---
title: Synorb REST API
description: Deterministic REST integration workflow and OpenAPI references.
canonical: https://synorb.com/docs/api
last-updated: 2026-09-15
---

# Synorb REST API

The REST API is for deterministic server-side routes, scheduled jobs, and
agent discovery. Keep the Synorb Key in a server-side secret store and send it
as `Authorization: Bearer YOUR_SYNORB_KEY`.

## Agent discovery

`GET` or `POST /ask` accepts a natural-language `q` or `query` and returns a
read-only NLWeb-style stream-discovery envelope. Add `Accept:
text/event-stream` or `stream=true` when an SSE response is preferred; events
are `start`, `result`, and `complete`. Discovery is authenticated but does not
consume Manifest quota.

`POST /batch` accepts a non-empty `operations` array with at most 20 entries.
Only `/ask`, `/streams/search`, and `/api/streams/search` are supported. The
server executes the bounded batch inline and returns `202` with a completed
receipt, `Location`, and `status_url`; `GET /batch/{job_id}` retrieves that
receipt while it remains available. This is not a durable background queue and
does not accept billable retrieval paths.

## Safe content workflow

Resolve ontology tags first, select explicit `stream_ids`, call
`POST /manifests/plan`, then execute the exact planned request with only
`plan_token` added. Re-plan after changing any request field. Follow `next` and
`prev` links for GET lists and follow the opaque fully-qualified GET URLs
returned by `POST /manifests/query` verbatim with the same Authorization
header. Query scope is held server-side. `/manifests/exec` remains POST-only;
its paging values are hints to copy into a fresh request and plan token.

## References

- [OpenAPI contract](https://synorb.com/openapi.json)
- [Agent REST reference](https://synorb.com/api/llms.txt)
- [Runtime agent guide](https://synorb.com/agent-guide.md)
- [API versioning and deprecation policy](https://synorb.com/docs/api-versioning)