Base URL
All endpoints (except GET /health) are prefixed with /v1/.
Authentication
Every request requires a Bearer token:
Authorization: Bearer ak_live_<key>
GET /v1/whoami to verify your key.
Endpoints
Artifacts
| Method | Endpoint | Description |
|---|
POST | /v1/artifacts | Upload an artifact |
GET | /v1/artifacts | List artifacts with filters |
GET | /v1/artifacts/{id} | Get artifact metadata |
GET | /v1/artifacts/{id}/download-url | Get presigned download URL |
DELETE | /v1/artifacts/{id} | Soft-delete an artifact |
POST | /v1/artifacts/{id}/links | Create a download link |
Presigned uploads
| Method | Endpoint | Description |
|---|
POST | /v1/artifacts/upload-url | Get presigned upload URL (large files) |
POST | /v1/artifacts/{id}/complete | Finalize presigned upload |
Artifact Pages (authenticated)
| Method | Endpoint | Description |
|---|
POST | /v1/artifacts/{id}/publish | Publish an artifact as a public page |
DELETE | /v1/artifacts/{id}/publish | Unpublish a page (accepts artifact ID or page slug) |
Artifact Pages (public — no auth)
| Method | Endpoint | Description |
|---|
GET | /v1/public/pages/{slug}/gate-info | Check if a page is password-protected |
POST | /v1/public/pages/{slug}/unlock | Verify passcode, receive a content token |
POST | /v1/public/pages/{slug}/report | Submit an abuse report (always 202) |
The three /v1/public/pages/ endpoints require no Bearer token. They are called by the public viewer and by end users’ browsers. The “Every request requires a Bearer token” rule applies only to authenticated endpoints.
Sessions
| Method | Endpoint | Description |
|---|
POST | /v1/sessions/{id}/seal | Seal a session |
Account
| Method | Endpoint | Description |
|---|
GET | /v1/whoami | Verify auth, get tenant info |
GET | /health | Health check (no auth) |
Content upload paths
| Method | Best for | Size limit |
|---|
Multipart form data (POST /v1/artifacts) | CLI, file uploads | 500 MB |
JSON body with base64 (POST /v1/artifacts) | Programmatic callers, small content | 10 MB decoded |
Presigned URL (upload-url → PUT → complete) | Large files | 5 GB |
- Response includes
next_cursor (null if no more results)
- Pass
cursor=<value> for the next page
- Max
limit: 200, default: 50
Sort order guarantee: Results are always ordered by created_at DESC, artifact_id DESC. This is a V1 API contract and will not change without a new API version.
Rate limiting
Per-tenant: 100 requests/second sustained, 200 requests/second burst (sliding window).
Headers on every response:
| Header | Description |
|---|
X-RateLimit-Limit | Requests per second allowed |
X-RateLimit-Remaining | Remaining in current window |
X-RateLimit-Reset | Unix timestamp when window resets |
429 Too Many Requests with Retry-After header and retry_after_seconds in the body.
Error response shape
All errors return:
{
"error": {
"code": "artifact_not_found",
"message": "Artifact art_xxx was not found.",
"status": 404
}
}
error.code (stable). Never parse error.message. See the full error reference.
The page field on artifact responses
GET /v1/artifacts/{id} includes a page sub-object when the artifact has a live published page:
{
"artifact_id": "art_abc123",
"filename": "report.pdf",
"page": {
"public_url": "https://artifacta.io/a/pg_aB3xK9mP1qR5sT2u",
"visibility": "unlisted"
}
}
| Field | Type | Description |
|---|
page.public_url | string | Full viewer URL. Anyone with this URL can view the artifact. |
page.visibility | string | "unlisted" or "public". |
page is null when no live page exists (never published, or unpublished). It is present only on the single-artifact GET /v1/artifacts/{id} response — list results always return page: null.
API guarantees
- Read-after-write consistency: An artifact written via
POST /v1/artifacts is immediately visible to all read endpoints.
- Backward compatibility: Additive changes (new fields, new optional parameters, new endpoints) are non-breaking. Removals and type changes require a new API version. V1 remains available for 12 months after V2 launches.
Coming in V1.1: POST /v1/artifacts/batch/download-urls — batch download URLs for up to 20 artifacts in a single request.
