> ## Documentation Index
> Fetch the complete documentation index at: https://www.composer.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Store a complete Triage submission or follow-on revision



## OpenAPI

````yaml /api-reference/openapi.json post /records
openapi: 3.1.0
info:
  title: composerID Intent API
  version: 1.0.0-draft
  summary: >-
    Publish a decision into any destination system of record, under one Intent
    ID.
  description: >
    The composerID Intent API: mint an intent at the decision, plan its

    destinations, preflight against a tenant's own requirements, publish
    idempotently,

    and reconcile drift, with every step on an append-only timeline under one
    Intent ID.


    **Status.** This is the documented contract, served today by the reference
    sandbox

    (`service/` in the composerID repository) over mock destination tenants. The

    production service behind `https://api.composer.id` is in build; nothing
    here is a

    claim that it is live. The sandbox implements this document exactly, so a
    client

    generated from it works against the sandbox now and against production
    unchanged.


    **Authentication.** Bearer token on every request (`Authorization: Bearer

    <token>`). Production clients use OAuth 2.0 client credentials: exchange a

    `client_id` and `client_secret` at `POST /v1/oauth/token` for a token that

    expires in an hour and carries only the scopes the client was granted

    (`intents:read`, `intents:write`, `publish`, `reconcile`, `passthrough`,

    `destinations:read`); a token without the scope a route needs gets 403

    `insufficient_scope`. Personal sandbox API keys are also accepted as bearer

    tokens and carry every scope. All comparisons are constant-time. Destination

    credentials are never supplied by the caller: they are held per tenant and

    injected by the adapter.


    **Sandbox credentials.** The hosted sandbox issues its own: `POST

    /v1/sandbox/keys` (no authentication, rate-limited per caller address)

    creates a tenant with a personal API key, an OAuth client and a webhook

    signing key, shown once and expiring together. Each tenant sees only the

    intents it minted. The local run prints a key at startup instead. The

    production service will not expose this route.

    The one route that carries no bearer token is `POST
    /v1/webhooks/{platform}`:

    the caller is a destination platform, so the delivery authenticates by its

    `X-Signature-HMAC-SHA256-{n}` header (Base64 HMAC-SHA256 over the raw body,

    any active signing key, timing-safe), the same convention composerID's own

    outbound webhooks use.


    **Idempotency.** Publishing is idempotent on

    `{intent_id}-{intent_version}-{target_system}`. A replayed publish returns
    the

    stored receipt with `replayed: true` and never creates a second record in
    the

    destination system. Where a destination documents no idempotency header, the

    adapter dedupes by querying the destination's own client-supplied id before

    creating.


    **What crosses the boundary.** A destination receives a valid request plus
    the

    Intent ID. Diagnostic answers, scores and the Compliance File never leave

    composerID.
  contact:
    name: composerID developer access
    url: https://www.composer.id/authentication
servers:
  - url: https://sandbox.composer.id/v1
    description: >-
      Hosted reference sandbox: mock destination tenants, self-serve credentials
      at POST /sandbox/keys.
  - url: https://api.composer.id/v1
    description: 'Production. In build: see the status note above.'
  - url: http://127.0.0.1:8787/v1
    description: >-
      Local reference sandbox (python3 -m service.server), mock destination
      tenants.
security:
  - oauth2:
      - destinations:read
      - intents:read
      - intents:write
      - passthrough
      - publish
      - reconcile
  - bearerAuth: []
tags:
  - name: Auth
    description: >-
      OAuth 2.0 client credentials. Exchange a client id and secret for a
      short-lived bearer token carrying only the scopes the client was granted.
  - name: Intent
    description: Mint, read, amend and audit an intent. The timeline is append-only.
  - name: Routing
    description: >-
      Apply the Channel Map, then validate against the destination tenant's own
      requirements before publishing.
  - name: Publishing
    description: >-
      Idempotent publish, drift reconciliation, inbound destination events, and
      a raw escape hatch that stays anchored to the Intent ID.
  - name: Discovery
    description: What composerID can reach, and what each destination requires.
externalDocs:
  description: >-
    The composerID documentation: API reference, schemas and destination
    coverage
  url: https://www.composer.id/api-reference/overview
paths:
  /records:
    post:
      tags:
        - Intent
      summary: Store a complete Triage submission or follow-on revision
      operationId: submitTriageRecord
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriageSubmission'
      responses:
        '200':
          description: Identical source revision replayed; no new record or revision.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriageSubmissionReceipt'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriageSubmissionReceipt'
        '400':
          description: Malformed body or missing required field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid or expired bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'insufficient_scope: the token lacks `intents:write`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown intent or destination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Changed source content or stale expected version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid question, typed answer, branch, timing or relationship.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - oauth2:
            - intents:write
        - bearerAuth: []
