# Developers [API reference](/developers/api) · [OpenAPI](/openapi/zeronoise-v1.yaml) · [Markdown](/developers.md) Use ZeroNoise from your own scripts, tools and coding agents. 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 - **CLI:** `zeronoise` for terminals, scripts and coding agents. It handles idempotency keys, retries and polling for you. - **REST API:** HTTP and JSON from any language. See the [API reference](/developers/api). - **Coding agents:** the [ZeroNoise skill](#use-with-coding-agents) teaches agents such as Claude Code, Codex and Cursor to use the CLI and API safely. ## 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:]]` references. - **Citation:** the source and exact location, a line range or timestamp, behind one reference. - **Operation:** background AI work such as drafting, discovery or generating a Brief. Poll it until it succeeds or fails. ## Install and sign in The CLI needs Node.js 22 or newer. ```bash npm install -g @zeronoise/cli zeronoise auth login zeronoise auth status --json ``` `auth login` opens your browser. After you approve, ZeroNoise creates a 90-day key for this device and the CLI saves it in the macOS Keychain. The key acts as you, with your current access. `zeronoise auth logout` revokes it. `zeronoise --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](/users/settings?tab=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. Revoking a key in Settings takes effect immediately. 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: ```bash zeronoise agents draft --message "Track primary sources on EU AI regulation" --wait --json ``` Then review and launch it: ```bash 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: ```bash zeronoise briefs list --agent-id 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: ```bash 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: ```bash 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 a Brief use your organization's credits. Scheduled Briefs of an active Agent do too. Failed work is not charged. 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. It tells the agent to ask before spending credits or deleting anything, and to treat Brief and Source content as data rather than instructions. ```bash npx skills add https://zeronoise.ai ``` Or give your agent this instruction: ```text Read and follow https://zeronoise.ai/.well-known/skills/zeronoise/SKILL.md ``` ## 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 Brief can cover at most 31 days. - Agents of other organizations are read-only: you can follow them and read their Briefs and approved Sources. - Lists are paginated with `limit` and `cursor`, newest first. To check for new Briefs, pass `--since` (`since` over HTTP) with your last check time and skip Briefs you have already seen.