usestring-ai Documentation API

openapi: 3.2.0
info:
  description: 'The customer-facing HTTP/JSON API for Composer.


    Describe the feed you want in prose, answer the questions the builder asks, and

    approve the finished schema. Every route is under `/v1` and every route under

    `/v1` requires an API key.


    ## Authentication


    `Authorization: Bearer sk_fb_live_…`. The scheme is matched

    case-insensitively. The tenant comes from the key AND ONLY FROM THE KEY: no

    request body may carry an organization or user id, and one that does is refused

    rather than silently overwritten.


    The two documentation routes — `/openapi.yaml` and `/docs` — take no key.


    ## Errors


    Every refusal has the same body: `{"error": {"type", "code", "message", "param?", "request_id?"}}`.

    Switch on `type` to decide whether to retry, fix the request, or escalate;

    `code` is the specific reason within the family. `request_id` matches the

    `x-string-request-id` response header and our log line, so quote it when you ask

    us about a request.


    | Upstream condition | HTTP |

    | --- | --- |

    | invalid argument, out of range | 400 |

    | bad or missing key | 401 |

    | permission denied | 403 |

    | unknown build | 404 |

    | already exists, failed precondition, aborted | 409 |

    | body over 1 MiB | 413 |

    | rate limited | 429 + `Retry-After` |

    | the request was cancelled upstream | 499 |

    | not implemented upstream | 501 |

    | unavailable | 503 |

    | upstream timeout | 504 |

    | anything else | 500, with a generic message |


    The table is grpc-gateway''s canonical gRPC-to-HTTP mapping with ONE deliberate

    change: a failed precondition answers **409, not 400**. On this API that

    condition is a state conflict — input sent to a build that has finished, a gate

    answered after it stopped being pending — which you resolve by changing state,

    not by editing your request, and a 400 would send you to re-read JSON that is

    already correct.


    499 is listed for completeness and is not documented on individual operations:

    it is written when the request was already cancelled, so in practice there is

    nobody left to read it.


    **403 is never about a particular build or feed, and that is deliberate.** It

    answers only for the CALLER: an organization that is not entitled to use

    Composer (`feed_builder_disabled`), or, on `POST /v1/builds` alone, a key with no

    user recorded against it (`key_not_attributed`). A build owned by another

    organization answers a BYTE-IDENTICAL 404 to an unknown id — same code, same

    message. Nothing inspects the id, the organization, or the message to choose

    between them, because a distinguishable answer is an oracle: a caller could walk

    build ids and learn which ones are real. Do not write client code that tries to

    tell the two apart.


    ## Scope: this API serves supervised builds only


    Every build starts supervised: it may stop and ask you things, and it publishes

    by way of a publish-review gate you answer. There is no unattended mode and no

    way to pre-authorize publishing, so `POST /v1/builds` takes no lever for

    either — the body is the query and nothing else.


    ## Streaming


    `GET /v1/builds/{id}/events` is server-sent events. OpenAPI cannot describe a

    stream of framed events, so **generated clients will not handle that endpoint** —

    use an SSE client for it and a generated client for the other ten operations.

    The frame shape and event names are on the operation itself.'
  title: Composer Documentation API
  version: v1
servers:
- description: The origin this document was served from.
  url: /
security:
- bearerAuth: []
tags:
- description: This specification and its rendering. Unauthenticated.
  name: Documentation
paths:
  /docs:
    get:
      description: A Swagger UI page rendering /openapi.yaml. No API key is required.
      operationId: getDocs
      responses:
        '200':
          content:
            text/html: {}
          description: An HTML page.
      security: []
      summary: Browsable API reference
      tags:
      - Documentation
  /openapi.yaml:
    get:
      description: The OpenAPI 3.1 document for this API, as YAML. NO API KEY IS REQUIRED — a specification you need a credential to read is useless for evaluating the product, and its contents are not a secret. Generated from the service's own types at runtime, so it describes the binary that served it.
      operationId: getOpenAPIDocument
      responses:
        '200':
          content:
            application/yaml: {}
          description: The specification.
      security: []
      summary: This document
      tags:
      - Documentation
components:
  securitySchemes:
    bearerAuth:
      description: 'A Composer API key: `Authorization: Bearer sk_fb_live_…`.'
      scheme: bearer
      type: http