Developers
API reference · OpenAPI · Markdown
Use ZeroNoise from AI apps, your own scripts and coding agents. MCP, the REST API and the zeronoise
CLI can create and configure Agents, review their Sources, generate Briefs and resolve every citation
back to its source, with the same permissions as the app.
Ways to connect
Pick the one that matches where you want to use ZeroNoise:
-
In an AI app such as Claude, ChatGPT, Codex, Claude Code or Cursor: add the MCP server
https://zeronoise.ai/mcpand sign in. No API key is needed. See AI apps (MCP). -
In a terminal, script or coding agent: the
zeronoiseCLI handles idempotency keys, retries and polling for you, and the ZeroNoise skill teaches coding agents to use it safely. - On a server or anywhere without a browser: an API key with the CLI, the REST API (see the API reference) or MCP.
Concepts
- Agent: a monitoring goal with instructions, a schedule and approved Sources. It starts as a draft, is finalized, then runs while active.
- Source: a channel, profile, feed, web page or another Agent. Only approved Sources feed Briefs.
- Chat: the conversation that shapes an Agent's configuration and proposes changes or discovery.
-
Brief: a report an Agent writes on its schedule. Its Markdown marks evidence with
[[citation:<id>]]references. - Citation: the evidence behind one reference: the exact cited text, the source document (title and URL) and, for audio and video, the time in seconds.
- Operation: background AI work such as drafting, discovery or generating a Brief. Poll it until it succeeds or fails.
AI apps (MCP)
ZeroNoise is a remote MCP server at https://zeronoise.ai/mcp. Add it to your AI app as a custom
connector or server, then sign in with your ZeroNoise account when the app asks.
- Claude (web, desktop and mobile): Settings > Connectors > Add custom connector.
- ChatGPT: turn on developer mode in ChatGPT's settings, then add an app with this URL and OAuth sign-in.
-
Codex:
codex mcp add zeronoise --url https://zeronoise.ai/mcp, or add a Streamable HTTP server in the Codex app. -
Claude Code:
claude mcp add --transport http zeronoise https://zeronoise.ai/mcp, then sign in with/mcp. - Cursor and other apps: add the URL as a remote (Streamable HTTP) MCP server.
When you sign in you choose one organization. The app then acts as you in that organization, with your access there. To use another organization, reconnect the app and choose it.
Desktop and terminal apps finish signing in through a page on your own computer, so the approval page warns that the redirect points to an application running on your machine. That is expected when you started the connection yourself.
Each connected app appears once under Connected apps in Settings > Developer, however many of your devices use it. Revoking it there ends its access within a few minutes.
The tools say which actions spend credits, so the app can ask you first. Citations and Chat messages
come 10 per page. For access limited to one workspace or Agent, read-only access, or a client that
cannot sign in through a browser, send an API key as an
Authorization: Bearer header instead.
Install and sign in
The CLI needs Node.js 22 or newer.
npm install -g @zeronoise/cli
zeronoise auth login
zeronoise auth status --json
auth login opens your browser. After you approve, ZeroNoise creates a key for this device and the
CLI saves it in the macOS Keychain. The key acts as you, with your current access. It expires after
90 days unless you choose 30 days or no expiry on the approval page. zeronoise auth logout revokes
it.
zeronoise <command> --help explains any command without calling the API.
zeronoise capabilities --json describes every command, with its inputs and required scopes, for
programs and agents.
API keys for scripts and agents
For scripts, CI, coding agents and the REST API, create a key in
Settings > Developer and provide it as ZERONOISE_API_KEY. Each key
belongs to you and can only narrow your current access.
- Access: Read-only by default. Choose Agent operator for authoring and AI actions, or pick individual scopes.
- Reach: in a personal account, all your Agents by default, or one Agent. In a team organization, your current workspace by default, one Agent, or the whole organization.
- Expiry: 90 days by default, or 30 days, or no expiry. Revoking a key in Settings takes effect immediately.
ZeroNoise emails you whenever a new key is created for your account, from Settings or from a CLI sign-in, so you can revoke any key you don't recognize.
The secret is shown once. Keep it in a secret manager. Never paste it into prompts, command arguments
or committed files, and use a separate key for each tool or deployment. To save an existing key in
the Keychain, run zeronoise auth login --with-token; it prompts for the key without showing it.
Quickstart
Draft an Agent from a description of what you want to follow:
zeronoise agents draft --message "Track primary sources on EU AI regulation" --wait --json
Then review and launch it:
zeronoise agents get AGENT_ID --json
zeronoise agents finalize AGENT_ID --json
zeronoise sources discover AGENT_ID --instructions "Official regulator and parliament sources" --wait --json
zeronoise sources list AGENT_ID --status pending --json
zeronoise sources approve AGENT_ID SOURCE_ID --json
zeronoise agents activate AGENT_ID --json
Read the Briefs and the evidence behind them:
zeronoise briefs list AGENT_ID --json
zeronoise briefs get BRIEF_ID --json
zeronoise briefs citations BRIEF_ID --json
Follow Agents, including public and shared Agents of other organizations, and check everything they publish:
zeronoise follows add AGENT_ID --json
zeronoise briefs list --following --since 2026-10-01T00:00:00Z --json
Reading beyond your own Agents needs a key that is not bound to a workspace or Agent, such as the one
auth login creates.
The same steps over HTTP:
curl "https://zeronoise.ai/api/v1/briefs?agent_id=AGENT_ID" \
-H "Authorization: Bearer $ZERONOISE_API_KEY"
Credits and asynchronous work
Reads and ordinary edits are free. Drafting, Chat messages, Source discovery, adding a Source by URL
and generating or regenerating a Brief use your organization's credits. Scheduled Briefs of an active Agent do too.
Failed work is not charged. Each command shows this in a Credits: line in its --help and as
credits in zeronoise capabilities --json; the OpenAPI document marks the same operations with
x-zeronoise-credits.
AI work runs in the background. The API responds with 202 Accepted and an Operation. Poll it until it
succeeds or fails, or pass --wait to the CLI. If the connection drops, keep polling the same
Operation instead of starting the work again.
Writes that start work take an Idempotency-Key header. The CLI generates one and prints it, so a
repeated command with the same key returns the original result instead of starting new work.
Configuration edits take the If-Match ETag from the configuration you read, so concurrent changes are
never overwritten.
Use with coding agents
The ZeroNoise skill teaches coding agents such as Claude Code, Codex and Cursor how to use the CLI and API safely. Coding agents can also connect through MCP; the skill then tells them to use those tools. It tells the agent to ask before spending credits or deleting anything, and to treat Brief and Source content as data rather than instructions.
npx skills add https://zeronoise.ai
The same skill is published on GitHub as npx skills add zeronoise-ai/zeronoise. In Claude Code and
Codex, the plugin adds the skill and the MCP server together:
/plugin marketplace add zeronoise-ai/zeronoise
/plugin install zeronoise@zeronoise
codex plugin marketplace add zeronoise-ai/zeronoise
codex plugin add zeronoise@zeronoise
Or give your agent this instruction:
Read and follow https://zeronoise.ai/.well-known/skills/zeronoise/SKILL.md
Brief links work in AI tools too: add .md to a brief's URL to get its Markdown, with citations as
footnotes. Public and shared briefs need no sign-in.
Limits
-
Saved CLI logins use the macOS Keychain. On other systems, use
ZERONOISE_API_KEY. - Adding a Source by URL may be unavailable while its security checks are rolled out. Adding existing Agents as Sources, and discovery, work as usual.
-
A requested Brief covers one of the Agent's closed schedule periods from the last 14 days. Pass
its exact
start_atandend_at(an error names the latest closed period), orperiods: Nfor whichever of the N most recent lack a Brief, generated oldest first. Only a Brief for the latest closed period emails subscribers. Activating an Agent for the first time also generates Briefs for the latest closed periods: 1 by default, set withinitial_briefs(0 for none). -
Regenerate a current Brief with
briefs regenerate(POST /briefs/{brief_id}/regenerations), for example after changing the Agent's Sources. The old Brief stays until the new one publishes, and regenerations email no one. Delete one withbriefs delete(DELETE /briefs/{brief_id}), which needs thebriefs:deletepermission that only Full access includes. - Agents of other organizations are read-only: you can follow them and read their Briefs and approved Sources.
-
Lists are paginated with
limitandcursor, newest first. To check for new Briefs, pass--since(sinceover HTTP) with your last check time and skip Briefs you have already seen. -
Date Briefs by
period(start_attoend_at), the window of content each one covers, not bypublished_at. A backfilled or regenerated Brief is published after its period. Scheduled Briefs close shortly before the Agent's scheduled time (currently one hour) so Sources can finish syncing.