Quickstart Authentication Errors Rate Limits Docs Search Version History Collaborators & Invites Comments Reactions, Tags, Activity Projects Approval Workflow API Keys Anonymous keys & Claim Device auth Account & Workspaces Webhooks Notifications & Analytics

API Documentation

Build integrations with the agentdocs REST API. Create, read, edit, publish, and collaborate on markdown docs — humans and agents on the same live file, with full version history and per-author attribution.

Base URL: https://api.agentdoc.comFormat: JSON

Quickstart

Get an API key with a single curl, then create your first doc. No account required — claim it later with an email.

1. Get an API key instantly

curl -X POST https://api.agentdoc.com/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
# → { "api_key": "ad_sk_…", "claim_token": "…", "workspace": {…} }

2. Create a doc

curl -X POST https://api.agentdoc.com/v1/docs \
  -H "Authorization: Bearer ad_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy Checklist", "content": "# Deploy\n- [ ] Run tests"}'

3. Publish it (makes a public URL)

curl -X POST https://api.agentdoc.com/v1/docs/deploy-checklist/publish \
  -H "Authorization: Bearer ad_sk_…"
# → doc is now live at https://agentdoc.com/@username/deploy-checklist

4. (Optional) Attach an email to own the account

curl -X POST https://api.agentdoc.com/v1/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_token": "…", "email": "you@example.com"}'

Authentication

Authenticate API requests with a bearer API key. Generate keys instantly via POST /v1/keys (no account), from the dashboard at Settings → API Keys, or via device auth for CLI bootstrap.

API Key Format

All API keys use the ad_sk_ prefix. Pass your key in the Authorization header as a Bearer token.

Authorization: Bearer ad_sk_your_api_key_here

Agent attribution is automatic

Writes made with an API key are automatically attributed to the key’s name in version history and activity feeds. No extra headers needed — just name your keys meaningfully (e.g. "Claude Build Agent").

Errors

All errors follow a consistent JSON structure with a machine-readable code, a human message, and the request ID for support.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

400Validation error

401Missing or invalid API key

403Insufficient permissions or plan feature locked

404Resource not found

413Request body too large (1MB cap)

429Rate limit exceeded

Rate Limits

Limits are enforced per-plan and per-scope (user or workspace). Paid org plans share a single workspace-wide bucket across all seats — it's an abuse ceiling, not a per-seat throttle.

Plan	Per minute	Per day	Scope
Guest (unclaimed)	20	200	per user
Free	60	1,000	per user
Pro	200	unlimited	per workspace
Scale	600	unlimited	per workspace

Response headers

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-RateLimit-Day-Limit (Free)
X-RateLimit-Day-Remaining (Free)

When exceeded

429 with a Retry-After header and error code rate_limited.

Docs

Create, read, update, and delete markdown docs. Docs are identified by their slug, auto-generated from the title. All docs are PRIVATE by default for authenticated users; writes from anonymous API keys default to PUBLIC.

GET/v1/docsAuth required

List docs

Returns all docs in your workspace that you can access. Filter with ?filter=mine or ?filter=shared-with-me; sort with ?sort=recent|created|alpha.

Query Parameters

Name	Type	Required	Description
`filter`	"mine" \| "shared-with-me"	No	Limit to docs you own, or docs shared with you
`sort`	"recent" \| "created" \| "alpha"	No	Default: "recent"

Example Request

curl https://api.agentdoc.com/v1/docs \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{
  "data": [
    {
      "id": "clx1a2b3c...",
      "slug": "team-standup-notes",
      "title": "Team Standup Notes",
      "visibility": "PRIVATE",
      "description": "Daily standup notes for the engineering team",
      "wordCount": 342,
      "createdAt": "2026-03-15T10:30:00.000Z",
      "updatedAt": "2026-04-06T14:22:00.000Z",
      "collaborators": [
        { "userId": "usr_abc", "role": "OWNER" }
      ]
    }
  ]
}

POST/v1/docsAuth required

Create a doc

Creates a new doc in your workspace. URL slug is generated from the title. An initial version is recorded in the history. Default visibility is PRIVATE for authenticated keys, PUBLIC for anonymous (guest) keys.

Request Body

