Skip to main content
Agents work in Nohead next to people. Coding agents such as Claude Code, Cursor or Codex, chat apps, agent frameworks, CI jobs and scripts use the same public API as the web app, each with an API key of its own. Every change they make is attributed to that key and kept in history, so you can see what an agent did, and why, and undo it.

​
Pick an interface

For a coding agent, the CLI is usually the best fit: --json output and exit codes cost it less context than a list of tools.

​
Give each agent its own key

In the web app, open your project’s API keys page and choose New API key. Give the agent a key of its own, with only the scopes its job needs: New keys are published-only by default (Published records only): they read published records and nothing else, which is what a site needs. Turn it off for a key that writes, reads unpublished content or history, manages webhooks or reads the activity log. Published-only keys start with nohead_pk_, the others with nohead_sk_.
Keep the key in a secret store, such as your CI’s, never in the repository.
The CLI and the SDKs read the key from NOHEAD_API_KEY. A key belongs to one project, so with NOHEAD_API_KEY an agent never needs a project ID. With a key per agent or pipeline, history shows which one made each change, and revoking a key stops only that one. On your own machine, nohead login makes the key for you, and nohead link keeps a folder in its project: see Projects.

​
What keeps changes safe

Whichever interface an agent uses, the same API stands behind it:
  • Attributed. History shows each change with the key’s name and the client it came through, such as the CLI or MCP.
  • Explained. A change can carry a note saying why, kept in history next to it: --note in the CLI, a required note on every MCP tool that changes a record, Nohead-Change-Note over HTTP.
  • Reviewed. With the CLI, the MCP server, an SDK or the API, an agent can propose changes as a draft that a person merges. New records start unpublished.
  • No lost edits. A change can name the revision the agent read (--if-revision, expected_revision, If-Match), and is refused if someone changed the record since.
  • Safe retries. With an idempotency key, retrying a write never applies it twice.
  • Reversible. Every record change is a revision you can revert, and deleted records, fields, collections and assets can be restored for 30 days.
Coding agents and MCP server show these in practice.

​
Point the agent at the API

The API serves /llms.txt, a plain-text map of every endpoint and the API’s conventions, generated from the same contract the API is tested against. It suits an agent’s context better than the full contract, /openapi.json: