Organization APIs

Why This Exists

This document defines API responsibilities for the Organization Domain.

It does not define implementation code or final OpenAPI specifications. Final OpenAPI specs come later after domain behavior and integration boundaries are approved.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

The Organization Domain owns API responsibilities for Organization-owned data.

Business Value

Clear API responsibilities let other domains use Organization context without duplicating Organization ownership.

API Groups

API group	Responsibilities	Example endpoints
Organization Profile API	Create, read, update, and expose governed profile read models.	POST /organizations, GET /organizations/{organizationId}, PATCH /organizations/{organizationId}/profile
Organization User API	Manage Organization user associations and roles.	POST /organizations/{organizationId}/users, GET /organizations/{organizationId}/users
Director API	Manage director records and verification status.	POST /organizations/{organizationId}/directors, PATCH /organizations/{organizationId}/directors/{directorId}
Contact API	Manage contacts for procurement operations.	POST /organizations/{organizationId}/contacts, GET /organizations/{organizationId}/contacts
Address API	Manage physical, postal, branch, and operating addresses.	POST /organizations/{organizationId}/addresses, PATCH /organizations/{organizationId}/addresses/{addressId}
Service API	Manage organization services.	POST /organizations/{organizationId}/services, GET /organizations/{organizationId}/services
Product API	Manage organization products.	POST /organizations/{organizationId}/products, GET /organizations/{organizationId}/products
Capability API	Manage capability claims, evidence, and verification status.	POST /organizations/{organizationId}/capabilities, PATCH /organizations/{organizationId}/capabilities/{capabilityId}
Equipment API	Manage equipment resources.	POST /organizations/{organizationId}/equipment, GET /organizations/{organizationId}/equipment
Fleet API	Manage fleet assets.	POST /organizations/{organizationId}/fleet-assets, GET /organizations/{organizationId}/fleet-assets
Experience API	Manage past projects and client references.	POST /organizations/{organizationId}/past-projects, POST /organizations/{organizationId}/client-references
Procurement Preference API	Manage opportunity preferences and constraints.	GET /organizations/{organizationId}/procurement-preferences, PUT /organizations/{organizationId}/procurement-preferences
Organization Intelligence API	Expose graph, health, memory summaries, and AI-readable context.	GET /organizations/{organizationId}/intelligence-graph, GET /organizations/{organizationId}/health

API Responsibility Principles

1. APIs expose Organization-owned data through governed boundaries.
2. APIs must enforce Organization lifecycle and business rules.
3. APIs should publish domain events when meaningful business changes occur.
4. APIs should distinguish customer-supplied facts from AI-enriched suggestions.
5. APIs must support cross-domain reference without ownership leakage.

API Boundary Diagram

flowchart LR
    Consumers[Other Domains and UX]
    API[Organization APIs]
    Domain[Organization Domain]
    Events[Domain Events]
    ReadModels[Read Models]

    Consumers --> API
    API --> Domain
    Domain --> Events
    Domain --> ReadModels
    ReadModels --> Consumers

OpenAPI Scope

OpenAPI specifications will be produced later. This document defines domain responsibilities and example endpoint shapes only.