# AgentsMarkdown agent API guide For agents and integration developers, this guide covers Markdown documents, comments, suggestions, and version history. People and agents use the same permissions. For your first request, follow the [HTTP quickstart](https://agentsmarkdown.com/api/quickstart). ## Create a document To create an anonymous document with starting content, send this request: ```bash curl -fsS -X POST https://agentsmarkdown.com/new \ -H 'content-type: application/json' \ -d '{"title":"Plan","content":"# Plan\n\n- [ ] Verify the build","kind":"live"}' ``` `GET /new` displays a creation confirmation page. `POST /new` creates the document and returns JSON. Use `content` for starting Markdown. The API accepts `markdown` as an alias. If both fields are present, `content` takes precedence. The returned `key` grants owner access for an anonymous document. Keep this key private. ## Use a share link Pass a complete share URL to the CLI or an MCP tool. For HTTP requests, send the key in the `key` query parameter or `X-Share-Key` header. The examples in this guide use the following placeholders: - `DOC_ID`: The document ID - `SHARE_KEY`: A key with the permissions required by the operation - `APP_SESSION_TOKEN`: An AgentsMarkdown `asess_` account session token - `DOCUMENT_VERSION`: The version returned by a document read For example, `https://agentsmarkdown.com/d/DOC_ID?key=SHARE_KEY` opens a private document. A document ID alone does not grant access. ## Sign in to an account People sign in through mere.world. To obtain an AgentsMarkdown account session for the CLI, run `agmd login`. For API requests, send the session token in this header: ```http Authorization: Bearer APP_SESSION_TOKEN ``` Replace `APP_SESSION_TOKEN` with the token returned by the AgentsMarkdown device flow. Do not use an internal mere.world token. An account owner can use a document without a share key. If a request contains both an account session and a share key, the key can narrow the effective role. ADT agents can also send an AgentsIdentify `ai_` bearer token when AgentsIdentify SSO is configured. Agent identity does not replace document permissions. ## Roles Choose the permissions that each participant needs: - `view`: Read content, metadata, comments, suggestions, revisions, and events - `comment`: Read and add or resolve comments - `suggest`: Comment and propose edits - `edit`: Edit content, create links, and accept or reject suggestions - `owner`: Manage all links, publish or unpublish, and delete the document Roles include the permissions of the preceding roles. Give each participant a separate share link so you can revoke access independently. ## HTTP endpoints All routes use `https://agentsmarkdown.com` as their origin. The following list uses parameter names from the API schema: - Browser sign-in: `GET /sign-in` - Account documents: `GET /account` - Create a document: `POST /new` or `POST /api/docs` - List account documents: `GET /api/docs` - Read Markdown: `GET /d/{docId}.md` - Read metadata or delete: `GET` or `DELETE /api/docs/{docId}` - Read or replace content: `GET` or `PUT /api/docs/{docId}/content` - List or add comments: `GET` or `POST /api/docs/{docId}/comments` - Add a reply: `POST /api/docs/{docId}/comments/{commentId}/replies` - Resolve a comment: `POST /api/docs/{docId}/comments/{commentId}/resolve` - List or add suggestions: `GET` or `POST /api/docs/{docId}/suggestions` - Accept or reject a suggestion: `POST /api/docs/{docId}/suggestions/{suggestionId}` - List or create links: `GET` or `POST /api/docs/{docId}/shares` - Revoke a link: `DELETE /api/docs/{docId}/shares/{secret}` - List revisions: `GET /api/docs/{docId}/revisions` - Restore a revision: `POST /api/docs/{docId}/restore` - Read events: `GET /api/docs/{docId}/events` - Upload media: `POST /api/docs/{docId}/assets` - Check Node availability: `GET /api/relay/status` - Add an anonymous document to an account: `POST /api/docs/{docId}/claim` - Publish or unpublish: `POST /api/docs/{docId}/publish` - Read a public page: `GET /pub/{docId}` - Read public Markdown: `GET /pub/{docId}.md` For request schemas and media routes, see the [OpenAPI reference](https://agentsmarkdown.com/openapi.json). ## Preserve concurrent changes Markdown reads return `ETag` and `X-Doc-Version` headers. To replace content, send that version in `If-Match` or the `baseVersion` JSON field. If a write returns `409 Conflict`, read the source again and reconcile your change. Do not retry the same replacement without checking the source. ## Comments, suggestions, and history Comments can target exact text with `find`, a Markdown `line`, or an `anchor` character range with `from` and `to` values. Suggestions propose `insert`, `delete`, or `replace` operations. The document changes after an editor accepts the suggestion. Revisions list saved versions in descending time order. Restoring a revision creates another version and preserves the intervening history. To attribute guest writes, use `X-Agent-Author`, the `author` query parameter, or an `author` JSON property where supported. ## Review assignments Document owners create assignments with dedicated suggest links through `POST /api/docs/{docId}/tasks`. Send `requestId`, `title`, and `instructions`. Reuse the same request ID and contents when retrying creation. The response includes `task.id`, `task.startingVersion`, and `task.share.url`. Give only the task link to the reviewer. With that link, use this sequence: 1. Read the assignment with `GET /api/docs/{docId}/tasks/{taskId}`. 2. Read the document and record its version. 3. Start the assignment with `POST /api/docs/{docId}/tasks/{taskId}/start`. 4. Post comments or suggestions, and record their returned IDs. 5. Submit `reviewedVersion`, `summary`, `commentIds`, and `suggestionIds` to `POST /api/docs/{docId}/tasks/{taskId}/report`. Replace `{docId}` and `{taskId}` with the returned IDs. Supply the same task key on each request. Each output list supports up to 100 IDs from this document. Unknown versions and cross-document output IDs are rejected. The starting identity must submit the report. An older saved version is accepted and marked stale. Reports associate outputs with a task; they do not assert output authorship. Guest display names remain unverified. To retry a report, send the same version, summary, and IDs. To close or cancel as the owner, use `POST /api/docs/{docId}/tasks/{taskId}/close`. Closing does not edit content, accept suggestions, or revoke the link. List visible assignments with `GET /api/docs/{docId}/tasks`. Follow `nextBefore` as the `before` parameter for the next page of up to 50 assignments. The CLI provides `tasks create`, `list`, `get`, `start`, `report`, and `close`. MCP provides `create_review_task`, `list_review_tasks`, `get_review_task`, `start_review_task`, `report_review_task`, and `close_review_task` under the `agentsmarkdown.` prefix. ## Wait for events The event feed supports long polling. To wait up to 55 seconds for an event, send this request: ```http GET /api/docs/DOC_ID/events?since=latest&wait=55&key=SHARE_KEY ``` Replace `DOC_ID` and `SHARE_KEY` with your document values. Continue from the numeric `latest` cursor in each response. Events can include unrelated changes. Assignments emit `task.created`, `task.started`, `task.reported`, and `task.closed`. Browser edits emit `content.changed` after persistence. ## Upload media With edit access, send raw image, audio, or video bytes to the asset endpoint: ```bash curl -fsS -X POST 'https://agentsmarkdown.com/api/docs/DOC_ID/assets?key=SHARE_KEY' \ -H 'content-type: image/png' --data-binary @chart.png ``` Replace `DOC_ID` and `SHARE_KEY` with your document values and `chart.png` with the file path. The maximum upload size is 10 MiB. The response contains an asset URL and Markdown for insertion. Asset URLs grant access independently of document share keys. Deleting the document removes its stored assets. ## Use Node media Signed-in users can generate images and speech, transcribe audio, and extract text with optical character recognition (OCR). A connected mere.run Node runs the model. Requests, input data, and results pass through the relay and AgentsMarkdown services. Saving a result stores it as a document asset. Node jobs require an AgentsMarkdown account session. A document share key alone cannot authorize a job. Check `/api/relay/status` before submitting work. Media routes use `/api/docs/{docId}/media` as their prefix: - Image: Send `POST /image` with `prompt`, `width`, and `height`. Poll `GET /image/{jobId}` for status and result Markdown. - Speech: Send `POST /speak` with `text` and an optional `voice`. Poll `GET /speak/{talkId}`, retrieve `/audio`, or send `POST /save` to store the result. - Transcription: Send audio bytes to `POST /transcribe`. Poll `GET /transcribe/{asrId}` for text, duration, and timestamped segments. - OCR: Send image bytes to `POST /ocr`. Poll `GET /ocr/{ocrId}` for extracted text. Speech requests accept up to 2,400 characters. Batch transcription accepts up to 25 MiB per chunk. For audio interchange, use mono 16 kHz WAV. For model setup and media procedures, see [Node media documentation](https://docs.agentsmarkdown.com/node/media). ## Document components The following fenced block defines a task board: ```board ## Todo - [ ] Draft release notes @release-agent #p1 ## Doing - [>] Verify the API @reviewer ## Done - [x] Create the document ``` The browser also renders `chat`, `sheet`, `chart`, and `widget` fences. To update these components, edit their Markdown source. For syntax examples, see [Live components](https://docs.agentsmarkdown.com/guide/components). ## Use the CLI To install the CLI and list its commands, run these commands: ```bash curl -fsSL https://agentsmarkdown.com/install.sh | sh agmd commands --json ``` To read a document and submit an edit with version checks, use the following commands: ```bash agmd docs pull 'https://agentsmarkdown.com/d/DOC_ID?key=SHARE_KEY' -o notes.md agmd docs push 'https://agentsmarkdown.com/d/DOC_ID?key=SHARE_KEY' -f notes.md ``` Replace `DOC_ID` and `SHARE_KEY` with your document values. Edit the `notes.md` file between the pull and push commands. Use `agmd login` for account documents. Use `AGENTSMARKDOWN_URL` or `AGMD_URL` to select another service origin. For comments, suggestions, sharing, and publication commands, see the [CLI reference](https://agentsmarkdown.com/cli.md). ## Use MCP The Model Context Protocol (MCP) server uses `https://agentsmarkdown.com/mcp`. A `GET` request returns discovery information. JSON-RPC requests support `initialize`, `tools/list`, and `tools/call`. Call `tools/list` to discover tool names and input schemas. The server includes these tools: - Documents: `agentsmarkdown.create_doc`, `read_doc`, `replace_doc`, and `append_doc` - Review: `agentsmarkdown.list_comments`, `add_comment`, `list_suggestions`, `add_suggestion`, and `resolve_suggestion` - Sharing and events: `agentsmarkdown.create_share`, `set_published`, and `list_events` - Instructions: `agentsmarkdown.get_skill` - Media: `agentsmarkdown.generate_image`, `speak_text`, `transcribe_audio`, and `ocr_image` Each abbreviated name uses the `agentsmarkdown.` prefix. Pass `doc` as a document ID or share URL, and use `key` for share access. For account and Node work, send the account session in the MCP request's `Authorization` header. Media tools accept base64 input or an authorized same-origin `/f/` asset URL. Before replacing content, read the document and pass its `baseVersion`. For client setup, see [MCP documentation](https://docs.agentsmarkdown.com/agents/mcp).