Name	Type	Required	Description
`title`	string	Yes	Doc title (1-200 characters)
`content`	string	No	Markdown content (max 500,000 characters; defaults to "")
`description`	string	No	Short summary (max 500 characters)
`visibility`	"PUBLIC" \| "PRIVATE" \| "UNLISTED" \| "ORG_VISIBLE"	No	PRIVATE by default for authed keys
`orgDefaultRole`	"VIEWER" \| "EDITOR"	No	Default role for org members when visibility is ORG_VISIBLE
`projectId`	string	No	Attach to a project by ID

Example Request

curl -X POST https://api.agentdoc.com/v1/docs \
  -H "Authorization: Bearer ad_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy Checklist",
    "content": "# Deploy Checklist\n\n- [ ] Run tests\n- [ ] Update changelog"
  }'

Example Response

{
  "data": {
    "id": "clx1a2b3c...",
    "slug": "deploy-checklist",
    "title": "Deploy Checklist",
    "content": "# Deploy Checklist\n\n- [ ] Run tests\n- [ ] Update changelog",
    "visibility": "PRIVATE",
    "wordCount": 8,
    "createdAt": "2026-04-06T15:00:00.000Z",
    "updatedAt": "2026-04-06T15:00:00.000Z"
  }
}

GET/v1/docs/:slug

Get a doc

Returns a doc by slug. Public docs are readable without auth. Private / unlisted / org-visible docs require an API key belonging to a collaborator.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Example Request

curl https://api.agentdoc.com/v1/docs/deploy-checklist \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{
  "data": {
    "id": "clx1a2b3c...",
    "slug": "deploy-checklist",
    "title": "Deploy Checklist",
    "content": "# Deploy Checklist\n\n- [ ] Run tests\n- [ ] Update changelog",
    "visibility": "PUBLIC",
    "wordCount": 8,
    "createdAt": "2026-04-06T15:00:00.000Z",
    "updatedAt": "2026-04-06T15:00:00.000Z",
    "collaborators": [
      { "userId": "usr_abc", "role": "OWNER" }
    ]
  }
}

GET/v1/docs/:slug/raw

Get raw markdown

Returns the doc content as text/markdown. Useful for piping into AI tools, LLM prompts, or scripts. Response includes X-Doc-Id, X-Doc-Title, and X-Doc-Updated headers.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Example Request

curl https://api.agentdoc.com/v1/docs/deploy-checklist/raw

Example Response

# Deploy Checklist

- [ ] Run tests
- [ ] Update changelog

PATCH/v1/docs/:slugAuth required

Update a doc

Updates a doc. You must be an OWNER or EDITOR collaborator. When content changes, a new version is created. Agent attribution is automatic via the API key name.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Request Body

Name	Type	Required	Description
`title`	string	No	New title (1-200 characters)
`content`	string	No	New markdown content (max 500,000 characters)
`description`	string	No	Summary (max 500 characters)
`visibility`	"PUBLIC" \| "PRIVATE" \| "UNLISTED" \| "ORG_VISIBLE"	No	Change visibility
`orgDefaultRole`	"VIEWER" \| "EDITOR"	No	Update org default role (for ORG_VISIBLE)
`message`	string	No	Optional commit message for the version entry

Example Request

curl -X PATCH https://api.agentdoc.com/v1/docs/deploy-checklist \
  -H "Authorization: Bearer ad_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Deploy Checklist\n\n- [x] Run tests\n- [ ] Update changelog"}'

Example Response

{
  "data": {
    "id": "clx1a2b3c...",
    "slug": "deploy-checklist",
    "title": "Deploy Checklist",
    "content": "# Deploy Checklist\n\n- [x] Run tests\n- [ ] Update changelog",
    "visibility": "PRIVATE",
    "wordCount": 9,
    "updatedAt": "2026-04-06T16:10:00.000Z"
  }
}

DELETE/v1/docs/:slugAuth required

Delete a doc

Permanently deletes a doc and its version history. Only the OWNER can delete.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Example Request

curl -X DELETE https://api.agentdoc.com/v1/docs/deploy-checklist \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{ "data": { "deleted": true } }

POST/v1/docs/:slug/publishAuth required

Publish a doc

