Agent Contract: Direct Markdown Sharing

Agent Contract: Direct Markdown Sharing

This contract defines the public Proof SDK flow for creating and operating on shared documents over HTTP.

Endpoints

Canonical route:

`POST /documents`

Compatibility alias:

`POST /share/markdown`

Legacy internal route:

`POST /api/documents`

Request Formats

JSON

POST /documents HTTP/1.1
Content-Type: application/json
Authorization: Bearer    # when API-key auth is enabled

{
  "markdown": "# Plan\n\nShip the rewrite.",
  "title": "Rewrite Plan",
  "role": "commenter",
  "ownerId": "agent:claude"
}

Raw markdown

POST /documents?title=Rewrite%20Plan&role=commenter HTTP/1.1
Content-Type: text/markdown
Authorization: Bearer    # when API-key auth is enabled

# Plan

Ship the rewrite.

Response

{
  "success": true,
  "slug": "abc123xy",
  "docId": "b9d9f8e8-5a4e-4af8-a9d4-5e0ecf7ff4ab",
  "url": "/d/abc123xy",
  "shareUrl": "https://your-proof.example/d/abc123xy",
  "tokenPath": "/d/abc123xy?token=...",
  "tokenUrl": "https://your-proof.example/d/abc123xy?token=...",
  "ownerSecret": "8b5f...owner secret...",
  "accessToken": "4d53...link token...",
  "accessRole": "commenter",
  "active": true,
  "shareState": "ACTIVE",
  "snapshotUrl": "https://your-proof.example/snapshots/abc123xy.html",
  "createdAt": "2026-02-12T16:10:00.000Z",
  "_links": {
    "view": "/d/abc123xy",
    "state": "/documents/abc123xy/state",
    "ops": { "method": "POST", "href": "/documents/abc123xy/ops" },
    "events": "/documents/abc123xy/events/pending?after=0",
    "docs": "/agent-docs"
  }
}

Token Semantics

undefined

Authentication Model

`PROOF_SHARE_MARKDOWN_AUTH_MODE` controls direct-share auth:

undefined

`/api/documents` is governed separately by `PROOF_LEGACY_CREATE_MODE`:

undefined

Minimal Agent Flow

undefined

Read + Operate Contract

Read state

undefined

Mutation endpoint

Use `POST /documents/:slug/ops` with:

undefined