# cresa.one API

API-scoped agent context. The authoritative contract is the OpenAPI 3.1 spec.

## Authoritative references
- OpenAPI 3.1 spec: https://cresa.one/openapi.json
- Human API docs: https://cresa.one/docs#api
- Product context: https://cresa.one/llms.txt
- Pricing + limits (machine-readable): https://cresa.one/pricing.md

## Base URL
- https://cresa.one

## Skill updates
- Fallback installer: curl -fsSL https://cresa.one/install.sh | bash.
- Fallback installer installs /cresa-one at ~/.claude/commands/cresa-one.md.
- /cresa-one checks /api/skill/version and automatically runs the hosted installer if a newer skill version exists.

## Auth
- Anonymous: omit Authorization (temporary 24h Sites, lower limits).
- Authenticated: Authorization: Bearer <API_KEY> (csk_ prefix).
- Get a key: POST /api/auth/agent/request-code (email) then POST /api/auth/agent/verify-code (code).
- Manage keys: GET/POST /api/v1/me/keys, PATCH/DELETE /api/v1/me/keys/{id},
  GET /api/v1/me/keys/{id}/reveal, POST /api/v1/me/keys/{id}/roll.
- Drive share tokens are also Bearer tokens, scoped to a Drive + optional pathPrefix.

## Endpoint groups
- Auth: POST /api/auth/agent/request-code, POST /api/auth/agent/verify-code.
- Sites (publish): POST /api/v1/publish, PUT /api/v1/publish/{slug},
  POST /api/v1/publish/{slug}/finalize, PATCH /api/v1/publish/{slug}/metadata,
  GET /api/v1/publish/{slug}, DELETE /api/v1/publish/{slug},
  POST /api/v1/publish/{slug}/rename, POST /api/v1/publish/{slug}/status
  (published|pending|archived|disabled), POST /api/v1/publish/from-drive,
  GET /api/v1/publishes, GET /api/v1/publishes/search?q=.
- Uploads: PUT /api/v1/uploads/{kind}/{id} (kind = site|drive). The upload URLs
  returned by the publish and Drive-staging flows point here; {id} is the
  single-use upload capability, so no Authorization header is required. Forward
  returned upload headers, especially Content-Type; this value is stored in the
  Site manifest or Drive file record.
- Tags & smart views: GET/PUT /api/v1/publish/{slug}/tags, GET /api/v1/tags,
  GET/POST /api/v1/views, PATCH/DELETE /api/v1/views/{id},
  GET /api/v1/views/{id}/sites.
- Slugs: GET /api/v1/publish/slug-available?slug=, GET /api/v1/publish/slug-suggest.
- Access control: GET/PATCH /api/v1/publish/{slug}/access,
  POST /api/v1/publish/{slug}/access/invites, POST /api/v1/publish/{slug}/claim.
- Site Data: GET/POST /api/v1/publishes/{slug}/data/{collection},
  GET/PATCH/DELETE /api/v1/publishes/{slug}/data/{collection}/{recordId}.
- Analytics (paid): GET /api/v1/publishes/{slug}/analytics?range=,
  GET /api/v1/analytics?range= (24h|7d|30d|90d|all).
- Drives: GET/POST /api/v1/drives, GET /api/v1/drives/default,
  GET/PATCH/DELETE /api/v1/drives/{driveId}, GET/PATCH /api/v1/drives/{driveId}/files,
  GET/DELETE /api/v1/drives/{driveId}/files/{path...},
  POST /api/v1/drives/{driveId}/files/uploads,
  POST /api/v1/drives/{driveId}/files/finalize,
  POST /api/v1/drives/{driveId}/files/move,
  GET/POST /api/v1/drives/{driveId}/tokens.
- Profiles: GET/PATCH /api/v1/profile, PATCH /api/v1/profile/username,
  GET/POST /api/v1/profile/sites, DELETE /api/v1/profile/sites/{slug}.
- Account: GET/POST /api/v1/me/keys (+ key id ops above),
  GET /api/v1/me/variables, PUT/DELETE /api/v1/me/variables/{name}.
- Domains & handles: GET/POST /api/v1/domains, GET/DELETE /api/v1/domains/{domain},
  GET/POST/PATCH/DELETE /api/v1/handle, GET/POST /api/v1/links,
  GET/PATCH/DELETE /api/v1/links/{location}.
- Support: POST /api/v1/support.

## Publish flow
1. POST /api/v1/publish with a file manifest → returns upload URLs.
2. PUT each file's bytes to its upload URL (/api/v1/uploads/{kind}/{id}).
3. POST /api/v1/publish/{slug}/finalize to make the version live.
4. Share the returned siteUrl (and claimUrl for anonymous Sites).

If using the skill helper and files changed, prefer one call that uploads files,
finalizes, patches viewer metadata, and replaces tags:
./scripts/publish.sh ./site --slug slug --title "Title" --description "..." --og-image-path /og.png --tags '["tag"]'.
Use --metadata-only only when files did not change.

## Site metadata
- PATCH /api/v1/publish/{slug}/metadata updates owner-only Site fields without uploading files.
- Use viewer.title, viewer.description, and viewer.ogImagePath for dashboard/UI labels and share previews.
- viewer.ogImagePath is Site-relative, for example /og.png. Publish og.png with the Site; Drive-only files are private and are not public OG image URLs.
- PATCH returns a compact status object such as {"success":true,"passwordProtected":true,"spaMode":false}. Verify persisted values with GET /api/v1/publish/{slug} and inspect .viewer, .tags, and .manifest.
- Do not re-upload or rewrite HTML just to change these Site metadata fields.
- Use PUT /api/v1/publish/{slug}/tags with {"tags":["..."]} for tags; tags are not accepted in publish create/update bodies. Tags are owner-only, full replacement, normalized lowercase, deduped, sorted in responses, max 50 kept, max 32 chars each.

## Drive writes
- Stage with POST /api/v1/drives/{driveId}/files/uploads and body {path,size,contentType,sha256,ifNoneMatch|ifMatch}.
- Use ifNoneMatch:"*" for create-only writes or ifMatch:"{etag}" for conditional replacement.
- PUT bytes to the returned url with returned headers, then finalize with POST /api/v1/drives/{driveId}/files/finalize and {uploadId}.

## Content types
- Helpers map common web MIME types including AVIF/WebP/HEIC/TIFF images, MP4/MOV/WebM video, FLAC/AIFF/ALAC/M4A/AAC/WAV/MP3/OGG/Opus/MIDI audio, WOFF/TTF/OTF fonts, WASM, web manifests, archives, JSONL/maps, parquet, SQLite, glTF/GLB/USDZ/STL, and common text/data files.

## Error recovery
- Errors are JSON with a backwards-compatible "error" field; prefer structured
  fields when present: code, message, retry_after, docs_url.
- On rate_limit_exceeded, wait retry_after seconds (or the Retry-After header).
- On unauthorized, load/request an API key unless the endpoint allows anonymous use.
- Trust live API responses over docs when they disagree.

## Support
hello@cresa.one