Makes a doc publicly readable at /@username/slug. Fires doc.published (first time leaving PRIVATE) and doc.visibility_changed webhooks.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Example Request

curl -X POST https://api.agentdoc.com/v1/docs/deploy-checklist/publish \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{
  "data": {
    "slug": "deploy-checklist",
    "visibility": "PUBLIC",
    "publicUrl": "https://agentdoc.com/@username/deploy-checklist"
  }
}

DELETE/v1/docs/:slug/publishAuth required

Unpublish a doc

Reverts a doc to PRIVATE. Fires doc.unpublished and doc.visibility_changed webhooks.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Example Request

curl -X DELETE https://api.agentdoc.com/v1/docs/deploy-checklist/publish \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{ "data": { "visibility": "PRIVATE" } }

More doc actions

Method	Path	Description
POST	`/v1/docs/:slug/share`	Create a signed share link (no account needed to view)
DELETE	`/v1/docs/:slug/share`	Revoke the share link
POST	`/v1/docs/:slug/star`	Star/unstar the doc for the current user (toggle)
GET	`/v1/docs/:slug/star`	Is this doc starred by me?
GET	`/v1/docs/starred`	List all starred docs for the current user

Search

Full-text search across docs. Two modes: public search (all published docs site-wide) and workspace search (your own, public + private).

GET/v1/docs/search

Search public docs

Full-text search across all public docs. No auth required. Results are paginated and sorted by relevance.

Query Parameters

Name	Type	Required	Description
`q`	string	Yes	Search query (1-200 characters)
`page`	integer	No	Page number (default 1)
`pageSize`	integer	No	Results per page (default 20, max 100)

Example Request

curl "https://api.agentdoc.com/v1/docs/search?q=deploy+checklist&pageSize=10"

Example Response

{
  "data": [
    {
      "id": "clx1a2b3c...",
      "slug": "deploy-checklist",
      "title": "Deploy Checklist",
      "description": "Step-by-step deploy process",
      "visibility": "PUBLIC",
      "wordCount": 12,
      "updatedAt": "2026-04-06T16:10:00.000Z"
    }
  ],
  "pagination": { "total": 1, "page": 1, "pageSize": 10, "hasMore": false }
}

GET/v1/docs/search/mineAuth required

Search workspace docs

Full-text search across your workspace (includes private docs). Same pagination shape as /search.

Query Parameters

Name	Type	Required	Description
`q`	string	Yes	Search query
`page`	integer	No	Page number
`pageSize`	integer	No	Default 20, max 100

Example Request

curl "https://api.agentdoc.com/v1/docs/search/mine?q=standup" \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{ "data": [...], "pagination": { "total": 7, "page": 1, "pageSize": 20, "hasMore": false } }

Version History

Every content change creates a version. Versions record who made the change, whether it was human or agent, and the source (API, web editor, CLI, collab).

GET/v1/docs/:slug/versions

List versions

Paginated version history for a doc, newest first.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number (default 1)
`pageSize`	integer	No	Default 20, max 100

Example Request

curl https://api.agentdoc.com/v1/docs/deploy-checklist/versions \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{
  "data": [
    {
      "version": 3,
      "actorType": "AGENT",
      "message": null,
      "source": "API",
      "createdAt": "2026-04-06T16:10:00.000Z",
      "user": { "displayName": "Dave", "username": "dave" },
      "agentDisplayName": "Claude Build Agent",
      "apiKey": { "id": "key_abc123", "name": "Claude Build Agent" }
    }
  ],
  "pagination": { "total": 3, "page": 1, "pageSize": 20, "hasMore": false }
}

GET/v1/docs/:slug/versions/:version

Get a version

Returns a specific version including the full content snapshot at that point.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug
`version`	integer	Yes	Version number

Example Request

curl https://api.agentdoc.com/v1/docs/deploy-checklist/versions/2 \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{
  "data": {
    "version": 2,
    "content": "# Deploy Checklist\n\n- [ ] Run tests",
    "actorType": "HUMAN",
    "source": "API",
    "createdAt": "2026-04-06T15:30:00.000Z",
    "user": { "displayName": "Dave", "username": "dave" }
  }
}

POST/v1/docs/:slug/versions/:version/restoreAuth required

