{"openapi":"3.1.0","info":{"title":"Bigspin Annotation API","summary":"Synchronous transcript annotation over Bigspin's annotator registry.","description":"The Bigspin Annotation API annotates conversation transcripts with named,\nversioned annotators (for example ``universal-signals``).\n\n## Authentication\n\nEvery endpoint except ``/health`` and the docs surface requires a Bigspin\nAPI key sent as a bearer token:\n\n```\nAuthorization: Bearer bsk_...\n```\n\nRequests without a valid key receive ``401``; revoked or disabled keys\nreceive ``403``.\n\n## Rate limits\n\nRequests are rate-limited per key (fixed window). When the limit is\nexceeded the API responds ``429`` with a ``Retry-After`` header. Provider\ncapacity is additionally governed globally; saturation also surfaces as\n``429`` + ``Retry-After``.\n\n## Errors\n\nEvery error response uses one envelope: ``{\"error\": ..., \"detail\": ...}``.\n\nThe service runs on two substrates (Fargate/FastAPI and Lambda/ALBResolver)\nbehind api-dev.bigspin.ai; the FastAPI edge's OpenAPI spec is canonical.\n","version":"0.1.0"},"servers":[{"url":"https://api-dev.bigspin.ai","description":"Development"}],"paths":{"/health":{"get":{"tags":["health"],"summary":"Health","description":"Liveness probe reporting which compute substrate serves traffic.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/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":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/annotators":{"get":{"tags":["annotations"],"summary":"List Annotators","description":"Public registry view: the available annotators and their versions.","operationId":"list_annotators_v1_annotators_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotatorListResponse"}}}}}}},"/v1/batches":{"post":{"tags":["batches"],"summary":"Create Batch","description":"Spec'd in OpenAPI now; returns 501 in v1 (see RFC 000055).","operationId":"create_batch_v1_batches_post","responses":{"501":{"description":"Not implemented in v1 (see RFC 000055)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/batches/{batch_id}":{"get":{"tags":["batches"],"summary":"Get Batch","description":"Spec'd in OpenAPI now; returns 501 in v1 (see RFC 000055).","operationId":"get_batch_v1_batches__batch_id__get","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}}],"responses":{"501":{"description":"Not implemented in v1 (see RFC 000055)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AnnotationRequest":{"properties":{"transcript":{"items":{"$ref":"#/components/schemas/TranscriptMessage"},"type":"array","title":"Transcript"},"annotator":{"type":"string","title":"Annotator"},"options":{"additionalProperties":true,"type":"object","title":"Options"}},"type":"object","required":["transcript","annotator"],"title":"AnnotationRequest","description":"Request body for ``POST /v1/annotations``.\n\nClients name an ``annotator`` (an instrument in the registry), never a\nmodel or provider. ``options`` is an open bag for per-request knobs."},"AnnotationResponse":{"properties":{"summary":{"$ref":"#/components/schemas/AnnotationSummary"},"outcome":{"type":"string","enum":["strong","mixed","poor","critical","indeterminate"],"title":"Outcome"},"outcome_notes":{"type":"string","title":"Outcome Notes"},"signals":{"additionalProperties":{"$ref":"#/components/schemas/SignalHit"},"type":"object","title":"Signals"},"annotator":{"type":"string","title":"Annotator"},"annotator_version":{"type":"string","title":"Annotator Version"},"taxonomy_version":{"type":"string","title":"Taxonomy Version"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"type":"object","required":["summary","outcome","outcome_notes","signals","annotator","annotator_version","taxonomy_version","usage"],"title":"AnnotationResponse","description":"Response body for ``POST /v1/annotations``."},"AnnotationSummary":{"properties":{"title":{"type":"string","title":"Title"},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords"},"summary":{"type":"string","title":"Summary"},"quality_concerns":{"type":"string","title":"Quality Concerns"},"user_intent":{"type":"string","title":"User Intent"},"domain":{"type":"string","title":"Domain"}},"type":"object","required":["title","keywords","summary","quality_concerns","user_intent","domain"],"title":"AnnotationSummary","description":"Structured summary of the conversation under annotation."},"AnnotatorInfo":{"properties":{"id":{"type":"string","title":"Id"},"annotator_version":{"type":"string","title":"Annotator Version"},"taxonomy_version":{"type":"string","title":"Taxonomy Version"},"description":{"type":"string","title":"Description"}},"type":"object","required":["id","annotator_version","taxonomy_version","description"],"title":"AnnotatorInfo","description":"Public registry view of one annotator (instrument)."},"AnnotatorListResponse":{"properties":{"annotators":{"items":{"$ref":"#/components/schemas/AnnotatorInfo"},"type":"array","title":"Annotators"}},"type":"object","required":["annotators"],"title":"AnnotatorListResponse","description":"Response body for ``GET /v1/annotators``."},"ErrorResponse":{"properties":{"error":{"type":"string","title":"Error"},"detail":{"type":"string","title":"Detail"}},"type":"object","required":["error","detail"],"title":"ErrorResponse","description":"The one error envelope for bigspin-api."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status"},"substrate":{"type":"string","title":"Substrate"}},"type":"object","required":["status","substrate"],"title":"HealthResponse","description":"Response body for ``GET /health`` on both edges.\n\n``substrate`` reports which compute substrate is serving traffic\n(``\"fargate\"`` or ``\"lambda\"``), sourced from ``BIGSPIN_SUBSTRATE``."},"SignalHit":{"properties":{"evidence":{"type":"string","title":"Evidence"},"turn":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn"}},"type":"object","required":["evidence"],"title":"SignalHit","description":"One fired quality signal: evidence plus an optional 1-indexed turn."},"TranscriptMessage":{"properties":{"role":{"type":"string","title":"Role"},"content":{"type":"string","title":"Content"},"is_user_visible":{"type":"boolean","title":"Is User Visible","default":true}},"type":"object","required":["role","content"],"title":"TranscriptMessage","description":"One message of the transcript under annotation."},"UsageInfo":{"properties":{"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_out":{"type":"integer","title":"Tokens Out"},"latency_ms":{"type":"integer","title":"Latency Ms"}},"type":"object","required":["tokens_in","tokens_out","latency_ms"],"title":"UsageInfo","description":"Token/latency accounting for one annotation call."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"health","description":"Unauthenticated liveness probe reporting the serving substrate."},{"name":"annotations","description":"Synchronous transcript annotation and the public registry of available annotators."},{"name":"batches","description":"Asynchronous batch annotation. Spec'd in v1 but not yet implemented — endpoints return 501 (see RFC 000055)."}]}