# cresa.one docs

Docs-scoped agent context. Canonical product documentation and API reference.

## Read this first
- Human docs: https://cresa.one/docs
- OpenAPI 3.1 spec (authoritative API contract): https://cresa.one/openapi.json
- Pricing + limits (machine-readable): https://cresa.one/pricing.md

## Anchors on the docs page
- https://cresa.one/docs#overview   - Sites vs Drives, what not to use cresa.one for
- https://cresa.one/docs#quickstart  - skill install + fallback installer
- https://cresa.one/docs#api-keys    - auth, Bearer keys, agent email code flow, key management
- https://cresa.one/docs#sites       - static publishes, access control, search
- https://cresa.one/docs#sitedata    - .cresaone/data.json manifest, validated record storage
- https://cresa.one/docs#drives      - private folders, scoped share tokens
- https://cresa.one/docs#flows       - Site publish flow + Drive write flow
- https://cresa.one/docs#api         - stable public endpoints
- https://cresa.one/docs#limits      - anonymous vs authenticated limits
- https://cresa.one/docs#pricing     - plan tiers
- https://cresa.one/docs#errors      - structured error recovery

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

## Core model
- Sites: static publishes at {slug}.cresa.one or a custom domain. Anonymous Sites expire after 24h; authenticated Sites are permanent. Common web media content types are preserved, including modern image, audio, video, font, WebAssembly, manifest, archive, structured-data, and 3D model formats.
- Site viewer metadata controls dashboard/UI title, description, and share-preview image. Update it with PATCH /api/v1/publish/:slug/metadata using viewer.title, viewer.description, and viewer.ogImagePath instead of re-uploading HTML just to change those fields. viewer.ogImagePath is Site-relative, such as /og.png; publish the image with the Site, not only to a private Drive.
- PATCH /api/v1/publish/:slug/metadata returns success/passwordProtected/spaMode. Verify persisted metadata with GET /api/v1/publish/:slug and inspect .viewer; viewer fields are not top-level title/description fields.
- Tags are replaced with PUT /api/v1/publish/:slug/tags and {"tags":["..."]}; they are owner-only, full replacement, normalized lowercase, deduped, sorted in responses, max 50 kept, max 32 chars each.
- Drives: private cloud folders for agent memory, context, and handoff. Share scoped read/write tokens with optional pathPrefix and TTL. Drive upload staging accepts {path,size,contentType,sha256,ifNoneMatch|ifMatch}; PUT bytes to the returned url with returned headers, then finalize with {uploadId}.

## Auth
- Anonymous: omit Authorization (24h Sites, lower limits).
- Authenticated: Authorization: Bearer <API_KEY>.
- Get a key: POST /api/auth/agent/request-code (email) then POST /api/auth/agent/verify-code (code).
- Up to 50 named keys (csk_ prefix), each revocable. Manage via /api/v1/me/keys.

## Safety
- Never commit ~/.cresaone/credentials, API keys, or Drive tokens.
- Drive files are private; do not describe them as public URLs.
- Do not use Drive-only file paths for public share-preview images.
- Trust live API responses over docs/skill text when they disagree.

## More agent context
- https://cresa.one/llms.txt       - concise agent context
- https://cresa.one/llms-full.txt  - expanded agent context
- https://cresa.one/.well-known/agent.json - agent discovery manifest

## Support
hello@cresa.one