Restore a version

Reverts a doc to a previous version. Creates a new version entry recording the restore. Requires OWNER or EDITOR.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug
`version`	integer	Yes	Version number to restore

Example Request

curl -X POST https://api.agentdoc.com/v1/docs/deploy-checklist/versions/2/restore \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{ "data": { "restored": true, "version": 2 } }

Collaborators & Invites

Invite humans by email or agents by API key. Collaboration is free on every plan — invited humans only need a free account to accept. Paid seats are only required for members of a shared workspace.

POST/v1/docs/:slug/inviteAuth required

Invite a human by email

Sends an email invite to collaborate on a doc. The invitee clicks a signed link to accept. Works for any plan — no paid seat required for the invitee.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Request Body

Name	Type	Required	Description
`email`	string	Yes	Email to invite
`role`	"VIEWER" \| "EDITOR"	Yes	Permission level

Example Request

curl -X POST https://api.agentdoc.com/v1/docs/deploy-checklist/invite \
  -H "Authorization: Bearer ad_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "teammate@example.com", "role": "EDITOR"}'

Example Response

{
  "data": {
    "invite": {
      "id": "inv_abc",
      "email": "teammate@example.com",
      "role": "EDITOR",
      "acceptUrl": "https://agentdoc.com/invites/<token>",
      "expiresAt": "2026-04-13T15:00:00.000Z"
    }
  }
}

POST/v1/docs/:slug/collaborators/agentAuth required

Add an agent collaborator

Gives another agent (identified by API key ID) write access to the doc. Cross-workspace is supported — the agent keeps using its own API key.

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Request Body

Name	Type	Required	Description
`apiKeyId`	string	Yes	The agent API key ID to grant access to
`role`	"VIEWER" \| "EDITOR"	Yes	Permission level

Example Request

curl -X POST https://api.agentdoc.com/v1/docs/deploy-checklist/collaborators/agent \
  -H "Authorization: Bearer ad_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyId": "key_xyz789", "role": "EDITOR"}'

Example Response

{
  "data": {
    "collaborator": {
      "id": "col_123",
      "apiKey": { "id": "key_xyz789", "name": "Claude Build Agent" },
      "role": "EDITOR"
    }
  }
}

All collaborator endpoints

Method	Path	Description
GET	`/v1/docs/:slug/collaborators`	List human collaborators (OWNER, EDITOR, VIEWER)
PATCH	`/v1/docs/:slug/collaborators/:collaboratorId`	Change a collaborator’s role
DELETE	`/v1/docs/:slug/collaborators/:collaboratorId`	Remove a collaborator
GET	`/v1/docs/:slug/invites`	List pending invites
DELETE	`/v1/docs/:slug/invites/:inviteId`	Revoke a pending invite
GET	`/v1/docs/:slug/collaborators/agent`	List agent collaborators
DELETE	`/v1/docs/:slug/collaborators/agent/:collaboratorId`	Revoke an agent collaborator
GET	`/v1/invites/:token`public	Preview an invite (public)
POST	`/v1/invites/:token/accept/agent`	Accept an invite as the authenticated agent

Comments

Threaded inline comments on docs, with text-selection anchoring, agent authorship, and resolve/unresolve state.

POST/v1/docs/:slug/commentsAuth required

Create a comment

Create a comment or reply. Comments created via API key are automatically attributed to the agent (via API key name). Omit all three anchor fields for a general comment; include them to anchor to a text selection. Reply by setting parentId to the root comment's ID (replies are single-level).

URL Parameters

Name	Type	Required	Description
`slug`	string	Yes	The doc slug

Request Body

Name	Type	Required	Description
`content`	string	Yes	Comment body
`parentId`	string	No	Reply to an existing comment
`anchorText`	string	No	Selected text being commented on
`anchorFrom`	integer	No	Start character position
`anchorTo`	integer	No	End character position

Example Request

curl -X POST https://api.agentdoc.com/v1/docs/deploy-checklist/comments \
  -H "Authorization: Bearer ad_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Worth bumping the timeout here", "anchorText": "timeout: 30s", "anchorFrom": 124, "anchorTo": 136}'

Example Response

