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

# 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`. An OAuth 2.0 access token minted
through the flow in the [authentication documentation](https://synorb.com/auth)
is sent in the same header and is accepted on every endpoint its granted scopes
cover.

## 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 usage allowance.

`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.

<!-- SYNORB:SKILLS:full:START -->
## Synorb Skills

Skills are jobs that a user sets up once, in the open Agent Skills format (`SKILL.md`).
The agent then runs each job on a Beacon on a schedule and reports only what is new.
Each skill is one Markdown file. The user's own model writes the result.

- [Synorb Setup](https://synorb.com/skills/synorb-setup.md) (`synorb-setup`): Connect Synorb once, see a first cited briefing, and set up the Beacons your skills run on.
- [Newsletter Writer](https://synorb.com/skills/newsletter-writer.md) (`newsletter-writer`): Set it up once. Every Monday your agent writes a new issue in your voice, every item cited.
- [Research Associate](https://synorb.com/skills/research-associate.md) (`research-associate`): Set it up once. Every week your agent sends a cited memo for your question, with evidence and open questions.
- [Podcast Producer](https://synorb.com/skills/podcast-producer.md) (`podcast-producer`): Set it up once. Every week your agent writes a two-host episode script, or a short spoken briefing every morning.
- [Launch Radar](https://synorb.com/skills/launch-radar.md) (`launch-radar`): Set it up once. Every week your agent reports what AI companies shipped, from their own announcements.
- [Thesis Tracker](https://synorb.com/skills/thesis-tracker.md) (`thesis-tracker`): Set it up once. Every month your agent reports what VC firms published, mapped to your thesis.
- [Podcast Digest](https://synorb.com/skills/podcast-digest.md) (`podcast-digest`): Set it up once. Every week your agent sends the arguments from the top business and tech podcasts.

Start with `synorb-setup` when you have no Synorb connection. Catalog: https://synorb.com/skills.json. Gallery: https://synorb.com/skills.

Install:

- Coding agents: `npx skills add Synorb/skills` (all skills), or `--skill <name>` for one.
- Any agent that can read a link: read `https://synorb.com/skills/<name>.md` and follow it.
- Upload: `https://synorb.com/skills/<name>.zip` holds the skill folder.
- When a skill gets a demo key, it sends `client` (REST) or `agent_name` (MCP) as `synorb-skill/<name>`.
<!-- SYNORB:SKILLS:full:END -->

## 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)