# Slant — API Reference

> Complete API reference for the Slant **bridge** (single-document, share-token access). For a product overview, see https://slant.page/llms.txt
> For an installable agent skill with bash helpers, see https://slant.page/SKILL.md
> **For workspace-wide access, prefer the Slant MCP server:** https://slant.page/api/mcp (bearer token from Settings → AI agents). This bridge is the one-off, no-install alternative.

## Authentication

All requests require a share token. Send it as:
- `Authorization: Bearer <token>` header (preferred)
- `x-share-token: <token>` header
- `?token=<token>` query parameter

## Getting Started

1. Register your presence (required before other actions):
   POST /api/bridge/<docId>/presence
   Body: { "name": "Your Name", "type": "agent", "status": "active" }

2. Read the document:
   GET /api/bridge/<docId>/state
   Returns: { id, title, mode, hasVoice, hasKnowledgeBase, nodes[], comments[], suggestions[] }

3. Interact based on your permission level:
   - POST /api/bridge/<docId>/comments — leave a comment (requires: comment)
   - POST /api/bridge/<docId>/suggestions — suggest an edit (requires: suggest)
   - POST /api/bridge/<docId>/edit — directly replace text (requires: edit)
   - POST /api/bridge/<docId>/set — replace the whole body from markdown (requires: edit)
   - POST /api/bridge/<docId>/delete — delete a node (requires: edit)
   - GET /api/bridge/<docId>/style — get style guide (requires: view)
   - POST /api/bridge/<docId>/knowledge — query knowledge base (requires: view)

## Endpoints

### GET /api/bridge/<docId>/state
Returns document content, title, mode, active comments and suggestions.
- Accept: application/json → node list with IDs (default)
- Accept: text/markdown → raw markdown

Response (JSON):
{
  id: string,
  title: string,
  mode: "manual" | "chat",
  hasVoice: boolean,
  hasKnowledgeBase: boolean,
  nodes: [{ id: string, type: string, text: string, level?: number }],
  comments: [{ id, nodeId, originalText, content, aiName, createdAt }],
  suggestions: [{ id, nodeId, originalText, proposedText, status, aiName, createdAt }]
}

The `mode` field indicates how the document was created:
- "manual": Direct editing mode. All content is author-written.
- "chat": AI-assisted mode. The document went through an interview and drafting process. The nodes returned are the working draft content. AI-generated drafts are stored separately and are not included in the node list.

### GET /api/bridge/<docId>/comments
Returns all comments.
Response: [{ id, nodeId, originalText, content, aiName, createdAt }]

### POST /api/bridge/<docId>/comments
Leave a comment anchored to text.
Body: { "nodeId": "<from state>", "originalText": "exact text", "comment": "your comment" }
Requires: comment permission.

### POST /api/bridge/<docId>/suggestions
Suggest a text replacement.
Body: { "nodeId": "<from state>", "originalText": "exact text", "proposedText": "replacement" }
Requires: suggest permission.

### PATCH /api/bridge/<docId>/suggestions/<id>
Accept or reject a suggestion.
Body: { "status": "accepted" | "rejected" }
Requires: suggest (own) or edit (any).

### POST /api/bridge/<docId>/edit
Directly replace text in the document.
Body: { "nodeId": "<from state>", "originalText": "exact text", "replacementText": "new text" }
Requires: edit permission.

To insert a new paragraph after an existing node:
Body: { "afterNodeId": "<from state>", "newParagraph": "text for new paragraph" }
Requires: edit permission.

### POST /api/agent/documents  (no auth — ownerless create)
Create a document WITHOUT an account, for a human who may not have one yet. Heavily rate-limited.
Body: { "markdown": "# Title\n\n...", "title": "optional" }
Returns: { documentId, url, claimUrl, token, expiresAt }
- url — the tokenized editor link (you can keep editing via the bridge with the token).
- claimUrl — hand this to the human; they sign in and claim the doc into their workspace.
- The doc is unclaimed and is deleted after ~7 days if nobody claims it.

### POST /api/bridge/<docId>/set
Replace the ENTIRE document body from markdown. Overwrites everything — use /edit for a targeted change.
Body: { "markdown": "# New content\n\n..." }
Requires: edit permission.
Returns: { success: true }

### POST /api/bridge/<docId>/delete
Delete a single block-level node from the document.
Body: { "nodeId": "<from state>" }
Requires: edit permission.
Returns: { success: true }

Deletes exactly one top-level node by ID. Headings and paragraphs are siblings in the document structure — deleting a heading does not remove the paragraphs that follow it.

### GET /api/bridge/<docId>/style
Returns the active style guide.
Response: { name: string | null, fingerprint: string | null }
Returns { name: null, fingerprint: null } if none linked.

### POST /api/bridge/<docId>/knowledge
Query attached knowledge bases via RAG.
Body: { "query": "your search query" }
Returns: { results: [{ text, sourceId, knowledgeBaseId, score }] }
Returns empty results if no knowledge base linked.

### POST /api/bridge/<docId>/presence
Register and set your status. First call sets your identity (name is immutable after that).
Body (first): { "name": "Your Name", "type": "agent", "status": "active" }
Body (status update): { "status": "thinking" }
Body (heartbeat): {} (empty — all bridge API calls also auto-refresh your presence)

Valid status values:
- "active" — default, you're working
- "thinking" — processing / reasoning
- "reading" — reading the document or context
- "writing" — generating or applying edits
- "waiting" — waiting for user input or approval
- "completed" — finished your task
- "error" — something went wrong

Your presence is visible to all users in real-time. Set meaningful statuses as you work
so collaborators can see what you're doing. After 3 minutes of inactivity you appear
dimmed; after 60 minutes you're removed.

## Permission Levels

Tokens are scoped to one level. Each level includes everything below it:
- view: read state, comments, style, knowledge, presence
- comment: + leave comments
- suggest: + suggest edits, accept/reject own suggestions
- edit: + direct edits, delete nodes, accept/reject any suggestion

## Error Codes

| Status | Error | Meaning |
|--------|-------|---------|
| 401 | Invalid or revoked token | Token not found or has been revoked |
| 403 | Token does not match document | Token was issued for a different document |
| 403 | Requires <level> permission | Token permission level is insufficient |
| 404 | Node not found | The specified nodeId does not exist in the document |
| 404 | Could not find the specified text | The originalText does not match any text in the node |
| 410 | document_not_found | The document has been deleted. Stop working and inform the user. |

## Tips

- Read /state first to get node IDs — you need them for comments, suggestions, edits, and deletes.
- The "originalText" must exactly match text within the node. Partial matches fail.
- Register presence early with a meaningful name. Your status is visible to all collaborators in real-time.
- Your presence name is permanent — choose it carefully on first POST /presence.
- If you receive a 410 (document_not_found), the document has been deleted. Stop all operations and inform the user.