> ## Documentation Index > Fetch the complete documentation index at: https://docs.fiveninelabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Start a session (the first turn) > With `Accept: text/event-stream`, streams the run on this request. Otherwise returns 201 immediately; watch via stream, events, result long-poll, or webhooks. Spending POST — honors Idempotency-Key. ## OpenAPI ````yaml /api-reference/openapi.yaml post /sessions openapi: 3.1.0 info: title: Five Nine Agent API version: '2026-08-26' description: > Live catalogs from the open web, under signed receipts. Conventions (versioning via the dated `fn-version` header, request IDs, idempotency, rate limits, pagination, money) are documented across this reference; the error envelope at https://docs.fiveninelabs.com/errors; the event vocabulary at https://docs.fiveninelabs.com/guides/events; webhooks at https://docs.fiveninelabs.com/guides/webhooks. Honesty marker: operations tagged `x-fn-status: planned` are specced but NOT yet served by the live API — on any method they answer 501 not_implemented with a `surface` member naming what is missing, never 404. Everything unmarked is live. The changelog says when a planned surface ships. servers: - url: https://api.fiveninelabs.com/v1 security: - bearerKey: [] paths: /sessions: post: summary: Start a session (the first turn) description: > With `Accept: text/event-stream`, streams the run on this request. Otherwise returns 201 immediately; watch via stream, events, result long-poll, or webhooks. Spending POST — honors Idempotency-Key. parameters: - $ref: '#/components/parameters/FnVersion' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SessionCreate' responses: '200': description: SSE stream (when Accept is text/event-stream) content: text/event-stream: schema: type: string description: https://docs.fiveninelabs.com/guides/events '201': description: Session created and running content: application/json: schema: $ref: '#/components/schemas/Session' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/Declined' '429': $ref: '#/components/responses/RateLimit' '502': $ref: '#/components/responses/EngineUnavailable' components: parameters: FnVersion: name: fn-version in: header required: false schema: type: string example: '2026-08-26' description: >- Dated API version; defaults to the account pin. Honesty note: with one version in existence the gateway echoes any value back as effective WITHOUT validating it — validation against the known-versions set is planned, so send only real dated versions from https://docs.fiveninelabs.com/changelog IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: 24h replay window; a retry never bills twice schemas: SessionCreate: type: object required: - query - max_spend_usd properties: query: type: string description: the natural-language question max_spend_usd: type: number exclusiveMinimum: 0 description: >- this run's reservation and ceiling (per-run, not lifetime); key caps apply query_budget_ms: type: integer maximum: 5400000 description: whole-query deadline; bounded by the engine's 90-minute backstop concurrency: type: integer minimum: 1 maximum: 8 webhook_url: type: string format: uri metadata: type: object maxProperties: 16 additionalProperties: type: string Session: type: object required: - id - object - status - created_at properties: id: type: string example: sess_9m2kd object: type: string const: session status: type: string description: >- running | judging | answered | abstained | error | stopped (open enum) query: type: string turn: type: integer spend_usd: type: number reserved_usd: type: number max_spend_usd: type: number sources: type: integer records: type: integer receipts_signed: type: integer unchecked: type: integer description: merchants never dispatched — a fact about us, stated key_id: type: string created_at: type: string format: date-time ended_at: type: string format: date-time metadata: type: object additionalProperties: type: string links: type: object properties: stream: type: string events: type: string result: type: string rows: type: string receipts: type: string console: type: string description: dashboard deep link to this run's detail view Error: type: object required: - error properties: error: type: object required: - type - code - message - doc_url - request_id properties: type: type: string code: type: string message: type: string doc_url: type: string format: uri request_id: type: string additionalProperties: true responses: InvalidRequest: description: invalid_request (https://docs.fiveninelabs.com/errors/invalid_param) content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: 401 invalid_key | key_revoked — key missing, unknown, or revoked content: application/json: schema: $ref: '#/components/schemas/Error' Payment: description: 402 insufficient_credit — balance, reserves, top_up_url in context content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- 403 missing_scope — or a cap forbids this (session_cap_exceeded | monthly_cap_exceeded; caps are permissions, not rates) content: application/json: schema: $ref: '#/components/schemas/Error' Declined: description: >- 422 declined_to_spend — RESERVED, not emitted today: a query we refuse to spend on returns 201 and ends as a $0 `abstained` run (reservation released); the pre-spend signal is estimate.would_run:false. See https://docs.fiveninelabs.com/errors/declined_to_spend content: application/json: schema: $ref: '#/components/schemas/Error' RateLimit: description: 429 rate_limited | concurrency_cap, with Retry-After content: application/json: schema: $ref: '#/components/schemas/Error' EngineUnavailable: description: >- 502 engine_unavailable — the extraction engine is unreachable; nothing was billed and no run started. No Retry-After header today; retry with your own backoff (https://docs.fiveninelabs.com/errors/engine_unavailable) content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerKey: type: http scheme: bearer description: 'fn_live_… or fn_test_… — Authorization: Bearer' ````