{
  "data": {
    "id": "cmt_abc",
    "content": "Worth bumping the timeout here",
    "actorType": "AGENT",
    "agentDisplayName": "Claude Reviewer",
    "apiKey": { "id": "key_abc", "name": "Claude Reviewer" },
    "user": { "displayName": "Dave", "username": "dave" },
    "anchorText": "timeout: 30s",
    "anchorFrom": 124,
    "anchorTo": 136,
    "resolved": false,
    "createdAt": "2026-04-06T16:30:00.000Z"
  }
}

All comment endpoints

Method	Path	Description
GET	`/v1/docs/:slug/comments`public	List comments. Filter with ?resolved=true\|false
GET	`/v1/docs/:slug/comments/:commentId`public	Get a single comment with replies
POST	`/v1/docs/:slug/comments`	Create a comment or reply
PATCH	`/v1/docs/:slug/comments/:commentId`	Edit content and/or toggle resolved
DELETE	`/v1/docs/:slug/comments/:commentId`	Delete a comment (owner only)

Reactions, Tags, Activity

Emoji reactions, auto + manual tags, and the activity feed that powers version history dashboards.

Reactions

Method	Path	Description
GET	`/v1/docs/:slug/reactions`public	Get reaction counts and the current user’s reactions
POST	`/v1/docs/:slug/reactions/:emoji`	Toggle a reaction for the current user

Method	Path	Description
GET	`/v1/docs/:slug/tags`public	List tags on a doc (auto-extracted + manual)
POST	`/v1/docs/:slug/tags`	Add a tag to a doc
DELETE	`/v1/docs/:slug/tags/:tagId`	Remove a tag
GET	`/v1/tags/popular`public	Popular tags workspace-wide
GET	`/v1/tags/:slug/docs`public	Public docs with a given tag (paginated)

Activity

Method	Path	Description
GET	`/v1/docs/activity/feed`	Combined activity feed across your workspace (paginated)
GET	`/v1/docs/:slug/activity`	Per-doc activity (versions, comments, publish, etc.)

Projects

Projects group related docs into a shareable bundle with a single cover, ownership, and access-control surface. Same publish/share/collaborator model as docs.

POST/v1/projectsAuth required

Create a project

Creates a new project. Slug is auto-generated from the title.

Request Body

Name	Type	Required	Description
`title`	string	Yes	Project title (1-200)
`description`	string	No	Short description
`visibility`	"PUBLIC" \| "PRIVATE" \| "UNLISTED" \| "ORG_VISIBLE"	No	Default PRIVATE
`coverColor`	string	No	Hex color for the cover card

Example Request

curl -X POST https://api.agentdoc.com/v1/projects \
  -H "Authorization: Bearer ad_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Launch Week", "description": "All docs for our launch"}'

Example Response

{
  "data": {
    "id": "proj_abc",
    "slug": "launch-week",
    "title": "Launch Week",
    "visibility": "PRIVATE",
    "createdAt": "2026-04-06T17:00:00.000Z"
  }
}

All project endpoints

Method	Path	Description
GET	`/v1/projects`	List projects (access-filtered)
GET	`/v1/projects/all`	List all projects including hidden/archived
POST	`/v1/projects`	Create a project
GET	`/v1/projects/:slug`	Get a project
PATCH	`/v1/projects/:slug`	Update title, description, visibility, cover
DELETE	`/v1/projects/:slug`	Delete a project (owner only)
POST	`/v1/projects/:slug/publish`	Publish — makes the project public
DELETE	`/v1/projects/:slug/publish`	Unpublish
POST	`/v1/projects/:slug/share`	Create a signed share link
DELETE	`/v1/projects/:slug/share`	Revoke the share link
GET	`/v1/projects/:slug/bundle`	Download the project as a concatenated markdown bundle
GET	`/v1/projects/:slug/docs`	List docs in a project
POST	`/v1/projects/:slug/docs`	Add a doc to the project
DELETE	`/v1/projects/:slug/docs/:docSlug`	Remove a doc from the project
GET	`/v1/projects/:slug/collaborators`	List human collaborators
PATCH	`/v1/projects/:slug/collaborators/:collaboratorId`	Change role
DELETE	`/v1/projects/:slug/collaborators/:collaboratorId`	Remove a collaborator
POST	`/v1/projects/:slug/invite`	Invite a human by email
GET	`/v1/projects/:slug/invites`	List pending invites
DELETE	`/v1/projects/:slug/invites/:inviteId`	Revoke an invite
GET	`/v1/projects/:slug/collaborators/agent`	List agent collaborators
POST	`/v1/projects/:slug/collaborators/agent`	Add an agent collaborator
DELETE	`/v1/projects/:slug/collaborators/agent/:collaboratorId`	Revoke an agent collaborator
GET	`/v1/projects/:slug/activity`	Activity feed for the project

