# First-party API contract. Official NymQue clients use the same documented API.
openapi: 3.1.0
info:
  title: NymQue API
  version: 0.3.8
  description: >
    This document describes the current first-party /api/v1 contract. Authenticated requests use a Bearer token
    and identify the active Space with X-Workspace-Id. Access is limited to active memberships in that Space.
    Official clients use this same contract. Invoice payment status comes from signed provider events or an
    authorized server-side recheck; a client cannot mark an invoice as paid. Public checkout behavior depends
    on the configured payment provider and supported payment methods.
    Error responses include the typed error envelope and preserve message and field-level validation details
    where applicable. Responses echo X-Request-Id. Money writes require an Idempotency-Key: matching retries
    replay the original response, while reuse with different values returns a conflict. Default rate limits
    are scoped to the actor and active Space, with route-specific limits taking precedence; 429 responses
    include Retry-After.
servers:
  - url: /api/v1
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer}
  parameters:
    WorkspaceId:
      name: X-Workspace-Id
      in: header
      required: true
      description: Active Space public identifier. Only Spaces where the caller has an active membership resolve.
      schema: {type: string, examples: [spc_01J9Z8Q4X3V6]}
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >
        Unique per user action (UUID recommended); reuse the same key to retry that action.
        Scoped to Space + actor + operation. Missing → 422 idempotency_key_required; same key with
        different values → 409 idempotency_key_conflict; same key and values → original response replayed.
      schema: {type: string, minLength: 1, maxLength: 100}
  headers:
    IdempotentReplayed:
      description: '`true` when the body is a stored replay of the first response for this Idempotency-Key.'
      schema: {type: string, enum: ['true', 'false']}
    RequestId:
      description: Request correlation id (also in error.request_id).
      schema: {type: string}
  responses:
    Forbidden:
      description: Permission denied (error.code=permission_denied, error.required_permission) or money step-up required (error=money_step_up_required)
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    MoneyWriteUnprocessable:
      description: Validation failed (validation_failed), missing Idempotency-Key (idempotency_key_required), key too long (idempotency_key_invalid), or a domain rule rejected the write (unprocessable)
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    IdempotencyConflict:
      description: Idempotency-Key already used for different values (error.code=idempotency_key_conflict)
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    RateLimited:
      description: Too many requests (error.code=rate_limited; error.details.retry_after seconds)
      headers:
        Retry-After: {schema: {type: integer}}
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
  schemas:
    Error:
      type: object
      required: [message, error]
      description: Standard /api/v1 error body. Top-level message/errors are kept for backward compatibility.
      properties:
        message: {type: string}
        errors:
          type: object
          description: Field-level validation errors (422 validation only)
          additionalProperties: {type: array, items: {type: string}}
        error:
          type: object
          required: [code, message, details, required_permission, request_id]
          properties:
            code:
              type: string
              pattern: '^[a-z][a-z0-9_]*$'
              examples: [unauthenticated, permission_denied, forbidden, not_found, workspace_required, workspace_not_found, workspace_access_revoked, conflict, idempotency_key_conflict, validation_failed, idempotency_key_required, idempotency_key_invalid, unprocessable, rate_limited, server_error]
            message: {type: string}
            details:
              type: object
              description: Client-safe context, e.g. fields (validation), any_of (permission sets), retry_after (429), header/operation (idempotency)
              additionalProperties: true
            required_permission: {type: [string, 'null'], examples: [expenses.manage]}
            request_id: {type: string}
    Task:
      type: object
      required: [id, workspace_id, title, status, priority]
      properties:
        id: {type: string, format: uuid}
        workspace_id: {type: string, format: uuid}
        title: {type: string}
        notes: {type: [string, 'null']}
        status: {enum: [open, in_progress, done, cancelled]}
        priority: {type: integer, minimum: 1, maximum: 4}
        due_at: {type: [string, 'null'], format: date-time}
    Session:
      type: object
      properties:
        token: {type: string}
        user: {type: object}
        workspace: {type: object}
        workspaces: {type: array, items: {type: object}}
        device_id: {type: [string, 'null']}
        idle_timeout_minutes: {type: integer, description: Untrusted-device idle lock in minutes}
        token_expires_minutes: {type: integer, description: Absolute Sanctum token lifetime}
    Customer:
      type: object
      properties:
        id: {type: string, format: uuid}
        public_id: {type: string}
        name: {type: string}
        email: {type: [string, 'null']}
        phone: {type: [string, 'null']}
        type: {enum: [person, business], description: "The API value `business` is the compatibility kind for an Organization."}
        payment_terms_days: {type: integer, minimum: 0, maximum: 3650}
        credit_limit_minor: {type: [integer, 'null'], minimum: 0, description: Approved customer exposure ceiling in integer minor units}
    Quote:
      type: object
      properties:
        id: {type: string, format: uuid}
        number: {type: string}
        status: {enum: [draft, sent, viewed, accepted, rejected, expired]}
        total_minor: {type: integer}
        currency: {type: string}
        payment_terms_days: {type: integer}
        credit_limit_minor_snapshot: {type: [integer, 'null']}
        accept_url: {type: [string, 'null']}
    Invoice:
      type: object
      properties:
        id: {type: string, format: uuid}
        public_id: {type: string}
        number: {type: string}
        status: {enum: [draft, sent, paid, void]}
        total_minor: {type: integer}
        currency: {type: string}
    Booking:
      type: object
      properties:
        id: {type: string, format: uuid}
        status: {type: string}
        starts_at: {type: string, format: date-time}
    SpaceAccess:
      type: object
      additionalProperties: false
      required: [space, gated, capabilities, aliases, computed_at]
      properties:
        space:
          type: object
          additionalProperties: false
          required: [id, public_id, type]
          properties:
            id: {type: string, format: uuid}
            public_id: {type: [string, 'null']}
            type: {type: string}
        gated: {type: boolean}
        capabilities:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [key, entitlement, grace_until, enablement]
            properties:
              key: {type: string, examples: [business.hrm]}
              entitlement: {enum: [active, grace, none]}
              grace_until: {type: [string, 'null'], format: date-time}
              enablement: {enum: [enabled, disabled, null]}
        aliases:
          type: object
          additionalProperties: {type: string}
          description: Service identifier mapped to a canonical capability key
        member:
          type: object
          description: Active Space membership projection; role is the stable authorization value and role_label is display-only.
          properties:
            role: {type: string, examples: [owner]}
            role_label: {type: string, examples: [Organization Owner]}
        computed_at: {type: string, format: date-time}
    Mission:
      type: object
      required: [id, title, brief, eligibility, evidence_rules, retention_days, status, reward]
      properties:
        id: {type: string, pattern: '^mis_'}
        title: {type: string, maxLength: 160}
        brief: {type: string}
        eligibility: {type: string}
        evidence_rules: {type: string}
        retention_days:
          type: integer
          minimum: 1
          maximum: 730
          description: Evidence and appeal text expire after this many days from their respective submission times.
        status: {type: string, enum: [draft, open, closed]}
        closes_at: {type: [string, 'null'], format: date-time}
        reward: {type: string, enum: [none]}
        organization:
          type: object
          properties:
            id: {type: [string, 'null']}
            name: {type: [string, 'null']}
    MissionParticipation:
      type: object
      description: Status and decision timestamps remain after participant and reviewer text expires.
      required: [id, status, evidence, evidence_expires_at, decision_reason, decision_reason_expires_at, appeal_note, appeal_note_expires_at, decided_at]
      properties:
        id: {type: string, pattern: '^mpt_'}
        mission_id: {type: [string, 'null']}
        status: {type: string, enum: [joined, submitted, approved, declined, appealed]}
        evidence: {type: [string, 'null'], description: Omitted from responses once its retention period has expired.}
        evidence_expires_at: {type: [string, 'null'], format: date-time}
        decision_reason: {type: [string, 'null'], description: Omitted from responses once its retention period has expired.}
        decision_reason_expires_at: {type: [string, 'null'], format: date-time}
        appeal_note: {type: [string, 'null'], description: Omitted from responses once its retention period has expired.}
        appeal_note_expires_at: {type: [string, 'null'], format: date-time}
        decided_at: {type: [string, 'null'], format: date-time}
        participant:
          type: object
          properties:
            id: {type: [string, 'null']}
            name: {type: [string, 'null']}