components:
  schemas:
    TriageSubmission:
      title: TriageSubmission
      type: object
      required:
        - schema_version
        - environment
        - source
        - kind
        - requester
        - context
        - questionnaire
        - responses
        - events
        - decision
      properties:
        schema_version:
          const: '1.0'
        environment:
          const: sandbox
        source:
          type: object
          required:
            - system
            - instance
            - session_id
            - revision
          properties:
            system:
              const: triage
            instance:
              type: string
              pattern: ^[A-Za-z0-9_.:-]{1,160}$
            session_id:
              type: string
              pattern: ^[A-Za-z0-9_.:-]{1,160}$
            revision:
              type: integer
              minimum: 1
          additionalProperties: false
        kind:
          enum:
            - initial
            - follow_on
            - change_request
        requester:
          type: object
          required:
            - id
            - display_name
          properties:
            id:
              type: string
              pattern: ^[A-Za-z0-9_.:-]{1,160}$
            display_name:
              type: string
          additionalProperties: false
        context:
          type: object
          required:
            - locale
            - timezone
            - started_at
            - submitted_at
          properties:
            locale:
              type: string
            timezone:
              type: string
            started_at:
              type: string
              format: date-time
            submitted_at:
              type: string
              format: date-time
          additionalProperties: false
        questionnaire: 346105ca-2ba5-4908-aab9-5a56f923de87
        responses:
          type: array
          items: 8b9b5d15-0822-40b8-b095-4569f10de443
          minItems: 1
          maxItems: 100
        events:
          type: array
          items:
            type: object
            required:
              - sequence
              - type
              - question_id
              - at
            properties:
              sequence:
                type: integer
                minimum: 1
              type:
                enum:
                  - question.shown
                  - question.answered
                  - question.skipped
                  - guidance.opened
                  - branch.skipped
              question_id:
                type: string
                pattern: ^[A-Za-z0-9_.:-]{1,160}$
              at:
                type: string
                format: date-time
              detail: {}
            additionalProperties: false
          minItems: 0
          maxItems: 2000
        decision: 01e83615-600e-44f0-857f-32f4a68e42b1
        target:
          type: object
          required:
            - intent_id
            - expected_version
          properties:
            intent_id:
              type: string
              pattern: ^[A-Za-z0-9_.:-]{1,160}$
            expected_version:
              type: integer
              minimum: 1
          additionalProperties: false
        work: d2fb2c10-7f7e-41fd-8c52-030a73daf34b
        metadata:
          type: object
      additionalProperties: false
      description: >-
        Complete source-reported Triage capture. Semantic validation also checks
        answer types against definitions, branch visibility, option IDs, parent
        references and timings. Follow-ons preserve original diagnostics; change
        requests get a new linked Intent ID.
      allOf:
        - if:
            properties:
              kind:
                const: follow_on
          then:
            required:
              - target
          else:
            not:
              required:
                - target
        - if:
            properties:
              kind:
                const: change_request
          then:
            required:
              - work
          else:
            not:
              required:
                - work
      $defs:
        question:
          type: object
          required:
            - id
            - type
            - prompt
            - guidance
            - answer_guidance
            - required
            - stage
          properties:
            id:
              type: string
              pattern: ^[A-Za-z0-9_.:-]{1,160}$
            type:
              enum:
                - text
                - single_choice
                - multiple_choice
                - boolean
                - date
                - money
                - number
            prompt:
              type: string
            guidance:
              type: string
            answer_guidance:
              type: string
            required:
              type: boolean
            stage:
              enum:
                - diagnostic
                - intake
                - country_compliance
                - desk_review
                - change_request
            options:
              type: array
              items:
                type: object
                required:
                  - id
                  - label
                  - guidance
                properties:
                  id:
                    type: string
                    pattern: ^[A-Za-z0-9_.:-]{1,160}$
                  label:
                    type: string
                  guidance:
                    type: string
                additionalProperties: false
              minItems: 1
              maxItems: 100
            follow_on:
              type: object
              required:
                - parent_question_id
                - reason
              properties:
                parent_question_id:
                  type: string
                  pattern: ^[A-Za-z0-9_.:-]{1,160}$
                reason:
                  type: string
                equals: {}
              additionalProperties: false
            semantic_key:
              type: string
              pattern: ^[A-Za-z0-9_.:-]{1,160}$
          additionalProperties: false
          allOf:
            - if:
                properties:
                  type:
                    enum:
                      - single_choice
                      - multiple_choice
              then:
                required:
                  - options
              else:
                not:
                  required:
                    - options
        questionnaire:
          type: object
          required:
            - id
            - version
            - title
            - questions
          properties:
            id:
              type: string
              pattern: ^[A-Za-z0-9_.:-]{1,160}$
            version:
              type: string
            title:
              type: string
            questions:
              type: array
              items:
                $ref: '#/components/schemas/TriageSubmission/$defs/question'
              minItems: 1
              maxItems: 100
          additionalProperties: false
        response:
          type: object
          required:
            - question_id
            - status
            - value
            - timing
          properties:
            question_id:
              type: string
              pattern: ^[A-Za-z0-9_.:-]{1,160}$
            status:
              enum:
                - answered
                - skipped
                - not_shown
                - invalidated
            value:
              oneOf:
                - type: string
                - type: boolean
                - type: number
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 100
                - $ref: '#/components/schemas/TriageSubmission/$defs/money'
                - type: 'null'
            timing:
              oneOf:
                - $ref: '#/components/schemas/TriageSubmission/$defs/timing'
                - type: 'null'
          additionalProperties: false
          allOf:
            - if:
                properties:
                  status:
                    enum:
                      - skipped
                      - not_shown
              then:
                properties:
                  value:
                    type: 'null'
            - if:
                properties:
                  status:
                    const: not_shown
              then:
                properties:
                  timing:
                    type: 'null'
        timing:
          type: object
          required:
            - shown_at
            - answered_at
            - elapsed_ms
            - guidance_opened
          properties:
            shown_at:
              type: string
              format: date-time
            answered_at:
              type: string
              format: date-time
            elapsed_ms:
              type: integer
              minimum: 0
            guidance_opened:
              type: boolean
          additionalProperties: false
        money:
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              pattern: ^(?:0|[1-9][0-9]{0,14})(?:\.[0-9]{1,2})?$
            currency:
              enum:
                - GBP
                - EUR
                - USD
                - AUD
                - CAD
                - SGD
          additionalProperties: false
        decision:
          type: object
          required:
            - status
          properties:
            status:
              enum:
                - not_evaluated
                - awaiting_desk
                - decided
            recommended_channels:
              type: array
              items:
                enum:
                  - permanent_hire
                  - outsourced
                  - contingent
                  - statement_of_work
                  - ai
              minItems: 0
              maxItems: 5
            final_channel:
              enum:
                - permanent_hire
                - outsourced
                - contingent
                - statement_of_work
                - ai
            scores: {}
            ruleset_version:
              type: string
            override:
              type: object
              required:
                - actor_id
                - reason
                - at
              properties:
                actor_id:
                  type: string
                reason:
                  type: string
                at:
                  type: string
                  format: date-time
              additionalProperties: false
          additionalProperties: false
        work:
          type: object
          required:
            - reason
            - change_types
          properties:
            reason:
              type: string
            change_types:
              type: array
              items:
                enum:
                  - scope
                  - budget
                  - dates
                  - people
                  - renewal
                  - other
              minItems: 1
              maxItems: 6
            original_intent_id:
              type: string
              pattern: ^[A-Za-z0-9_.:-]{1,160}$
            original_version:
              type: integer
              minimum: 1
            external_reference:
              type: object
              required:
                - system
                - id
              properties:
                system:
                  type: string
                id:
                  type: string
              additionalProperties: false
          additionalProperties: false
          anyOf:
            - required:
                - original_intent_id
                - original_version
            - required:
                - external_reference
      x-canonical-url: https://composer.id/schemas/triage-submission.json
    TriageSubmissionReceipt:
      title: TriageSubmissionReceipt
      type: object
      required:
        - intent_id
        - intent_version
        - stored_at
        - content_sha256
        - replayed
      properties:
        intent_id:
          type: string
          pattern: ^[A-Za-z0-9_.:-]{1,160}$
        intent_version:
          type: integer
          minimum: 1
        stored_at:
          type: string
          format: date-time
        content_sha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        replayed:
          type: boolean
      additionalProperties: false
      x-canonical-url: https://composer.id/schemas/triage-submission-receipt.json
    Error:
      type: object
      required:
        - error
      additionalProperties: true
      properties:
        error:
          type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        Client credentials, the production model: server-to-server, short-lived
        tokens, least-privilege scopes, rotation by issuing a new client secret.
      flows:
        clientCredentials:
          tokenUrl: https://api.composer.id/v1/oauth/token
          scopes:
            intents:read: Read intent records and their timelines.
            intents:write: Create, patch, plan, preflight and enrich intents.
            publish: Publish an intent into a destination system.
            reconcile: Run reconciliation against a destination.
            passthrough: Raw platform calls anchored to an Intent ID.
            destinations:read: List platforms, destinations and capabilities.
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A personal sandbox API key, minted by POST /sandbox/keys and carrying
        every scope; or a token from the oauth2 flow. Compared in constant time.
        Destination credentials are never passed by the caller.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.