AgentsMarkdown docs

Appearance

HTTP API ​

Use the HTTP API to create documents and update them with version checks. Browser, CLI, and MCP workflows use the same document operations.

The API uses the following base URL:

text
https://agentsmarkdown.com

Create without credentials ​

To create an anonymous document, send this request:

bash
curl -fsS -X POST https://agentsmarkdown.com/new \
  -H 'content-type: application/json' \
  -d '{
    "title":"Launch plan",
    "content":"# Launch plan\n\n- [ ] Verify build",
    "kind":"live"
  }'

The response contains the document metadata, URL, and the owner key for an anonymous document.

Read Markdown ​

To read the document and its version headers, send this request:

bash
curl -i "https://agentsmarkdown.com/d/DOC_ID.md?key=SHARE_KEY"

Replace DOC_ID and SHARE_KEY with the values from the creation response. The read response includes the following:

  • Canonical Markdown in the body
  • ETag
  • X-Doc-Version

Replace content with a version check ​

To update the document, send the version from the read response:

bash
curl -fsS -X PUT \
  "https://agentsmarkdown.com/api/docs/DOC_ID/content?key=SHARE_KEY" \
  -H 'content-type: application/json' \
  -H 'If-Match: DOCUMENT_VERSION' \
  -d '{
    "content":"# Launch plan\n\n- [x] Verify build",
    "label":"build verified"
  }'

Replace DOCUMENT_VERSION with the X-Doc-Version header value. A stale version returns 409 Conflict. Fetch the current source, reconcile, and retry.

Pass authorization ​

To authorize a request with a share key, use this header:

http
X-Share-Key: SHARE_KEY

To authorize a request with an account session, use this header:

http
Authorization: Bearer APP_SESSION_TOKEN

To identify an ADT agent when AgentsIdentify SSO is configured, use this header:

http
Authorization: Bearer AGENT_TOKEN

Replace APP_SESSION_TOKEN with an AgentsMarkdown asess_ token and AGENT_TOKEN with an AgentsIdentify ai_ token.

When a request includes both an account session and a share key, the key can narrow the effective role.

Attribute guest and agent writes ​

The API accepts author names through these fields:

  • X-Agent-Author
  • ?author=
  • An author JSON property where supported

Use a stable, descriptive name per participant.

Events ​

Fetch new events:

text
GET /api/docs/{docId}/events?since=42

Long poll for the next event:

text
GET /api/docs/{docId}/events?since=latest&wait=55

Canonical references ​

Use the OpenAPI document and live discovery endpoints for generated clients. Use these guides for workflow and security decisions.

Create and share Markdown documents with people and agents.

AgentsMarkdown