openapi: 3.0.3
info:
  title: Corexel Delivery OS API
  version: "1"
  description: >
    Formal OpenAPI surface for public /api/v1 meta, COS verify, and integrator
    entry points. Versioned with product releases. Not a claim that every
    admin route is fully documented yet.
  contact:
    name: Corexel Platform
servers:
  - url: /
    description: Same-origin app
paths:
  /api/v1:
    get:
      summary: API v1 versioning meta
      operationId: getApiV1Meta
      tags: [Platform]
      responses:
        "200":
          description: Published version, aliases, quotas honesty
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: "1"
                  unitProbeOk:
                    type: boolean
  /api/v1/openapi:
    get:
      summary: OpenAPI document (YAML or JSON)
      operationId: getApiV1OpenApi
      tags: [Platform]
      parameters:
        - in: query
          name: format
          schema:
            type: string
            enum: [yaml, json]
            default: yaml
      responses:
        "200":
          description: OpenAPI 3 document
  /api/v1/ledger/{programId}/verify:
    get:
      summary: COS public ledger verify
      operationId: verifyLedger
      tags: [COS]
      parameters:
        - in: path
          name: programId
          required: true
          schema:
            type: string
        - in: query
          name: mode
          schema:
            type: string
            enum: [full, merkle]
      responses:
        "200":
          description: Verify payload (valid / flagged)
  /api/v1/org-units:
    get:
      summary: List org units (auth required)
      operationId: listOrgUnits
      tags: [COS]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Org unit list
    post:
      summary: Create org unit (auth required)
      operationId: createOrgUnit
      tags: [COS]
      security:
        - bearerAuth: []
      responses:
        "201":
          description: Created
  /api/v1/doa-policies:
    get:
      summary: List DOA policies (auth required)
      operationId: listDoaPolicies
      tags: [COS]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: DOA policy list
  /api/admin/platform/rbac-matrix:
    get:
      summary: Scoped delegated RBAC permission matrix
      operationId: getRbacMatrix
      tags: [RBAC]
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: viewerScopeType
          schema:
            type: string
            enum: [platform, business_unit, department, team, program]
        - in: query
          name: viewerScopeId
          schema:
            type: string
      responses:
        "200":
          description: Matrix filtered to viewing admin scope
  /api/admin/platform/rbac-roles:
    get:
      summary: List delegated RBAC role instances
      operationId: listRbacRoles
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Role instances
    post:
      summary: Create role instance (delegation-checked)
      operationId: createRbacRole
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Created instance
        "400":
          description: Delegation or template guard denied
  /api/programs/{projectId}/export:
    post:
      summary: Start program data export job
      operationId: createProgramExport
      tags: [Export]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Export ready with signed download URL
  /api/programs/export/download:
    get:
      summary: Download program export ZIP (signed token)
      operationId: downloadProgramExport
      tags: [Export]
      parameters:
        - in: query
          name: token
          required: true
          schema:
            type: string
      responses:
        "200":
          description: application/zip
  /api/admin/platform/phase3-onboarding:
    get:
      summary: Guided onboarding probe status + persisted state
      operationId: getPhase3Onboarding
      tags: [Onboarding]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Status + stepper state
    patch:
      summary: Update/resume guided onboarding state
      operationId: patchPhase3Onboarding
      tags: [Onboarding]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Updated state
  /api/admin/platform/phase3-webhook-delivery:
    get:
      summary: Phase 3 §10 webhook delivery probe status
      operationId: getPhase3WebhookDeliveryStatus
      tags: [Webhooks]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Probe status + recent deliveries
  /api/admin/pm/webhook-deliveries:
    get:
      summary: Filterable outbound CX webhook delivery log
      operationId: listWebhookDeliveries
      tags: [Webhooks]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Delivery rows (spec-shaped projection)
  /api/admin/platform/phase3-5-delegated-admin:
    get:
      summary: Phase 3.5-S1 buyer delegated-admin probe status
      operationId: getPhase35DelegatedAdminStatus
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Probe status
  /api/v1/rbac/matrix:
    get:
      summary: Buyer-shaped scoped RBAC matrix
      operationId: getBuyerRbacMatrix
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Scoped matrix + org units
  /api/v1/rbac/roles:
    get:
      summary: List buyer-visible RBAC role instances
      operationId: listBuyerRbacRoles
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Role instances
    post:
      summary: Create delegated role grant (subjectEmail optional)
      operationId: createBuyerRbacRole
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Created role instance
        "400":
          description: Delegation or validation denied
  /api/admin/platform/phase3-5-org-tree:
    get:
      summary: Phase 3.5-S2 org-tree foundation probe status
      operationId: getPhase35OrgTreeStatus
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Probe status
  /api/v1/org-tree:
    get:
      summary: Composite org units, reporting, job posts, program bindings
      operationId: getOrgTree
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Org-tree foundation payload
  /api/v1/reporting-relationships:
    get:
      summary: List reporting relationships
      operationId: listReportingRelationships
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Functional and program reporting edges
    post:
      summary: Upsert a reporting relationship (admin)
      operationId: upsertReportingRelationship
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Stored reporting edge
        "400":
          description: Schema invalid
  /api/v1/job-posts:
    get:
      summary: Job-post catalog mapped to existing RBAC templates
      operationId: listJobPosts
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Catalog rows
  /api/v1/programs/org-unit-bindings:
    get:
      summary: List program to org-unit metadata bindings
      operationId: listProgramOrgUnitBindings
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Metadata bindings
    post:
      summary: Upsert program org-unit metadata binding (admin)
      operationId: upsertProgramOrgUnitBinding
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Stored binding
        "422":
          description: Org unit missing or tenant mismatch
  /api/admin/platform/phase3-5-nc-org-tree:
    get:
      summary: Phase 3.5-S3 Nextcloud org-tree projection probe status
      operationId: getPhase35NcOrgTreeStatus
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Probe status
  /api/v1/nextcloud/org-tree:
    get:
      summary: Nextcloud org-tree projection plan (no MKCOL)
      operationId: getNextcloudOrgTreePlan
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Org-unit folder paths and program workspace layout
  /api/v1/nextcloud/org-tree/ensure:
    post:
      summary: Ensure org-unit folders only (admin MKCOL)
      operationId: ensureNextcloudOrgTree
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Ensured org-unit folders; existing flat CX folders are not moved
  /api/v1/openproject/org-tree:
    get:
      summary: OpenProject org-tree projection plan (no create)
      operationId: getOpenProjectOrgTreePlan
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Org-unit container identifiers and program parent layout; existing CX not reparented
  /api/v1/openproject/org-tree/ensure:
    post:
      summary: Ensure org-unit containers only (admin)
      operationId: ensureOpenProjectOrgTree
      tags: [RBAC]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Ensured org-unit containers; existing CX projects are not reparented
  /status:
    get:
      summary: Public shared status page (HTML)
      operationId: getPublicStatusPage
      tags: [Trust]
      responses:
        "200":
          description: HTML status + incident log
  /developers:
    get:
      summary: Docs site entry (HTML)
      operationId: getDevelopersDocs
      tags: [Docs]
      responses:
        "200":
          description: Versioned API + admin guide index
  /developers/openapi:
    get:
      summary: OpenAPI YAML on shared deploy surface
      operationId: getDevelopersOpenApi
      tags: [Docs]
      responses:
        "200":
          description: Same YAML as /api/v1/openapi (marketing-only safe)
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Admin / COS bearer where required
tags:
  - name: Platform
  - name: COS
  - name: Trust
  - name: Docs
  - name: RBAC
  - name: Export
  - name: Onboarding
  - name: Webhooks