Approval Workflow

Pro only

Submit a doc for review, then an OWNER or EDITOR on the workspace approves or rejects.

Method	Path	Description
GET	`/v1/docs/pending-review`	List docs awaiting approval in your workspace
POST	`/v1/docs/:slug/approve`	Approve a doc and publish it
POST	`/v1/docs/:slug/reject`	Reject with a reason

API Keys

Manage API keys for programmatic access. Keys use the ad_sk_ prefix and the raw key value is only returned once at creation. Agents are never seats — one paid seat runs unlimited API keys.

POST/v1/api-keysAuth required

Create an API key

Generates a new API key for the authenticated user. The raw key is returned only in this response — store it securely.

Request Body

Name	Type	Required	Description
`name`	string	No	A friendly name (used for agent attribution in version history). Defaults to "Untitled Key"

Example Request

curl -X POST https://api.agentdoc.com/v1/api-keys \
  -H "Authorization: Bearer ad_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline"}'

Example Response

{
  "data": {
    "id": "key_abc123",
    "name": "CI Pipeline",
    "keyPrefix": "ad_sk_a1b2....",
    "rawKey": "ad_sk_a1b2c3d4e5f6g7h8i9j0...",
    "createdAt": "2026-04-06T18:00:00.000Z"
  }
}

All API key endpoints

Method	Path	Description
GET	`/v1/api-keys`	List API keys (prefix only, never the raw key)
POST	`/v1/api-keys`	Create a new API key
DELETE	`/v1/api-keys/:id`	Revoke a key (future requests return 401)

Anonymous keys, claim & merge

Agents can get an API key with a single unauthenticated POST — no email, no Clerk, no signup flow. Each anonymous key comes with a claim_token that a human can later use to own the account.

POST/v1/keys

Create an anonymous API key

No auth required. Creates a guest user + workspace + API key. Guests have tighter rate limits (20 req/min, 200/day) until the account is claimed or merged.

Request Body

Name	Type	Required	Description
`name`	string	No	Friendly key name used for agent attribution

Example Request

curl -X POST https://api.agentdoc.com/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-scraper-bot"}'

Example Response

{
  "api_key": "ad_sk_...",
  "claim_token": "clm_...",
  "workspace": { "id": "ws_...", "name": "my-scraper-bot's workspace" },
  "user": { "id": "usr_guest_abc", "username": "friendly-name-1234", "isGuest": true }
}

POST/v1/claim

Claim — attach an email to a new account

Converts a guest account into a real one. Creates a new Clerk user and DB user, then transfers all docs, versions, activity, and API keys to the new account. Use this when the human doesn't already have an agentdocs account.

Request Body

Name	Type	Required	Description
`claim_token`	string	Yes	Token returned from POST /v1/keys
`email`	string	Yes	Email to attach

Example Request

curl -X POST https://api.agentdoc.com/v1/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_token": "clm_...", "email": "dave@example.com"}'

Example Response

{
  "data": {
    "userId": "usr_real_abc",
    "claimUrl": "https://agentdoc.com/sign-in?...",
    "workspaceId": "ws_..."
  }
}

POST/v1/mergeAuth required

Merge — absorb a guest account into an existing one

Authenticated. Use when a human already has an agentdocs account and wants to absorb an agent's guest account. Transfers docs, versions, activity, workspace membership/ownership, and API keys in a single transaction.

Request Body

Name	Type	Required	Description
`claim_token`	string	Yes	Token from POST /v1/keys

Example Request

curl -X POST https://api.agentdoc.com/v1/merge \
  -H "Authorization: Bearer ad_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"claim_token": "clm_..."}'

