HTTP API
The public /api/v1 endpoints the CLI and agents call directly.
The CLI uses the same public /api/v1 API that agents can call directly. Exact request and response schemas are available in the generated reference at /api/docs.
| Endpoint | Purpose |
|---|---|
POST /api/v1/publish | Create a publish session and receive upload URLs. |
POST /api/v1/publish/{publishSessionId}/finalize | Activate the uploaded version. |
GET /api/v1/artifacts/{artifactId} | Read public artifact state. |
PATCH /api/v1/artifacts/{artifactId} | Update the title or slug (owner). |
DELETE /api/v1/artifacts/{artifactId} | Delete an artifact and all its data (owner). |
GET /api/v1/artifacts/{artifactId}/versions | List finalized versions and file changes. |
GET /api/v1/artifacts/{artifactId}/stats | Read daily view stats: totals, unique visitors, time on page (owner). |
PUT /api/v1/artifacts/{artifactId}/protection | Set or clear the artifact's password gate. |
POST /api/v1/artifacts/{artifactId}/unlock | Unlock a password-protected artifact with the shared password. |
PUT /api/v1/artifacts/{artifactId}/review-mode | Set the artifact's review mode: open, readonly, or off. |
POST /api/v1/artifacts/{artifactId}/report | Report an artifact for abuse. |
GET /api/v1/artifacts/{artifactId}/comments | List comment threads with full messages. |
GET /api/v1/artifacts/{artifactId}/comments/export | Export comments for agents and the CLI. |
POST /api/v1/artifacts/{artifactId}/comments | Open a thread as an account or guest (a bare publish token is rejected). |
POST /api/v1/comment-threads/{threadId}/messages | Reply to a thread. |
PATCH /api/v1/comment-messages/{messageId} | Edit a message you authored. |
DELETE /api/v1/comment-messages/{messageId} | Soft-delete a message you authored (tombstone). |
POST /api/v1/comment-threads/{threadId}/resolve | Resolve a thread (records who resolved). |
POST /api/v1/comment-threads/{threadId}/reopen | Reopen a thread. |
POST /api/v1/comment-threads/{threadId}/acknowledge | Mark an open thread "seen, working on it" (token or member only). |
DELETE /api/v1/comment-threads/{threadId} | Delete a thread (owner). |
POST /api/v1/claim/{token} | Claim an anonymous artifact after sign-in. |
Errors return a structured body. See the error reference.