security: [{bearerAuth: []}]
paths:
  /auth/challenge:
    get:
      security: []
      responses: {'200': {description: Public Turnstile sitekey (anti-abuse, not authentication)}}
  /auth/register:
    post:
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, email, password, password_confirmation]
              properties:
                name: {type: string}
                email: {type: string, format: email}
                password: {type: string, minLength: 12}
                password_confirmation: {type: string}
                turnstile_token: {type: string}
                phone: {type: string}
                country_code: {type: string}
                national_number: {type: string}
      responses: {'201': {description: Identity and personal workspace created; email verification required}, '422': {description: Validation failed}}
  /auth/login:
    post:
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email: {type: string, format: email}
                password: {type: string}
                turnstile_token: {type: string}
                device_id: {type: string, format: uuid}
      responses:
        '200': {description: Session, verification challenge, or TOTP step}
        '422': {description: Invalid credentials}
  /auth/password/forgot:
    post:
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: {type: string, format: email}
                turnstile_token: {type: string}
      responses: {'200': {description: Always OK (no email enumeration); queued reset mail if the identity exists}}
  /auth/password/reset:
    post:
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, token, password, password_confirmation]
              properties:
                email: {type: string, format: email}
                token: {type: string}
                password: {type: string, minLength: 12}
                password_confirmation: {type: string}
      responses: {'200': {description: Password updated; existing sessions revoked}, '422': {description: Invalid or expired token}}
  /auth/verify:
    post:
      security: []
      responses: {'200': {description: Identifier verified and session issued}}
  /auth/resend:
    post:
      security: []
      responses: {'200': {description: New verification challenge}}
  /auth/logout:
    post:
      responses: {'204': {description: Token revoked}}
  /me:
    get:
      responses: {'200': {description: Current identity and active Spaces}, '401': {description: Idle lock or expired token}}
    patch:
      responses: {'200': {description: Display name completed}}
  /business-spaces:
    post:
      responses: {'201': {description: Organization Space created}}
  /business-profile:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Organization profile visible to authorized members}}
    patch:
      responses: {'200': {description: Profile updated}}
  /members:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Space memberships}}
  /invitations:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Pending Space invitations}}
    post:
      responses: {'201': {description: Invitation created; queued mail if email}}
  /me/invitations:
    get:
      responses: {'200': {description: Invitations for the signed-in identity}}
  /collection-saved-views:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Space-scoped Collection saved views (resource=customers|purchase_orders|supplier_invoices|invoices)}}
    post:
      responses: {'201': {description: Saved view created (customers.manage / finance.record)}}
  /collection-saved-views/{view}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    patch:
      responses: {'200': {description: Saved view updated}}
    delete:
      responses: {'200': {description: Saved view deleted}}
  /customers:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Customers in the active Organization Space (pipeline_stage, follow_up_due, type, q, sort filters)}, '403': {description: 'Requires business.crm.customer.view, business.crm.customer.manage, customers.manage or commerce.manage'}}
    post:
      responses: {'201': {description: Customer created; optional payment terms and integer-minor-unit credit ceiling are Space-scoped}}
  /customers/bulk:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    post:
      responses: {'200': {description: Authorized bulk assign_owner or set_pipeline_stage (customers.manage)}}
  /customers/{customer}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Customer history}, '403': {description: 'Requires business.crm.customer.view, business.crm.customer.manage, customers.manage or commerce.manage'}}
    patch:
      responses: {'200': {description: Customer updated}}
  /quotes:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Quotes}, '403': {description: 'Requires business.sales.order.view, business.sales.quotation.create or commerce.manage'}}
    post:
      responses: {'201': {description: Quote created; send=true queues QuoteSent mail}}
  /quotes/{quote}/send:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses:
        '200': {description: Quote marked sent after credit exposure check; queued customer mail}
        '422': {description: Approved customer credit limit would be exceeded}
  /invoices:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: AR invoices (Collection filters status, q, sort)}, '403': {description: 'Requires business.sales.invoice.view, commerce.manage or finance.read'}}
    post:
      responses: {'201': {description: Invoice created}}
  /invoices/{invoice}/send:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '200':
          description: Payment intent + checkout URL; queued invoice mail (the only API path that creates a Payment Intent)
          headers: {Idempotent-Replayed: {$ref: '#/components/headers/IdempotentReplayed'}}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {$ref: '#/components/responses/MoneyWriteUnprocessable'}
        '429': {$ref: '#/components/responses/RateLimited'}
  /invoices/{invoice}/cash-payment:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '201':
          description: Manual payment recorded; webhook is still the card/PSP authority
          headers: {Idempotent-Replayed: {$ref: '#/components/headers/IdempotentReplayed'}}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {$ref: '#/components/responses/MoneyWriteUnprocessable'}
        '429': {$ref: '#/components/responses/RateLimited'}
  /invoices/bulk:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [invoice_ids, action]
              properties:
                invoice_ids: {type: array, minItems: 1, items: {type: string, format: uuid}}
                action: {enum: [send, record_cash]}
                method: {enum: [cash, bank_transfer, pos, wallet]}
                notes: {type: [string, 'null'], maxLength: 1000}
      responses:
        '200': {description: Bulk send result}
        '201': {description: Bulk cash payments recorded}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {$ref: '#/components/responses/MoneyWriteUnprocessable'}
        '429': {$ref: '#/components/responses/RateLimited'}
  /invoices/{invoice}/remind:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses:
        '200': {description: Payment reminder queued to the customer email with the existing partner checkout link; reminder_count incremented}
        '422': {description: Invoice not sent, fully credited, customer has no email, or reminded within the last 24h}
  /expenses:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Space expenses (newest first)}, '403': {$ref: '#/components/responses/Forbidden'}}
    post:
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [description, amount_minor]
              properties:
                vendor_name: {type: [string, 'null'], maxLength: 160}
                category: {type: [string, 'null'], maxLength: 80}
                description: {type: string, maxLength: 255}
                amount_minor: {type: integer, minimum: 1, description: Integer minor units}
                incurred_on: {type: [string, 'null'], format: date}
      responses:
        '201': {description: Expense recorded + expense.recorded journal (requires expenses.manage)}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {$ref: '#/components/responses/MoneyWriteUnprocessable'}
        '429': {$ref: '#/components/responses/RateLimited'}
  /payroll-runs:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Latest payroll runs with lines}, '403': {$ref: '#/components/responses/Forbidden'}}
    post:
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '201': {description: Draft payroll run created from lines or compensation (requires members.manage)}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {$ref: '#/components/responses/MoneyWriteUnprocessable'}
        '429': {$ref: '#/components/responses/RateLimited'}
  /payroll-runs/{payrollRun}/approve:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '200': {description: Payroll run approved and posted (requires finance.record)}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {$ref: '#/components/responses/MoneyWriteUnprocessable'}
        '429': {$ref: '#/components/responses/RateLimited'}
  /payroll-runs/{payrollRun}/submit-disbursement:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '200': {description: Disbursement submitted to the licensed partner; awaiting partner confirmation (not paid)}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {$ref: '#/components/responses/MoneyWriteUnprocessable'}
        '429': {$ref: '#/components/responses/RateLimited'}
  /webhooks/payments/{provider}:
    post:
      security: []
      parameters:
        - name: provider
          in: path
          required: true
          schema: {type: string, enum: [simulated, interswitch, paystack]}
          description: Provider adapter identifier accepted by this webhook endpoint.
        - name: X-Nymque-Signature
          in: header
          required: false
          schema: {type: string}
          description: HMAC-SHA256 of the raw body for the simulated adapter (`sha256=` prefix allowed).
        - name: X-Interswitch-Signature
          in: header
          required: false
          schema: {type: string}
          description: HMAC-SHA512 of the raw JSON body. Clients cannot mark invoices paid; the signed webhook or an authorized server-side recheck is authoritative.
        - name: X-Paystack-Signature
          in: header
          required: false
          schema: {type: string}
          description: HMAC-SHA512 of the raw body. Clients cannot mark invoices paid; the signed webhook or an authorized server-side recheck is authoritative.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Provider JSON. Simulated uses event_id/type/reference/transaction_id/amount_minor/currency. Interswitch uses TRANSACTION.COMPLETED (adapter normalizes; PAN is not stored). Paystack uses charge.success; the adapter normalizes it.
      responses:
        '200': {description: PaymentSucceeded processed idempotently; duplicate provider event id is a no-op. Unknown Interswitch/Paystack events return data.status=ignored.}
        '401': {description: Invalid or missing webhook signature}
        '404': {description: Provider path does not match the bound adapter}
  /bookings:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Bookings in the active Organization Space}, '403': {description: 'Requires business.sales.order.view, business.sales.order.manage or commerce.manage'}}
  /bookings/{booking}/confirm:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Booking confirmed}}
  /bookings/{booking}/cancel:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Booking cancelled}}
  /offerings/{offering}/slots:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Bookable slots}}
  /tasks:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Workspace tasks}}
    post:
      responses: {'201': {description: Task created}, '404': {description: Workspace unavailable}}
  /tasks/{task}:
    patch:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Task updated}}
  /action-center:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: 'Overdue, upcoming, and unscheduled actions. Space-wide business queues (receivables, orders, contracts, purchasing, inventory, people, finance, enquiries, hiring) are empty unless the member holds the matching read or manage key; actor-scoped queues are always returned.'}}
  /finance/summary:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Accounts, balance in minor units, and budgets. Requires finance.read.}}
  /finance/accounts:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Create a Space-scoped native Money account. Requires finance.record.}}
  /finance/entries:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Record a Space-scoped money-in or money-out ledger entry against a native Money account. Requires finance.record.}}
  /money:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Organization finance overview. Requires finance.read.}}
  /payment-intents:
    get:
      summary: List payment intents in the active Organization Space
      description: >
        Requires finance.read. Returns at most 100 newest records. With no status
        filter, only pending and processing intents are returned. Partner webhooks
        are authoritative; this read operation cannot settle an invoice.
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - name: status
        in: query
        schema: {type: string, enum: [pending, processing, succeeded, failed, cancelled]}
      responses:
        '200':
          description: Intent queue and payment authority disclosure
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    maxItems: 100
                    items:
                      type: object
                      properties:
                        id: {type: string, format: uuid}
                        status: {type: string, enum: [pending, processing, succeeded, failed, cancelled]}
                        amount_minor: {type: integer}
                        currency: {type: string}
                        provider: {type: string}
                        provider_reference: {type: [string, 'null']}
                        checkout_url: {type: [string, 'null']}
                        invoice_id: {type: [string, 'null']}
                        invoice_number: {type: [string, 'null']}
                        invoice_public_id: {type: [string, 'null']}
                        invoice_status: {type: [string, 'null']}
                        created_at: {type: [string, 'null'], format: date-time}
                  meta:
                    type: object
                    properties:
                      contract:
                        type: object
                        properties:
                          partner_held: {const: true}
                          webhooks_authoritative: {const: true}
                          clients_never_mark_paid: {const: true}
                          flow: {type: string}
        '403': {description: finance.read permission denied}
        '422': {description: Invalid status or active Space is not an Organization}
  /expense-claims:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      summary: List Organization expense claims
      description: >
        Returns at most 100 newest claims in the active Organization. The mine
        and for_approval filters can be combined; for_approval selects pending
        claims assigned to the current active membership.
      parameters:
      - {name: mine, in: query, schema: {type: boolean}}
      - {name: for_approval, in: query, schema: {type: boolean}}
      responses:
        '200': {description: Object containing a data array of expense claims}
        '403': {description: 'Active membership required for membership filters; without mine or for_approval requires finance.read or expenses.manage'}
        '422': {description: Organization Space required}
    post:
      summary: Submit an expense claim for approval
      description: >
        Requires active Organization membership. Currency comes from the Space's
        base currency. The server routes the approver using spend rules. The new
        claim is pending; submission does not transfer money.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [description, amount_minor]
              properties:
                description: {type: string, maxLength: 255}
                amount_minor: {type: integer, minimum: 1, maximum: 9000000000000000}
                vendor_name: {type: [string, 'null'], maxLength: 160}
                category: {type: [string, 'null'], maxLength: 80}
                incurred_on: {type: [string, 'null'], format: date}
                request_note: {type: [string, 'null'], maxLength: 2000}
            example: {description: Client visit transport, amount_minor: 250000, incurred_on: '2026-10-14'}
      responses:
        '201': {description: Object containing the pending claim in data}
        '404': {description: Active membership not found}
        '422': {description: Invalid input, spend routing error, or Organization Space required}
  /expense-claims/{claim}/decide:
    post:
      summary: Approve or reject a pending expense claim
      description: >
        Only the assigned approver or an actor with expenses.manage, members.manage,
        or finance.record may decide. Approval enforces delegated spend limits,
        posts the staff reimbursement liability and sets reimbursement_status to
        awaiting_partner. It does not mark cash reimbursement paid.
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: claim, in: path, required: true, schema: {type: string}, description: Claim id or public_id}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision]
              properties:
                decision: {type: string, enum: [approved, rejected]}
                decision_note: {type: [string, 'null'], maxLength: 2000}
      responses:
        '200': {description: Object containing the decided claim in data}
        '403': {description: Actor cannot decide}
        '404': {description: Claim is missing or belongs to another Space}
        '422': {description: Invalid input, claim is no longer pending, delegated limit exceeded or currency mismatch, or Organization Space required}
  /tasks/{task}/delegate:
    post:
      summary: Delegate a task to an active member of the same Space
      description: Requires tasks.manage. The task is resolved inside the active Space.
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: task, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [assignee_user_id]
              properties:
                assignee_user_id:
                  type: [string, integer]
                  description: Prefer the usr_ public id; numeric identity ids remain accepted for compatibility. Must be an active member of this Space.
                keep_as_watcher: {type: boolean, default: true}
      responses:
        '200': {description: Updated task in data}
        '403': {description: tasks.manage permission denied}
        '404': {description: Task unavailable in the active Space}
        '422': {description: Invalid assignee or delegation input}
  /tasks/{task}/request-approval:
    post:
      summary: Request manager approval for an Organization task
      description: >
        Requires tasks.manage and an Organization Space. Uses the active manager
        of the assignee, then the requester's manager. Rejects a duplicate pending
        request and rejects requests with no resolvable manager.
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: task, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                request_note: {type: [string, 'null'], maxLength: 2000}
      responses:
        '201': {description: Pending Space approval in data}
        '403': {description: tasks.manage permission denied}
        '404': {description: Task unavailable in the active Space}
        '422': {description: Invalid input, duplicate pending approval, missing manager, or Organization Space required}
  /vault-documents:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Vault file metadata in the active Space. Requires vault.read.}}
    post:
      responses: {'201': {description: Encrypted upload. Requires vault.upload.}}
  /notes:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Notes in the active Space}}
    post:
      responses: {'201': {description: Note created. Requires notes.manage.}}
  /notes/{note}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Note}}
    patch:
      responses: {'200': {description: Note updated. Requires notes.manage.}}
  /connect/threads:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Connect threads. Author is usr_ + name; phones are never returned.}}
    post:
      responses: {'201': {description: Thread created. Requires connect.post.}}
  /connect/threads/{thread}:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Thread with messages}}
  /connect/threads/{thread}/messages:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Message posted. Requires connect.post.}}
  /meetings:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Meeting records in the Space}}
    post:
      responses: {'201': {description: Space-scoped meeting record and participant details. Requires meet.manage.}}
  /meetings/{meeting}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Meeting record}}
    delete:
      responses: {'204': {description: Deleted. Requires meet.manage.}}
  /mail/messages:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Space inbox of platform and outbound mail}}
    post:
      responses: {'201': {description: Compose via MailGateway and record in inbox. Requires mail.send. Not IMAP.}}
  /mail/messages/{mailMessage}:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Mail row}}
  /automation/rules:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Automation rules configured for the active Space. Requires automation.manage.}}
  /automation/rules/{automationRule}:
    patch:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Enable or disable a rule}}
  /subscription:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Return the active Space plan and operational usage meters. This request does not initiate billing.}}
  /me/shield:
    get:
      responses: {'200': {description: Reachability and visibility. Does not claim E2EE everywhere.}}
    patch:
      responses: {'200': {description: Update phone discovery, visibility, and Connect reachability}}
  /me/onboarding/dismiss:
    post:
      responses: {'200': {description: Persist onboarding dismiss; checklist remains available on /me}}
  /me/notifications:
    get:
      responses: {'200': {description: In-app attention notifications for the signed-in identity}}
  /me/notifications/read-all:
    post:
      responses: {'200': {description: Mark all notifications read}}
  /me/notifications/{notification}/read:
    post:
      parameters:
        - name: notification
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses: {'200': {description: Mark one notification read}}
  /me/push-tokens:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token, platform]
              properties:
                token: {type: string, minLength: 16, maxLength: 512}
                platform: {enum: [ios, android, web]}
      responses: {'201': {description: Device push token registered for Connect alerts}}
    delete:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token: {type: string, minLength: 16, maxLength: 512}
      responses: {'200': {description: Device push token removed}}
  /auth/identifiers/link:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Link an additional email or phone onto the same usr_ (step-up OTP). Not automatic merge of two usr_ rows.
      responses: {'200': {description: Challenge issued or identifier linked}, '422': {description: Collision or validation failed}}
  /quotes/{quote}/cancel:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses:
        '200': {description: Quote cancelled — status cancelled; cannot be sent or accepted. QuoteCancelled DomainEvent.}
        '422': {description: Quote already closed (accepted/rejected/expired/cancelled)}
  /invoices/{invoice}/write-off:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      summary: Write an unpaid invoice off to bad-debt expense
      description: >
        The honest exit for an uncollectible receivable — distinct from a
        credit note (which reverses revenue): posts invoice.write_off
        (Dr 5900 Bad Debt Expense, Cr 1100 AR) for the REMAINING outstanding
        balance (net of credit-note applications and authorized returns) and
        closes the invoice as written_off. Written-off invoices exit
        reminders, aging buckets, AR attention and credit caps. Step-up auth
        required. Audit: invoice.written_off + InvoiceWrittenOff event.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason: {type: string, maxLength: 255}
      responses:
        '200': {description: Invoice written off (status=written_off, written_off_at, write_off_reason)}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {description: Invoice not in the active Space}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {$ref: '#/components/responses/MoneyWriteUnprocessable'}
        '429': {$ref: '#/components/responses/RateLimited'}
  /invoices/{invoice}/partner-refund:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '200': {description: Partner refund instructed and reversal journal appended. The invoice remains paid; clients cannot reverse payment status.}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {$ref: '#/components/responses/MoneyWriteUnprocessable'}
        '429': {$ref: '#/components/responses/RateLimited'}
  /invoices/{invoice}/credit-notes:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Credit notes for the invoice + meta.creditable_minor remaining}, '403': {description: 'Requires business.sales.invoice.view, commerce.manage or finance.read'}}
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '201': {description: Credit note issued (cn_, CN- number); posts invoice.credit_note journal debit revenue / credit AR. Invoice row never mutated.}
        '403': {$ref: '#/components/responses/Forbidden'}
        '409': {$ref: '#/components/responses/IdempotencyConflict'}
        '422': {description: 'Invoice draft/unsent, amount exceeds remaining creditable balance (net of authorized sales returns), unknown reason, or missing Idempotency-Key', content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
        '429': {$ref: '#/components/responses/RateLimited'}
  /credit-notes:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Space-scoped credit notes (filter status=issued|void)}, '403': {description: 'Requires business.sales.invoice.view, commerce.manage or finance.read'}}
  /credit-notes/{creditNote}:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Credit note with invoice + customer + applied_invoice_id/applied_invoice_number when applied}, '403': {description: 'Requires business.sales.invoice.view, commerce.manage or finance.read'}}
  /credit-notes/{creditNote}/apply:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      summary: Apply an issued credit note (fully or partially) to another open invoice of the same customer
      description: >
        Document-level reallocation inside accounts receivable — no journal posts.
        Without amount_minor the remaining balance applies up to the target's
        outstanding headroom; explicit amount_minor must fit both. The note stays
        issued while partially allocated and flips to applied when exhausted;
        the source invoice's receivable restores by the applied amount and the
        target's effective credit grows. Same customer and currency required;
        target must be sent. Step-up auth required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [invoice_id]
              properties:
                invoice_id: {type: string, description: Target invoice (inv_)}
                amount_minor: {type: integer, minimum: 1, description: Optional — defaults to min(remaining, target outstanding)}
      responses:
        '200': {description: "Allocation recorded — applied_minor/remaining_minor + applications[] on the note"}
        '422': {description: Note void/fully applied, different customer or currency, target is the source or already allocated from this note, draft/unsent, no headroom, or amount exceeds remaining creditable}
        '404': {description: Target invoice not in the active Space}
  /credit-notes/{creditNote}/void:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses:
        '200': {description: Note voided + journal reversed (corrections by reversal, never deleted). Applied notes restore both the source and applied invoices' effective balances.}
        '422': {description: Note already void or recovery hold active}
  /accounting/receivables-payables:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      summary: AR/AP overview with honest aging buckets
      description: >
        receivables rows carry outstanding_minor (net of credit-note
        applications and authorized returns — receivables_total_minor is the
        net sum, never gross), due_on, days_overdue and bucket.
        supplier_payables lists matched/payment_pending supplier invoices at
        net_minor (amount − issued debit notes − authorized returns);
        payables/payables_total_minor remain the recorded-expenses view.
        receivables_aging and payables_aging bucket net amounts into
        current / days_1_30 / days_31_60 / days_61_90 / days_90_plus plus an
        overdue total.
      responses:
        '200': {description: Space-scoped AR/AP overview with aging summaries}
        '422': {description: This action requires an Organization Space}
  /accounting/journals:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      summary: Post a manual journal entry (adjusting entry)
      description: >
        For accruals, reclassifications and corrections no domain record
        covers — the canonical ledger.
        Lines must balance (sum debits = sum credits) in integer minor
        units; every account_code must exist in the Space chart; a locked
        posting date is refused (422). idempotency_key is required and
        dedupes the posting. finance.record + recovery-hold + step-up on
        the total debit amount. Posted journals are never edited — use
        /accounting/journals/{id}/reverse. Audit: journal.manual_posted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [idempotency_key, description, lines]
              properties:
                idempotency_key: {type: string, maxLength: 100}
                description: {type: string, maxLength: 255}
                posting_date: {type: string, format: date}
                currency: {type: string, description: '3-letter code; defaults to the Space base_currency'}
                lines:
                  type: array
                  minItems: 2
                  items:
                    type: object
                    required: [account_code, direction, amount_minor]
                    properties:
                      account_code: {type: string, maxLength: 20}
                      direction: {type: string, enum: [debit, credit]}
                      amount_minor: {type: integer, minimum: 1}
                      dimension_value_ids: {type: array, items: {type: string}}
      responses:
        '201': {description: Journal posted (type=manual, provenance=manual)}
        '422': {description: Unbalanced lines, unknown account, locked period, or a Space that is not an Organization Space}
  /purchase-orders/{purchaseOrder}/supplier-invoices:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      summary: Record a supplier invoice against a received purchase order
      description: >
        Requires the PO to be partially_received or received. due_on is
        optional — when omitted it derives from the supplier's
        payment_terms_days (recording date + days). Invoice payloads carry
        due_on, overdue (past due while matched/payment_pending),
        debited_minor and net_minor (amount minus issued debit notes).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [invoice_number, amount_minor, currency]
              properties:
                invoice_number: {type: string, maxLength: 96}
                amount_minor: {type: integer, minimum: 1}
                currency: {type: string, minLength: 3, maxLength: 3}
                due_on: {type: [string, 'null'], format: date, description: 'Explicit due date; defaults to supplier payment terms'}
      responses:
        '201': {description: Supplier invoice recorded (sin_), pending match}
        '422': {description: PO not received/cancelled}
  /supplier-invoices/{supplierInvoice}/returns:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Authorized returns-to-vendor for the invoice + meta.returnable_minor (shared with debit notes)}}
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      summary: Authorize a return-to-vendor purchase return
      description: >
        Records goods sent back against a matched/payment_pending/paid
        supplier invoice and posts a supplier_invoice.purchase_return
        journal (Dr AP 2000, Cr purchases 5000). The supplier invoice row is
        never mutated. Returns and debit notes share the same debitable cap
        (amount − issued debits − authorized returns), so the two correction
        primitives can never double-reduce the payable. Step-up auth
        required. Supplier refunds settle via the licensed partner.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount_minor, reason]
              properties:
                amount_minor: {type: integer, minimum: 1}
                reason: {type: string, maxLength: 255}
      responses:
        '201': {description: Return authorized + journal posted; invoice payload nets it via returned_minor/net_minor}
        '422': {description: Invoice unmatched or amount exceeds remaining payable}
        '404': {description: Invoice not in the active Space}
  /supplier-invoices/{supplierInvoice}/debit-notes:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Debit notes for the supplier invoice + meta.debitable_minor remaining}}
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      summary: Issue a supplier debit note for a purchase return
      description: >
        Payable-side mirror of sales credit notes. Posts a
        supplier_invoice.debit_note journal (Dr AP 2000, Cr purchases 5000);
        the supplier invoice row is never mutated. Only matched,
        payment_pending, or paid invoices may be debited — match first so the
        payable exists. Payment instructions settle the net payable. Step-up
        auth required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount_minor, reason]
              properties:
                amount_minor: {type: integer, minimum: 1}
                reason: {type: string, enum: [returned_goods, short_delivery, quality_issue, pricing_error, order_cancellation, overbilling, other]}
                notes: {type: string, maxLength: 2000}
      responses:
        '201': {description: Debit note issued (dn_, DN- number) + journal posted}
        '422': {description: Invoice unmatched, amount exceeds remaining debitable balance, or unknown reason}
  /debit-notes:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Space-scoped debit notes (filter status=issued|void)}}
  /debit-notes/{debitNote}:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Debit note with supplier invoice + supplier names}}
  /debit-notes/{debitNote}/void:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses:
        '200': {description: Debit note voided + journal reversed (corrections by reversal, never deleted)}
        '422': {description: Note already void or recovery hold active}
  /space/access:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      summary: Capability slice of the Space access projection
      description: >
        Any active member of the Space in X-Workspace-Id; other Spaces 404, suspended members 403.
        Read-only (never materializes entitlement rows). gated=false means the Space has no
        entitlement or enablement records yet, so clients keep their compatibility enablement and
        capabilities is empty. entitlement is active, grace (lapsed less than 90 days ago: read and
        export only, owner decision Q2) or none. enablement is the owner's explicit choice, or null
        when the owner never toggled it. aliases maps service identifiers to canonical keys.
        Permissions, nav and widgets arrive with the effective-access resolver.
      responses:
        '200':
          description: Space access (capabilities)
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: {$ref: '#/components/schemas/SpaceAccess'}
        '400': {description: X-Workspace-Id missing}
        '403': {description: Membership is not active}
        '404': {description: Not a member of that Space}
  /space/storage:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Space storage usage by class and quota. Personal Vault excluded from employer quota.}}
    patch:
      responses: {'200': {description: Update Space quota (owner/admin). Requires space settings permission.}}
  /space/storage/cleanup:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'202': {description: Enqueue storage cleanup job (not a full purge product)}}
  /missions:
    get:
      summary: List open missions
      responses:
        '200':
          description: Mission terms available to authenticated members. No monetary rewards are offered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/Mission'}}
                  rewards: {type: string, enum: [not_offered]}
  /missions/{mission}/join:
    post:
      parameters:
        - name: mission
          in: path
          required: true
          schema: {type: string}
      responses:
        '201':
          description: Join an open mission; participation is limited to one per person.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {$ref: '#/components/schemas/MissionParticipation'}
        '404': {description: Mission is unavailable or closed}
  /me/missions:
    get:
      summary: List the signed-in person's mission participations
      responses:
        '200':
          description: Personal participation history; expired evidence and appeal text are not returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/MissionParticipation'}}
  /me/mission-participations/{participation}/submit:
    post:
      parameters:
        - name: participation
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [evidence]
              properties:
                evidence: {type: string, minLength: 5, maxLength: 5000}
      responses:
        '200':
          description: Submit evidence. Evidence and reviewer decision text are retained for retention_days from their respective submission or decision.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {$ref: '#/components/schemas/MissionParticipation'}
        '404': {description: Participation is not owned by the caller}
        '422': {description: Participation cannot accept evidence}
  /me/mission-participations/{participation}/appeal:
    post:
      parameters:
        - name: participation
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [note]
              properties:
                note: {type: string, minLength: 5, maxLength: 1000}
      responses:
        '200':
          description: Appeal a declined decision. Appeal text is retained for the mission's retention_days from submission.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {$ref: '#/components/schemas/MissionParticipation'}
        '404': {description: Participation is not owned by the caller}
        '422': {description: Participation cannot be appealed}
  /space/missions:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      summary: List missions owned by the active Space
      description: Requires members.manage; returns only missions in X-Workspace-Id.
      responses:
        '200':
          description: Space-scoped mission list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/Mission'}}
    post:
      summary: Create a draft mission in the active Space
      description: Requires members.manage. Mission rewards are not supported.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, brief, eligibility, evidence_rules, retention_days]
              properties:
                title: {type: string, maxLength: 160}
                brief: {type: string, minLength: 20, maxLength: 4000}
                eligibility: {type: string, minLength: 5, maxLength: 2000}
                evidence_rules: {type: string, minLength: 5, maxLength: 2000}
                retention_days: {type: integer, minimum: 1, maximum: 730}
                closes_at: {type: [string, 'null'], format: date-time}
      responses:
        '201':
          description: Draft mission created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {$ref: '#/components/schemas/Mission'}
        '403': {description: Permission denied}
        '422': {description: Invalid mission terms}
  /space/missions/{mission}/open:
    post:
      parameters:
        - {$ref: '#/components/parameters/WorkspaceId'}
        - name: mission
          in: path
          required: true
          schema: {type: string}
      responses:
        '200': {description: Open a draft mission for participation}
        '403': {description: Permission denied}
        '404': {description: Mission is not in the active Space}
        '422': {description: Mission cannot be opened}
  /space/missions/{mission}/close:
    post:
      parameters:
        - {$ref: '#/components/parameters/WorkspaceId'}
        - name: mission
          in: path
          required: true
          schema: {type: string}
      responses:
        '200': {description: Close an open mission}
        '403': {description: Permission denied}
        '404': {description: Mission is not in the active Space}
        '422': {description: Mission is already closed}
  /space/missions/{mission}/participations:
    get:
      parameters:
        - {$ref: '#/components/parameters/WorkspaceId'}
        - name: mission
          in: path
          required: true
          schema: {type: string}
      description: Requires members.manage; participation rows and participant identity are limited to the active Space.
      responses:
        '200':
          description: Mission submissions for review
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/MissionParticipation'}}
        '404': {description: Mission is not in the active Space}
  /space/mission-participations/{participation}/decide:
    post:
      parameters:
        - {$ref: '#/components/parameters/WorkspaceId'}
        - name: participation
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision, reason]
              properties:
                decision: {type: string, enum: [approved, declined]}
                reason: {type: string, minLength: 5, maxLength: 1000}
      responses:
        '200': {description: Approve or decline a submission; a reason is required}
        '403': {description: Permission denied}
        '404': {description: Participation is not in the active Space}
        '422': {description: Participation cannot be decided}
  /business-profile/promote:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Promote and referral share payload for Discover}}
  /business-profile/promote/shared:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Acknowledge that the operator shared the Discover link}}
  /connect/threads/{thread}/attention:
    patch:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                pinned: {type: boolean}
                muted: {type: boolean}
      responses: {'200': {description: Pin or mute thread for the viewer only}}
  /vault-documents/{vaultDocument}/favorite:
    patch:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [favorited]
              properties:
                favorited: {type: boolean}
      responses: {'200': {description: Toggle favorite for the viewer. Requires vault.read.}}
  /vault-documents/{vaultDocument}/shares:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Share document metadata with a Space member. Ownership unchanged.}}
  /vault-documents/{vaultDocument}/shares/{userPublicId}:
    delete:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Revoke share}}
  /ai/tools:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Typed Ask tools available in the active Space (grants ≤ human permissions)}}
  /customers/{customer}/timeline:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Space-scoped customer activity projection over commerce events, bookings, and notes}, '403': {description: 'Requires business.crm.customer.view, business.crm.customer.manage, customers.manage or commerce.manage'}}
  /ai/grants:
    put:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Update Ask tool grants for the actor in this Space}}
  /ai/tools/execute:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Execute one typed tool via policy engine. No SQL. No payments.execute.}}
  /ai/chat:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Ask NymQue conversation handled by a server-side provider adapter. Provider credentials stay server-side; the public /ask route lists available capabilities.}}
  /ai/traces:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Space-scoped AI execution observability with requester helpfulness and governance review annotations. Stores route/model/tool/approval metadata and latency only; no prompt text, raw tool arguments, or tool results.}}
  /ai/traces/{trace}/feedback:
    put:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Requester-owned helpful/not-helpful feedback for one trace. Feedback does not change permissions or execution policy.}}
  /ai/traces/{trace}/review:
    put:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses:
        '200': {description: Governance review annotation pass|needs_review|fail for one trace. Descriptive only; does not automatically mutate actor policy.}
        '403': {description: ai.governance.manage or equivalent Space governance authority required}
  /ai/quality:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: 1-365 day AI quality summary with completion/helpfulness/review rates, actor/tool reliability, latency, errors, and daily trend.}}
  /ai/evaluations:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Governance-only evaluation suites with cases, manual/automated runs, deterministic assertion outcomes, promotion-gate status, release-enforcement policy, and recent CI/predeploy release checks.}}
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Create an actor/model/prompt/orchestration evaluation suite, thresholds, and optional release-enforcement mode (manual|ci|predeploy|both) with changed-file patterns. Model targets may use provider@model syntax.}}
  /ai/evaluations/{suite}/enforcement:
    put:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses:
        '200': {description: Update governance-controlled release enforcement for a suite. manual disables release checks; ci/predeploy/both opt the suite into matching changed-file gates. Empty change_patterns uses target-kind defaults.}
        '403': {description: AI governance permission required.}
  /ai/evaluations/{suite}/cases:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Add a sanitized regression scenario with machine assertions for status, route, provider/model, tools, approval, latency, and response constraints.}}
  /ai/evaluations/{suite}/runs:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Record a manual baseline/candidate result set for the promotion gate.}}
  /ai/evaluations/{suite}/execute:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Automatically execute active regression cases through governed Ask in dry-run mode. Read tools may run; writes are simulated or approval-only. Stores privacy-safe observations and feeds deterministic scores directly into the promotion gate.}}
  /ai/evaluation-runs/{run}/promote:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses:
        '200': {description: Explicitly promote an eligible candidate version and supersede the previous promoted run.}
        '409': {description: Candidate is blocked by the evaluation gate.}
  /professional/profile:
    get:
      responses: {'200': {description: 'Person-owned professional profile information. Hiring workflows are not included.'}}
    patch:
      responses: {'200': {description: Update headline/summary/availability/discoverability}}
  /professional/experiences:
    post:
      responses: {'201': {description: Add experience row to the signed-in identity profile}}
  /professional/experiences/{experience}:
    delete:
      parameters:
        - name: experience
          in: path
          required: true
          schema: {type: string}
      responses: {'200': {description: Remove own experience row}}
  /professional/skills:
    post:
      responses: {'201': {description: Attach a skill (self-reported) to the Professional profile}}
  /platform/capabilities:
    get:
      responses: {'200': {description: Platform capability catalog. Entitlements never override Space permissions.}}
  /location/geocode:
    get:
      parameters:
        - name: q
          in: query
          required: true
          schema: {type: string}
      responses: {'200': {description: Provider-neutral location lookup when a supported geocoding provider is configured}}
  /orders/{order}/fulfill:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Fulfil order (inventory issue + FulfilmentCompleted). Requires commerce.manage.}}
  /orders/{order}/confirm-delivery:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: 'Confirm delivery-ready details and request shipment through an authorized logistics provider. Delivery status is confirmed by the provider.'}}
  /orders/{order}/returns:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      summary: Authorize a sales return against the order's receivable
      description: >
        Posts a sales_return_authorized journal (Dr revenue 4050, Cr AR 1100) and
        records a sales_returns row (status authorized). Cumulative cap: returns
        may not exceed the order's remaining returnable balance, and when the
        order has an invoice the amount must fit the invoice's remaining
        creditable balance (total minus effective credit-note allocations and
        earlier returns) so AR can never be over-credited. The invoice reports
        the reduction as returned_minor; invoice status is never mutated.
        Requires commerce.manage.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount_minor, reason]
              properties:
                amount_minor: {type: integer, minimum: 1}
                reason: {type: string, maxLength: 255}
      responses:
        '201': {description: Return authorized (sales_returns row + reversal journal id)}
        '422': {description: Amount exceeds the order's remaining returnable balance or the invoice's remaining creditable balance}
  /material-requests:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: 'List Material Requests in the active Space. Requires inventory.manage.'}}
    post:
      responses: {'201': {description: 'Create material demand for SKU, quantity and location. The application service coordinates a transfer or purchase.'}}
  /material-requests/{materialRequest}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show Material Request in active Space only (cross-Space 404)}}
  /material-requests/{materialRequest}/resolve:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: 'Spawn stock transfer and/or purchase requisition for an open line. Reuses inventory + P2P services.'}}
  /goods-receipts:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: 'Accepted Space-scoped goods receipts with putaway lines and landed-cost status. Requires inventory.manage.'}}
  /landed-cost-vouchers:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: 'Space-scoped applied landed-cost vouchers and exact integer allocations.'}}
  /goods-receipts/{goodsReceipt}/landed-costs:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    post:
      responses:
        '201': {description: 'Allocate freight, duty or other integer minor-unit charges by line value or quantity; update receipt lots and valuation.'}
        '409': {description: 'Voucher already exists or receipt stock moved; controlled reversal/adjustment required.'}
  /partner-shipments:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List shipment records in the active Space. Requires commerce.manage.}}
    post:
      responses: {'201': {description: Create a shipment record; partner booking depends on a supported logistics provider}}
  /partner-shipments/{shipment}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show shipment in active Space only (cross-Space 404)}}
  /partner-shipments/{shipment}/instruct:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Request shipment booking through a configured logistics provider}}
  /partner-shipments/{shipment}/tracking-events:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: 'Append a normalized tracking event'}}
  /partner-intents:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List partner-service requests in the active Space}}
    post:
      responses: {'201': {description: Create a partner-service request in the active Space}}
  /partner-intents/{intent}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show partner intent in active Space only (cross-Space 404)}}
  /partner-intents/{intent}/instruct:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Forward the request to a configured service provider where supported}}
  /kernel/relationships:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List kernel relationships visible to the active Space}}
    post:
      responses: {'201': {description: Record person↔org, org↔org, or person↔person relationship edge}}
  /connect/search:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      parameters:
        - name: q
          in: query
          required: true
          schema: {type: string}
      responses: {'200': {description: Search Connect message bodies in Space-visible threads}}
  /connect/threads/{thread}/messages/{message}/reactions:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Add a reaction to a message}}
  /platform/applications:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: 'List applications available in the active Space. Public application registration and OAuth authorization are not currently available.'}}
  /professional/opportunities:
    get:
      responses: {'200': {description: Discover published hiring opportunities (identity-scoped)}}
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Create a hiring opportunity draft in the active Organization Space}}
  /professional/hiring/opportunities:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List hiring opportunities owned by the active Space}}
  /professional/opportunities/{opportunity}/publish:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Publish opportunity for Professional discover/apply}}
  /professional/opportunities/{opportunity}/applications:
    post:
      responses: {'201': {description: Submit an application with the selected profile details}}
  /professional/applications/{application}:
    get:
      responses: {'200': {description: Show application visible to applicant or hiring Space}}
  /professional/applications/{application}/shortlist:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Advance application to shortlist}}
  /professional/applications/{application}/reject:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Reject application}}
  /professional/applications/{application}/schedule-interview:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Mark interview scheduled}}
  /professional/applications/{application}/offers:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Issue professional offer (no invented public ₦ salary required)}}
  /professional/offers:
    get:
      responses: {'200': {description: List offers for the signed-in identity}}
  /professional/offers/{offer}/accept:
    post:
      responses: {'200': {description: Accept offer to EMPLOYED_BY relationship + membership floor}}
  /professional/offers/{offer}/decline:
    post:
      responses: {'200': {description: Decline offer}}
  /value-requests:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    post:
      responses: {'201': {description: Create a structured request in the active Space. Follow-up assistant actions require an approved grant.}}
  /value-requests/{valueRequest}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show ValueRequest in active Space (cross-Space 404)}}
  /value-requests/{valueRequest}/resolve:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Resolve structured need to platform capability (no auth bypass)}}
  /commerce/reviews:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    post:
      responses: {'201': {description: Record commerce review after fulfil or delivered shipment}}
  /commerce/reviews/{review}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show review in active Space only}, '403': {description: 'Requires business.sales.order.view, business.sales.order.manage or commerce.manage'}}
  /commerce/disputes:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List active-Space commerce disputes, newest first, capped at 100}, '403': {description: 'Requires business.sales.order.view, business.sales.order.manage or commerce.manage'}}
    post:
      responses: {'201': {description: Open a commerce dispute record in the active Space}}
  /commerce/disputes/{dispute}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show dispute in active Space only}, '403': {description: 'Requires business.sales.order.view, business.sales.order.manage or commerce.manage'}}
  /orders/{order}/disputes:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Open dispute bound to an order in the active Space}}
  /orders/{order}/operating-record:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Space-scoped order-to-cash stage, blockers, next actions, timeline and partner-confirmed financial truth}, '403': {description: 'Requires business.sales.order.view, business.sales.order.manage or commerce.manage'}}
  /purchase-orders/{purchaseOrder}/operating-record:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Finance-authorized, Space-scoped procure-to-pay stage, blockers, next actions, timeline and partner-confirmed settlement truth}}
  /suppliers/scorecards:
    get:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Finance-authorized supplier reliability read models derived from on-time receipt and first-pass three-way-match evidence}}
  /money/transfer-beneficiaries:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Store a transfer beneficiary for an authorized partner workflow}}
  /money/transfer-instructions:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Submit a transfer instruction for server-side policy checks and an authorized partner. NymQue does not hold funds; the partner confirms execution.}}
  /money/global/fx-quotes:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List FX quote records in the active Space; availability depends on a configured provider}}
    post:
      responses: {'201': {description: Request an FX quote from a configured, licensed provider. NymQue does not custody or exchange currency.}}
  /money/global/fx-quotes/{quote}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show FX quote in active Space only (cross-Space 404)}}
  /money/digital-assets/balances:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Partner-held digital asset positions view. Never stores keys.}}
  /money/digital-assets/orders:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List digital-asset order records in the active Space}}
    post:
      responses: {'201': {description: Create a digital-asset order request for a configured licensed partner; NymQue does not custody assets or hold keys}}
  /money/digital-assets/orders/{order}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show digital-asset order in active Space only}}
  /money/digital-assets/orders/{order}/instruct:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Forward an order request to a configured licensed provider where available}}
  /money/financial-data/links:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List financial-data connections and consent records in the active Space}}
    post:
      responses: {'201': {description: Create a financial-data connection request after the required consent}}
  /money/financial-data/links/{link}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show financial-data link in active Space only}}
  /money/financial-data/links/{link}/instruct:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Send a connection request to a configured financial-data provider where available}}
  /money/financial-data/links/{link}/sync:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Add the application to the hiring Space shortlist}}
  /finance/goals:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List finance goals in Personal Space}}
    post:
      responses: {'201': {description: Create finance goal (integer minor units)}}
  /finance/goals/{goal}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show finance goal in active Space only}}
  /shield/decisions:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List risk decisions and required next actions for the active Space}}
  /shield/decisions/{decision}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show Shield decision in active Space only}}
  /economics/fee-rules:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: List draft fee rules configured for the active Space}}
  /economics/fee-quote:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Quote a fee using the rules configured for the active Space}}
  /economics/usage:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Record economics usage meter event}}
  /identity/verification/assert:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'200': {description: Record identity-verification evidence returned by an authorized provider adapter}}
  /kernel/relationships/{relationship}:
    parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
    get:
      responses: {'200': {description: Show kernel relationship visible to active Space (cross-Space 404)}}
  /kernel/relationships/{relationship}/evidence:
    post:
      parameters: [{$ref: '#/components/parameters/WorkspaceId'}]
      responses: {'201': {description: Attach evidence artifact metadata to a relationship edge}}
  /ai/router:
    get:
      responses: {'200': {description: ModelRouter status (provider preference + fallback). Not an agent marketplace.}}

  /service-cases:
    get:
      summary: Search the active Organization's service cases
      parameters:
        - {$ref: '#/components/parameters/WorkspaceId'}
        - {name: q, in: query, schema: {type: string, maxLength: 255}, description: Subject or public reference search}
        - {name: status, in: query, schema: {type: string, enum: [open, in_progress, pending_customer, resolved, closed]}}
        - {name: priority, in: query, schema: {type: string, enum: [low, normal, high, urgent]}}
        - {name: unassigned, in: query, schema: {type: boolean}, description: Only cases without an assignee}
        - {name: page, in: query, schema: {type: integer, minimum: 1}}
      responses:
        '200': {description: 'Space-scoped data array (50 per page) and meta with current_page, last_page, total.'}
        '422': {description: Invalid filters or non-Organization Space}
  /service-cases/{serviceCase}:
    parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: serviceCase, in: path, required: true, schema: {type: string}}
    get:
      summary: Case detail with authorized activity and work orders
      responses:
        '200': {description: 'Case data with timeline, knowledge and work_orders. Internal notes and can_add_internal_note depend on members.manage.'}
        '404': {description: Case does not exist in the active Space}
  /service-cases/{serviceCase}/notes:
    post:
      summary: Append a staff-only internal note
      parameters:
        - {$ref: '#/components/parameters/WorkspaceId'}
        - {name: serviceCase, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body: {type: string, minLength: 1, maxLength: 5000, description: Nonblank investigation text; whitespace is trimmed}
      responses:
        '201': {description: 'Appended event in data with type, details.body, actor_id, created_at. No customer delivery.'}
        '403': {description: Requires members.manage in the active Space}
        '404': {description: Case does not exist in the active Space}
        '422': {description: Blank or overlong note, or non-Organization Space}

  /operations/catalog:
    get:
      summary: "Native operations catalog and allowed action flags"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /operations/access:
    get:
      summary: "Allowed operations in the authorized active Space"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /service-reply-templates:
    get:
      summary: "Staff reply library"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Create a staff reply template"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title: {"type": "string"}
                body: {"type": "string"}
                status: {"type": "string", "enum": ["draft", "approved", "archived"]}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /service-reply-templates/{template}:
    patch:
      summary: "Edit a Space-owned staff template"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: template, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title: {"type": "string"}
                body: {"type": "string"}
                status: {"type": "string", "enum": ["draft", "approved", "archived"]}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /service-cases/{serviceCase}/replies:
    post:
      summary: "Post approved or written agent reply through relationship Connect"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: serviceCase, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                body: {"type": "string"}
                template_id: {"type": "string"}
                idempotency_key: {"type": "string"}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /service-case-bulk:
    post:
      summary: "Atomically update up to 50 active-Space cases"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids: {"type": "array", "items": {"type": "string"}}
                status: {"type": "string", "enum": ["open", "in_progress", "pending_customer", "resolved", "closed"]}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /service-case-export:
    get:
      summary: "Filtered staff CSV export with spreadsheet formula protection"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: q, in: query, schema: {type: string}}
      - {name: status, in: query, schema: {type: string}}
      - {name: priority, in: query, schema: {type: string}}
      - {name: unassigned, in: query, schema: {type: boolean}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /attendance-clock-policy:
    get:
      summary: "Clock policies: the Space default first, then per-location overrides (name, is_space_default)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Configure the Space default clock policy, or a location override when business_location_id is set (members.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                business_location_id: {"type": "string", "format": "uuid", "nullable": true}
                timezone: {"type": "string"}
                geofence_enabled: {"type": "boolean"}
                latitude: {"type": "number"}
                longitude: {"type": "number"}
                radius_meters: {"type": "integer"}
                max_accuracy_meters: {"type": "integer"}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /attendance-clock:
    post:
      summary: "Clock own attendance with server time and explicit single-action location consent when required; Late / Half day derive from the assigned shift"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action: {"type": "string", "enum": ["in", "out"]}
                location_consent: {"type": "boolean"}
                latitude: {"type": "number"}
                longitude: {"type": "number"}
                accuracy_meters: {"type": "number"}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /attendance-corrections:
    get:
      summary: "Own corrections or manager review queue"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Request correction without changing original attendance"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                attendance_record_id: {"type": "string"}
                reason: {"type": "string"}
                minutes_worked: {"type": "integer"}
                checked_in_at: {"type": "string"}
                checked_out_at: {"type": "string"}
                status: {"type": "string", "enum": ["present", "absent", "remote", "leave"]}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /attendance-corrections/{correction}/decide:
    post:
      summary: "Separate staff approval with stale-snapshot protection"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: correction, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                decision: {"type": "string", "enum": ["approve", "reject"]}
                note: {"type": "string"}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /leave-balance:
    get:
      summary: "Leave balance per type and year (entitlement + carry-forward + adjustments − used; pending separate). Top level describes `annual` or `type`."
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: type, in: query, required: false, schema: {type: string}, description: 'Leave type key or lvt_ public id'}
      - {name: year, in: query, required: false, schema: {type: integer}}
      - {name: membership_id, in: query, required: false, schema: {type: integer}, description: 'Another member; requires members.manage'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /leave-types:
    get:
      summary: "Space leave types; defaults (annual, sick, unpaid, other) are seeded on first read"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: status, in: query, required: false, schema: {type: string, enum: [active, archived]}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Create a leave type (business.hrm.leave.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties: &leaveTypeProperties
                key: {"type": "string"}
                name: {"type": "string"}
                paid: {"type": "boolean"}
                annual_entitlement_half_days: {"type": "integer", "nullable": true}
                accrual: {"type": "string", "enum": ["none", "monthly", "annual"]}
                carry_forward_max_half_days: {"type": "integer"}
                requires_document: {"type": "boolean"}
                status: {"type": "string", "enum": ["active", "archived"]}
                sort_order: {"type": "integer"}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '422': {description: 'Input or workflow state is invalid'}
  /leave-types/{leaveType}:
    patch:
      summary: "Update a leave type; the key is immutable (business.hrm.leave.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: leaveType, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: *leaveTypeProperties
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /leave-balance-adjustments:
    get:
      summary: "Append-only leave balance ledger; staff see their own rows"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: membership_id, in: query, required: false, schema: {type: integer}}
      - {name: year, in: query, required: false, schema: {type: integer}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
    post:
      summary: "Append a signed balance adjustment; corrections are offsetting rows (business.hrm.leave.adjust)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [membership_id, leave_type, delta_half_days, reason]
              properties:
                membership_id: {"type": "integer"}
                leave_type: {"type": "string"}
                year: {"type": "integer"}
                delta_half_days: {"type": "integer"}
                reason: {"type": "string"}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /work-holidays:
    get:
      summary: "Work holidays; drafts are visible only to holiday managers"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: year, in: query, required: false, schema: {type: integer}}
      - {name: status, in: query, required: false, schema: {type: string, enum: [draft, published]}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Create a draft holiday, optionally for one business location (business.hrm.holiday.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, observed_on]
              properties: &holidayProperties
                name: {"type": "string"}
                observed_on: {"type": "string", "format": "date"}
                business_location_id: {"type": "string", "format": "uuid", "nullable": true}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '422': {description: 'Input or workflow state is invalid'}
  /work-holidays/{holiday}:
    patch:
      summary: "Update a holiday (business.hrm.holiday.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: holiday, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: *holidayProperties
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /work-holidays/{holiday}/publish:
    post:
      summary: "Publish a holiday to staff, the calendar feed and leave day counts (business.hrm.holiday.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: holiday, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /business-locations:
    get:
      summary: "Space business locations for shift, holiday and clock-policy pickers"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '422': {description: 'Input or workflow state is invalid'}
  /work-shifts:
    get:
      summary: "Space work shifts (local start/end, grace, half-day thresholds, ISO work days)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: status, in: query, required: false, schema: {type: string, enum: [active, archived]}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Create a shift; end at or before start crosses midnight (business.hrm.shift.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, starts_at_local, ends_at_local]
              properties: &workShiftProperties
                name: {"type": "string"}
                starts_at_local: {"type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"}
                ends_at_local: {"type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"}
                grace_minutes: {"type": "integer", "description": "Arrival after start + grace is Late"}
                late_after_minutes: {"type": "integer", "nullable": true, "description": "Arrival after start + this is Half day"}
                half_day_minutes: {"type": "integer", "nullable": true, "description": "Worked minutes below this is Half day"}
                work_days: {"description": "ISO weekdays 1 (Mon) to 7 (Sun), as a list or comma-separated string", "oneOf": [{"type": "array", "items": {"type": "integer"}}, {"type": "string"}]}
                business_location_id: {"type": "string", "format": "uuid", "nullable": true}
                status: {"type": "string", "enum": ["active", "archived"]}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '422': {description: 'Input or workflow state is invalid'}
  /work-shifts/{shift}:
    patch:
      summary: "Update or archive a shift (business.hrm.shift.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: shift, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: *workShiftProperties
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /shift-assignments:
    get:
      summary: "Dated shift assignments; staff see only their own"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: membership_id, in: query, required: false, schema: {type: integer}}
      - {name: current, in: query, required: false, schema: {type: boolean}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Assign a member to an active shift; ranges for one member may not overlap (business.hrm.shift.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [membership_id, work_shift_id, starts_on]
              properties:
                membership_id: {"type": "integer"}
                work_shift_id: {"type": "string"}
                starts_on: {"type": "string", "format": "date"}
                ends_on: {"type": "string", "format": "date", "nullable": true}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /shift-assignments/{assignment}:
    patch:
      summary: "Change or end an assignment date range (business.hrm.shift.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: assignment, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                starts_on: {"type": "string", "format": "date"}
                ends_on: {"type": "string", "format": "date", "nullable": true}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /employees:
    get:
      summary: "Employee directory with employment profile summary (any business.hrm.employment/lifecycle/conduct permission)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: status, in: query, required: false, schema: {type: string}}
      - {name: q, in: query, required: false, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '422': {description: 'Input or workflow state is invalid'}
  /employees/{member}:
    get:
      summary: "Employee 360 record: profile, employment changes, conduct, leave and attendance summary; sections included per viewer permission; member is a membership id or me"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: member, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /employees/{member}/profile:
    patch:
      summary: "Upsert the employment profile; employee number is allocated per Space on first save; staff may update only their own emergency contact (business.hrm.employment.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: member, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                employment_type: {"type": "string", "enum": ["full_time", "part_time", "contract", "intern", "temporary"]}
                started_on: {"type": "string", "format": "date", "nullable": true}
                business_location_id: {"type": "string", "nullable": true}
                emergency_contact: {"type": "object", "nullable": true, "properties": {"name": {"type": "string"}, "relationship": {"type": "string"}, "phone": {"type": "string"}}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /employment-changes:
    get:
      summary: "Promotion, transfer, resignation and termination requests; staff see changes about them or requested by them"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: status, in: query, required: false, schema: {type: string}}
      - {name: membership_id, in: query, required: false, schema: {type: integer}}
      - {name: kind, in: query, required: false, schema: {type: string}}
      - {name: mine, in: query, required: false, schema: {type: boolean}}
      - {name: awaiting, in: query, required: false, schema: {type: boolean}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Request an employment change; staff may request only their own resignation; submitted changes route to a separate approver via space approvals (business.hrm.lifecycle.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [kind, effective_on]
              properties:
                kind: {"type": "string", "enum": ["promotion", "transfer", "resignation", "termination"]}
                membership_id: {"type": "integer", "nullable": true}
                effective_on: {"type": "string", "format": "date"}
                reason: {"type": "string", "nullable": true}
                position_id: {"type": "string", "nullable": true}
                department_id: {"type": "string", "nullable": true}
                business_location_id: {"type": "string", "nullable": true}
                reports_to_membership_id: {"type": "integer", "nullable": true}
                employment_type: {"type": "string", "enum": ["full_time", "part_time", "contract", "intern", "temporary"]}
                submit: {"type": "boolean"}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /employment-changes/{change}:
    get:
      summary: "One employment change with viewer-specific action flags"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: change, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
  /employment-changes/{change}/submit:
    post:
      summary: "Submit a draft change for approval (requester or business.hrm.lifecycle.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: change, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /employment-changes/{change}/decide:
    post:
      summary: "Approve or reject a pending change; requester and subject cannot decide; approved changes due today apply atomically (business.hrm.lifecycle.approve)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: change, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision]
              properties:
                decision: {"type": "string", "enum": ["approved", "rejected"]}
                note: {"type": "string", "nullable": true}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /employment-changes/{change}/cancel:
    post:
      summary: "Cancel an open change (requester or business.hrm.lifecycle.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: change, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /employment-changes/{change}/apply:
    post:
      summary: "Apply an approved change whose effective date has arrived; idempotent; endings are blocked by active legal holds and never delete the identity (business.hrm.lifecycle.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: change, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /conduct-records:
    get:
      summary: "Confidential awards and warnings; staff see only their own"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: membership_id, in: query, required: false, schema: {type: integer}}
      - {name: mine, in: query, required: false, schema: {type: boolean}}
      - {name: kind, in: query, required: false, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Issue an award or warning to another member; details are encrypted at rest (business.hrm.conduct.manage)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [membership_id, kind, title]
              properties:
                membership_id: {"type": "integer"}
                kind: {"type": "string", "enum": ["award", "warning"]}
                title: {"type": "string"}
                details: {"type": "string", "nullable": true}
                issued_on: {"type": "string", "format": "date", "nullable": true}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /conduct-records/{record}:
    get:
      summary: "One conduct record; only the subject employee and conduct managers can read it"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: record, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
  /conduct-records/{record}/acknowledge:
    post:
      summary: "Subject employee acknowledges a conduct record once, with an optional comment"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: record, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                employee_comment: {"type": "string", "nullable": true}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '422': {description: 'Input or workflow state is invalid'}
  /attendance-today:
    get:
      summary: "Caller's effective shift window, today's attendance record and next punch action (in, out or null)"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '422': {description: 'Input or workflow state is invalid'}
  /me/employment:
    get:
      summary: "Staff self-service My work: the caller's own employee summary, today's shift and next punch, leave balances, open and recent requests (leave, attendance corrections, employment changes), upcoming published holidays for their location, manager/teammates/direct reports with directory fields only, unacknowledged policies and conduct records, upcoming meetings to RSVP, reviews and training, and published payslip lines. Sections whose capability is disabled are omitted and listed in `sections`."
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '422': {description: 'Input or workflow state is invalid'}
  /meeting-minutes:
    get:
      summary: "Space-owned meeting minutes"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Record minutes and action items for a scoped meeting"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                meeting_id: {"type": "string"}
                body: {"type": "string"}
                actions: {"type": "array", "items": {"type": "object"}}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /meeting-minutes/{minute}/export:
    get:
      summary: "Download Space-owned Markdown or Word minutes"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: minute, in: path, required: true, schema: {type: string}}
      - {name: format, in: query, schema: {type: string, enum: [md, docx], default: md}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /website-pages:
    get:
      summary: "Platform-owned website drafts and publications"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Create typed text content in Platform context"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                slug: {"type": "string"}
                kind: {"type": "string", "enum": ["page", "service", "faq", "policy", "download", "team", "testimonial", "banner", "navigation", "product", "media", "settings"]}
                content: {"type": "object"}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /website-pages/{page}:
    patch:
      summary: "Save a draft with optimistic revision check"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: page, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                revision: {"type": "integer"}
                content: {"type": "object"}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /website-pages/{page}/publish:
    post:
      summary: "Publish the current draft as an explicit public snapshot"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: page, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                revision: {"type": "integer"}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /website-pages/{page}/unpublish:
    post:
      summary: "Withdraw the public snapshot while preserving history"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: page, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                revision: {"type": "integer"}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /website-pages/{page}/restore:
    post:
      summary: "Restore an earlier revision into draft without automatic publication"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: page, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                revision: {"type": "integer"}
                source_revision: {"type": "integer"}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /website-pages/{page}/revisions:
    get:
      summary: "Read Platform-Space revision history"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: page, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /relationship-portals/customers/{customer}/cases:
    post:
      summary: "Create support request for the authenticated linked customer"
      security: [{bearerAuth: []}]
      parameters:
      - {name: customer, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subject: {"type": "string"}
                description: {"type": "string"}
                priority: {"type": "string", "enum": ["low", "normal", "high", "urgent"]}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /relationship-portals/customers/{customer}/cases/{serviceCase}:
    get:
      summary: "Read only linked customer case and public replies"
      security: [{bearerAuth: []}]
      parameters:
      - {name: customer, in: path, required: true, schema: {type: string}}
      - {name: serviceCase, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /relationship-portals/customers/{customer}/cases/{serviceCase}/replies:
    post:
      summary: "Reply as linked customer through Connect and reopen resolved case"
      security: [{bearerAuth: []}]
      parameters:
      - {name: customer, in: path, required: true, schema: {type: string}}
      - {name: serviceCase, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                body: {"type": "string"}
                idempotency_key: {"type": "string"}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /relationship-portals/customers/{customer}/cases/{serviceCase}/feedback:
    post:
      summary: "Record one resolved-case satisfaction response"
      security: [{bearerAuth: []}]
      parameters:
      - {name: customer, in: path, required: true, schema: {type: string}}
      - {name: serviceCase, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rating: {"type": "integer"}
                comment: {"type": "string"}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /relationship-portals/customers/{customer}/knowledge:
    get:
      summary: "Published knowledge for a linked customer relationship"
      security: [{bearerAuth: []}]
      parameters:
      - {name: customer, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}

  /service-desk/cases:
    get:
      summary: "Paginated staff cases with Space labels and own pin preferences"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: q, in: query, schema: {type: string, maxLength: 200}}
      - {name: status, in: query, schema: {type: string}}
      - {name: priority, in: query, schema: {type: string}}
      - {name: unassigned, in: query, schema: {type: boolean}}
      - {name: tag, in: query, schema: {type: string}}
      - {name: pinned, in: query, schema: {type: boolean}}
      - {name: page, in: query, schema: {type: integer, minimum: 1}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /service-cases/{serviceCase}/labels:
    post:
      summary: "Replace staff-only case labels"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: serviceCase, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags: {"type": "array", "items": {"type": "string"}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /service-cases/{serviceCase}/preferences:
    post:
      summary: "Set own case pin and importance flags"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: serviceCase, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pinned: {"type": "boolean"}
                important: {"type": "boolean"}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /service-cases/{serviceCase}/transcript:
    get:
      summary: "Export public replies as text; internal notes require explicit include_internal query"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: serviceCase, in: path, required: true, schema: {type: string}}
      - {name: include_internal, in: query, schema: {type: boolean, default: false}}
      - {name: format, in: query, schema: {type: string, enum: [txt, csv, json], default: txt}}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}

  /meeting-attendance:
    get:
      summary: "Own participation or organizer roster in the active Space"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
    post:
      summary: "Invite an active Space participant by permanent usr_ identity"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                meeting_id: {"type": "string"}
                participant_id: {"type": "string"}
      responses:
        '201': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /meeting-attendance/people:
    get:
      summary: "Organizer selector of active Space people without phone or email"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /meeting-attendance/{attendance}/respond:
    post:
      summary: "Record own accepted or declined RSVP"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: attendance, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                response: {"type": "string", "enum": ["accepted", "declined"]}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}
  /meeting-attendance/{attendance}/record:
    post:
      summary: "Organizer records attendance with manual provenance"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: attendance, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                attendance: {"type": "string", "enum": ["present", "absent", "unrecorded"]}
      responses:
        '200': {description: 'Successful scoped result or download; replies return 200 on idempotent replay'}
        '403': {description: 'Required role or relationship authorization denied'}
        '404': {description: 'Resource is absent from authorized Space or relationship'}
        '409': {description: 'Stale revision or conflicting request key'}
        '422': {description: 'Input or workflow state is invalid'}

  /service-cases/{serviceCase}/send-close:
    post:
      summary: "Send a final reply and close atomically; replay never recloses a reopened case"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: serviceCase, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                body: {"type": "string"}
                template_id: {"type": "string"}
                idempotency_key: {"type": "string"}
      responses:
        '201': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /service-desk/reports:
    get:
      summary: "Scoped case cohort, SLA, response, resolution and answered CSAT measures"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: from, in: query, schema: {type: string, format: date}}
      - {name: to, in: query, schema: {type: string, format: date}}
      responses:
        '200': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /attendance-corrections/missing-day:
    post:
      summary: "Request a missing day; no attendance is posted before separate manager approval"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                worked_on: {"type": "string", "format": "date"}
                reason: {"type": "string"}
                checked_in_at: {"type": "string", "format": "date-time"}
                checked_out_at: {"type": "string", "format": "date-time"}
      responses:
        '201': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /meeting-minutes/{minute}:
    patch:
      summary: "Edit current draft or review minutes using revision conflict protection"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: minute, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                revision: {"type": "integer"}
                body: {"type": "string"}
                sections: {"type": "object"}
                actions: {"type": "array", "items": {"type": "object"}}
      responses:
        '200': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /meeting-minutes/{minute}/state:
    post:
      summary: "Review, finalize or archive minutes; final minutes are immutable"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: minute, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                revision: {"type": "integer"}
                status: {"type": "string", "enum": ["review", "final", "archived"]}
      responses:
        '200': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /meeting-minutes/{minute}/derive:
    post:
      summary: "Derive keyword candidates from an authorized supplied transcript for organizer review"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: minute, in: path, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                revision: {"type": "integer"}
                transcript: {"type": "string", "maxLength": 20000}
      responses:
        '200': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /website-pages/{page}/preview:
    get:
      summary: "Private escaped HTML draft preview; no publication"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: page, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /website-subscribers:
    get:
      summary: "Platform subscription consent inventory with deterministic pagination"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      - {name: page, in: query, schema: {type: integer, minimum: 1}}
      responses:
        '200': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /website-subscribers/export:
    get:
      summary: "Export only currently confirmed non-withdrawn Platform subscribers as CSV"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /website-media:
    get:
      summary: "Select Platform-owned ready PNG, JPEG or PDF Vault files; upload uses the existing Vault contract"
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: Successful scoped response, protected export, form or redirect}
        '403': {description: Authorization or signature denied}
        '404': {description: Record absent from authorized scope or no published unchanged file version}
        '409': {description: Revision or retry conflict}
        '422': {description: Invalid input or workflow state}
  /service-office-hours:
    get:
      summary: Organization support schedule; authorized staff only
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      responses:
        '200': {description: Current schedule or an empty list}
        '403': {description: Staff permission required}
    post:
      summary: Configure timezone and weekly support hours with revision conflict protection
      security: [{bearerAuth: []}]
      parameters:
      - {$ref: '#/components/parameters/WorkspaceId'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [enabled, timezone, hours, closed_message]
              properties:
                enabled: {type: boolean}
                timezone: {type: string, example: Africa/Lagos}
                revision: {type: integer, minimum: 1, description: Required when replacing an existing schedule}
                closed_message: {type: string, maxLength: 1000}
                hours:
                  type: array
                  maxItems: 7
                  description: One interval per starting day; omitted days closed; overnight ends on next day; end exclusive
                  items:
                    type: object
                    required: [day, start, end]
                    properties:
                      day: {type: integer, minimum: 0, maximum: 6, description: Sunday is zero}
                      start: {type: string, example: '09:00'}
                      end: {type: string, example: '17:00'}
      responses:
        '200': {description: Saved schedule and current revision}
        '403': {description: Staff permission required}
        '409': {description: Reload the schedule before replacing it}
        '422': {description: Invalid timezone, interval or duplicate day}
  /relationship-portals/customers/{customer}/availability:
    get:
      summary: Relationship-scoped published support availability; requests remain accepted outside hours
      security: [{bearerAuth: []}]
      parameters:
      - {name: customer, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: Local checked time, published hours, availability and notice; open is null when unconfigured}
        '404': {description: Customer relationship not owned by this identity}

x-nymque-future:
  developer_platform:
    status: Planned
    note: >
      Public application registration, OAuth authorization, and third-party capability publishing are not currently available.
    oauth_public_server: false
  partner_verticals:
    status: Partial
    note: Requests for partner-delivered services depend on provider availability and authorization in the active Space.
  shield_risk_engine:
    status: Partial
    note: Risk decisions follow server-side policy and are available only to authorized reviewers.