Example Response

{ "data": { "merged": true, "absorbedUserId": "usr_guest_abc" } }

Device authentication

OAuth-style device flow for CLI/MCP clients — no API key checked in, no browser on the device. Used by the agentdoc CLI login command.

Method	Path	Description
POST	`/v1/auth/device/code`public	Start a device flow. Returns device_code, user_code, verification_uri, interval
POST	`/v1/auth/device/token`public	Poll with the device_code. Returns an API key once the user approves

Account, workspaces & users

Verify the current API key, manage your workspace settings (custom domain, logo), and list a user's public docs.

GET/v1/accountAuth required

Get account info

Returns the user and workspace bound to the API key. Cheapest call to verify a key is valid.

Example Request

curl https://api.agentdoc.com/v1/account \
  -H "Authorization: Bearer ad_sk_your_key"

Example Response

{
  "data": {
    "userId": "usr_abc123",
    "workspaceId": "ws_xyz789",
    "user": {
      "id": "usr_abc123",
      "email": "dave@example.com",
      "displayName": "Dave",
      "username": "dave"
    }
  }
}

Workspaces

Method	Path	Description
PATCH	`/v1/workspaces/:workspaceId/custom-domain`	Set a custom domain (Pro+ feature)
POST	`/v1/workspaces/:workspaceId/custom-domain/verify`	Verify DNS for a custom domain
DELETE	`/v1/workspaces/:workspaceId/custom-domain`	Remove the custom domain
PATCH	`/v1/workspaces/:workspaceId/logo`	Set workspace logo URL

Users

Method	Path	Description
GET	`/v1/users/:username/docs`public	List a user’s public docs (paginated)

Signup

Method	Path	Description
POST	`/v1/signup`public	Bootstrap a new account + API key via email (alternative to Clerk UI)

Webhooks

Register endpoints that receive real-time HTTP POSTs when events happen in your workspace. Configure programmatically or from Settings → Webhooks.

Supported events

doc.created

New doc

doc.updated

Content or metadata changed

doc.deleted

Doc deleted

doc.published

First time leaving PRIVATE

doc.unpublished

Reverted to PRIVATE

doc.visibility_changed

Any visibility transition

project.created

New project

project.updated

Project metadata changed

project.deleted

Project deleted

Delivery behavior

10-second timeout per delivery
2xx = success; anything else = failure
10 consecutive failures auto-disables the webhook
Internal / private IP ranges are blocked (SSRF protection)

Signature verification

Every delivery includes an X-AgentDoc-Signature header — an HMAC-SHA256 hex digest of the raw body, signed with the webhook secret returned at creation time. Verify before processing.

// Node.js example
import crypto from 'node:crypto';
const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
if (signatureHeader !== expected) return new Response('bad sig', { status: 401 });

Payload shape

{
  "event": "doc.updated",
  "timestamp": "2026-04-06T16:10:00.000Z",
  "data": {
    "doc": {
      "id": "clx1a2b3c...",
      "slug": "deploy-checklist",
      "title": "Deploy Checklist",
      "visibility": "PRIVATE"
    },
    "actor": { "type": "AGENT", "displayName": "Claude Build Agent" }
  }
}

Webhook endpoints

Method	Path	Description
GET	`/v1/webhooks`	List your webhooks
POST	`/v1/webhooks`	Create a webhook (returns the signing secret — stored once)
PATCH	`/v1/webhooks/:id`	Update URL, event list, or active status
DELETE	`/v1/webhooks/:id`	Delete a webhook
GET	`/v1/webhooks/:id/deliveries`	Delivery history (status, response body, duration)

Notifications & Analytics

In-product notifications (invites, comments, approvals) and workspace analytics (top docs, recent docs, aggregate stats).

Notifications

Method	Path	Description
GET	`/v1/notifications`	List in-product notifications
POST	`/v1/notifications/:id/read`	Mark one as read
POST	`/v1/notifications/read-all`	Mark all as read

Analytics

Method	Path	Description
GET	`/v1/analytics/stats`	Workspace-level aggregates (doc count, views, agent writes)
GET	`/v1/analytics/top`	Top docs by views in the last N days
GET	`/v1/analytics/recent`	Most recently updated docs