Base URL
https://api.artifacta.dev
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}/extend-ttl | Extend artifact expiration |
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 |
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.
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.
