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/agent-tokens | Mint an expiring workspace-scoped agent token with an account key. |
DELETE /api/v1/agent-tokens/current | Revoke the bearer agent token (idempotent 204). |
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). |
GET /api/v1/artifacts/{artifactId}/data | List shared-data collections and counts (owner). |
GET /api/v1/artifacts/{artifactId}/data/{collection} | List records in a collection (owner). |
POST /api/v1/artifacts/{artifactId}/data/{collection} | Insert a record, or an array of up to 100 all-or-nothing, regardless of the collection's insert policy (owner). |
DELETE /api/v1/artifacts/{artifactId}/data/{collection} | Clear every record in a collection (owner). |
GET /api/v1/artifacts/{artifactId}/data/{collection}/{recordId} | Read one record (owner). |
PATCH /api/v1/artifacts/{artifactId}/data/{collection}/{recordId} | Update one record (owner). |
DELETE /api/v1/artifacts/{artifactId}/data/{collection}/{recordId} | Delete one record (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. |
PUT /api/v1/artifacts/{artifactId}/expiration | Set a temporary lifetime with {expiresInSeconds}, or clear it with null (publish token, scoped agent token, or manager). |
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. |
Artifact pages themselves call /__ac/data/* on their own content origin; see Artifact Data for the manifest, client, and access rules.
Errors return a structured body. See the error reference.