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

# Create Annotation

> Annotate one transcript with the named annotator (sync).



## OpenAPI

````yaml /api-reference/openapi.json post /v1/annotations
openapi: 3.1.0
info:
  description: |
    The Bigspin Annotation API annotates conversation transcripts with named,
    versioned annotators (for example ``universal-signals``).

    ## Authentication

    Every endpoint except ``/health`` and the docs surface requires a Bigspin
    API key sent as a bearer token:

    ```
    Authorization: Bearer bsk_...
    ```

    Requests without a valid key receive ``401``; revoked or disabled keys
    receive ``403``.

    ## Rate limits

    Requests are rate-limited per key (fixed window). When the limit is
    exceeded the API responds ``429`` with a ``Retry-After`` header. Provider
    capacity is additionally governed globally; saturation also surfaces as
    ``429`` + ``Retry-After``.

    ## Errors

    Every error response uses one envelope: ``{"error": ..., "detail": ...}``.

    The service runs on two substrates (Fargate/FastAPI and Lambda/ALBResolver)
    behind api-dev.bigspin.ai; the FastAPI edge's OpenAPI spec is canonical.
  summary: Synchronous transcript annotation over Bigspin's annotator registry.
  title: Bigspin Annotation API
  version: 0.1.0
servers:
  - description: Development
    url: https://api-dev.bigspin.ai
security: []
tags:
  - description: Unauthenticated liveness probe reporting the serving substrate.
    name: health
  - description: >-
      Synchronous transcript annotation and the public registry of available
      annotators.
    name: annotations
  - description: >-
      Asynchronous batch annotation. Spec'd in v1 but not yet implemented —
      endpoints return 501 (see RFC 000055).
    name: batches
paths:
  /v1/annotations:
    post:
      tags:
        - annotations
      summary: Create Annotation
      description: Annotate one transcript with the named annotator (sync).
      operationId: create_annotation_v1_annotations_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationResponse'
          description: Successful Response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Content
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Many Requests
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Gateway
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service Unavailable
components:
  schemas:
    AnnotationRequest:
      description: |-
        Request body for ``POST /v1/annotations``.

        Clients name an ``annotator`` (an instrument in the registry), never a
        model or provider. ``options`` is an open bag for per-request knobs.
      properties:
        annotator:
          title: Annotator
          type: string
        options:
          additionalProperties: true
          title: Options
          type: object
        transcript:
          items:
            $ref: '#/components/schemas/TranscriptMessage'
          title: Transcript
          type: array
      required:
        - transcript
        - annotator
      title: AnnotationRequest
      type: object
    AnnotationResponse:
      description: Response body for ``POST /v1/annotations``.
      properties:
        annotator:
          title: Annotator
          type: string
        annotator_version:
          title: Annotator Version
          type: string
        outcome:
          enum:
            - strong
            - mixed
            - poor
            - critical
            - indeterminate
          title: Outcome
          type: string
        outcome_notes:
          title: Outcome Notes
          type: string
        signals:
          additionalProperties:
            $ref: '#/components/schemas/SignalHit'
          title: Signals
          type: object
        summary:
          $ref: '#/components/schemas/AnnotationSummary'
        taxonomy_version:
          title: Taxonomy Version
          type: string
        usage:
          $ref: '#/components/schemas/UsageInfo'
      required:
        - summary
        - outcome
        - outcome_notes
        - signals
        - annotator
        - annotator_version
        - taxonomy_version
        - usage
      title: AnnotationResponse
      type: object
    ErrorResponse:
      description: The one error envelope for bigspin-api.
      properties:
        detail:
          title: Detail
          type: string
        error:
          title: Error
          type: string
      required:
        - error
        - detail
      title: ErrorResponse
      type: object
    TranscriptMessage:
      description: One message of the transcript under annotation.
      properties:
        content:
          title: Content
          type: string
        is_user_visible:
          default: true
          title: Is User Visible
          type: boolean
        role:
          title: Role
          type: string
      required:
        - role
        - content
      title: TranscriptMessage
      type: object
    SignalHit:
      description: 'One fired quality signal: evidence plus an optional 1-indexed turn.'
      properties:
        evidence:
          title: Evidence
          type: string
        turn:
          anyOf:
            - type: integer
            - type: 'null'
          title: Turn
      required:
        - evidence
      title: SignalHit
      type: object
    AnnotationSummary:
      description: Structured summary of the conversation under annotation.
      properties:
        domain:
          title: Domain
          type: string
        keywords:
          items:
            type: string
          title: Keywords
          type: array
        quality_concerns:
          title: Quality Concerns
          type: string
        summary:
          title: Summary
          type: string
        title:
          title: Title
          type: string
        user_intent:
          title: User Intent
          type: string
      required:
        - title
        - keywords
        - summary
        - quality_concerns
        - user_intent
        - domain
      title: AnnotationSummary
      type: object
    UsageInfo:
      description: Token/latency accounting for one annotation call.
      properties:
        latency_ms:
          title: Latency Ms
          type: integer
        tokens_in:
          title: Tokens In
          type: integer
        tokens_out:
          title: Tokens Out
          type: integer
      required:
        - tokens_in
        - tokens_out
        - latency_ms
      title: UsageInfo
      type: object

````