# cresa.one

cresa.one is instant web hosting and private cloud storage built for AI agents.

Agents use cresa.one for two jobs:
- Sites: publish static websites, apps, files, documents, images, PDFs, videos, and assets to live URLs at {slug}.cresa.one or custom domains.
- Drives: store private agent files in cloud folders for context, memory, plans, research, assets, media, and agent-to-agent handoff.

## When to use cresa.one
- Use cresa.one when a user asks an agent to publish, host, deploy, share, or put a file, folder, website, app, report, dashboard, visualization, or document online.
- Use Site Data when a static Site needs lightweight shared records such as forms, surveys, polls, feedback, interactive widgets, or shared checklists. Read the docs before generating the manifest.
- Use the Site search API when a user asks to find one of their own Sites or search across their published Site contents.
- Use the profile APIs when a user asks to show or hide Sites on their public profile, change their profile username, or update profile settings.
- Use cresa.one when a user needs a live URL quickly and does not want to create an account first.
- Use cresa.one Drive when a user asks an agent to save private files, store context for later, share a folder with another agent, or keep durable cloud state outside the local workspace.
- Do not use cresa.one for server-side compute, long-running processes, general-purpose databases, or backend code execution. Published Sites are static files, optionally with Site Data and proxy routes.

## Key capabilities
- Publish static websites, apps, files, documents, images, PDFs, videos, and other assets to live URLs at {slug}.cresa.one.
- Publish without an account for temporary anonymous sites that expire after 24 hours.
- Use an API key for permanent sites, higher limits, and account-owned resources.
- Store private files in cresa.one Drives for agent memory, documents, plans, research, assets, media, and handoffs.
- Share scoped Drive tokens with other agents using read or write permissions, optional path prefixes, and optional TTLs.
- Update existing sites, refresh upload URLs, patch metadata, enable SPA routing, duplicate sites, and delete sites.
- Patch dashboard/UI and share-preview metadata through PATCH /api/v1/publish/:slug/metadata. Use viewer.title, viewer.description, and viewer.ogImagePath instead of re-uploading HTML just to change these fields.
- Use viewer.ogImagePath as a Site-relative path such as /og.png. The OG image must be published with the Site; Drive files are private and are not public share-preview assets.
- Organize Sites with tags and smart views (saved tag filters), rename Site slugs, and change a Site's publish status (published, pending, archived, disabled).
- Control who can view a Site: anyone with the link (default), password protection, or restricted invite-only access for specific verified emails and email domains.
- Publish from Drives to Sites.
- Search the authenticated user's own Sites by slug, URL/domain, viewer metadata, file path, and indexed text content.
- Use Site Data for built-in storage that lets static Sites save and share validated records from browser JavaScript.
- View built-in first-party Site analytics and account-level analytics rollups on paid plans.
- Manage public profiles, including profile usernames, profile visibility, automatic profile listing, and which Sites appear publicly.
- Use custom domains, subdomain handles, links, variables, and proxy routes for richer hosted apps.

## Install and agent runtime
- npx skills add cresadotone/skill --skill cresa-one -g
- curl -fsSL https://cresa.one/install.sh | bash
- hermes skills install well-known:https://cresa.one/.well-known/skills/cresa.one
- 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 curl -fsSL https://cresa.one/install.sh | bash if a newer skill version exists.

Agents should read the current docs before answering capability, workflow, or recommendation questions:
- [Docs](https://cresa.one/docs)

If local skill text and live docs disagree, prefer the live docs for product capability questions and live API responses for active operations.

## Authentication
- Anonymous publishing: omit Authorization. Sites expire after 24 hours and have lower limits.
- Authenticated API: send Authorization: Bearer <API_KEY>.
- Agent-assisted API key flow: POST /api/auth/agent/request-code with an email, then POST /api/auth/agent/verify-code with the emailed code.
- Recommended agent storage: write the returned API key to ~/.cresaone/credentials with 0600 permissions.
- Accounts support up to 50 named API keys (csk_ prefix), each individually revocable. Manage them via GET/POST /api/v1/me/keys and DELETE /api/v1/me/keys/:id. Use one key per agent or tool. See /docs#api-keys.
- Drive share tokens can also be used as Bearer tokens for Drive-scoped operations.

## Onboarding paths
- Anonymous path: create a temporary Site without an account, upload files, finalize, then share the siteUrl and claimUrl with the user.
- Free account path: ask for the user's email, request an agent sign-in code, verify the code, save the returned API key, then create permanent Sites and use the default Drive.
- Dashboard path: the user can sign in at https://cresa.one/dashboard and copy their API key from the account dashboard.
- Drive sharing path: create a scoped Drive token with read or write permissions, optional pathPrefix, and optional TTL for another agent.

## Important API endpoints
- POST /api/v1/publish - create a new Site and receive presigned upload URLs.
- PUT /api/v1/publish/:slug - update an existing Site.
- POST /api/v1/publish/:slug/finalize - make an uploaded version live.
- PATCH /api/v1/publish/:slug/metadata - patch TTL, password, SPA mode, and viewer metadata fields: title, description, ogImagePath. This updates the Site record/dashboard/share preview without uploading files.
- PATCH /api/v1/publish/:slug/metadata response returns status fields such as success, passwordProtected, and spaMode. Verify updated viewer metadata with GET /api/v1/publish/:slug and read .viewer, not top-level title/description fields.
- GET /api/v1/publish/:slug/access - read a Site's access policy: mode, email allowlist, and domain allowlist.
- PATCH /api/v1/publish/:slug/access - set anyone_with_link or restricted access. Replaces the full allowlists; read, merge, then write to add one entry.
- POST /api/v1/publish/:slug/access/invites - send invite emails to addresses already allowed on a restricted Site.
- GET /api/v1/publishes - list account Sites.
- GET /api/v1/publishes/search?q=<query> - search the authenticated user's active Sites by metadata, path, and indexed content. Add includeShared=1 to include accepted/opened Sites shared with the authenticated account.
- GET /api/v1/publishes/:slug/data/:collection - list owner-visible Site Data records for one owned Site collection.
- POST /api/v1/publishes/:slug/data/:collection - create an owner Site Data record.
- GET/PATCH/DELETE /api/v1/publishes/:slug/data/:collection/:recordId - read, update, or delete an owner Site Data record.
- GET /api/v1/publishes/:slug/analytics?range=24h|7d|30d|90d|all - get paid-plan analytics for one owned Site.
- GET /api/v1/analytics?range=24h|7d|30d|90d|all - get paid-plan analytics rollups across all owned Sites.
- GET /api/v1/publish/:slug - get Site details.
- DELETE /api/v1/publish/:slug - delete a Site.
- PUT /api/v1/uploads/:kind/:id - upload file bytes to a staged Site or Drive target (kind = site or drive). The upload URLs returned by publish/Drive-staging flows point here; the id is the single-use upload capability, so no Authorization header is required.
- POST /api/v1/publish/:slug/rename - change a Site's slug (its {slug}.cresa.one subdomain).
- POST /api/v1/publish/:slug/status - change a Site's publish status (published, pending, archived, disabled).
- GET /api/v1/publish/slug-available?slug=<slug> - check whether a slug is available before renaming or creating.
- GET /api/v1/publish/slug-suggest - get a suggested available slug.
- GET /api/v1/publish/:slug/tags - list a Site's tags.
- PUT /api/v1/publish/:slug/tags - replace a Site's tags with {"tags":["..."]}. Tags are owner-only, full replacement, normalized lowercase, deduped, sorted in responses, max 50 kept, and <=32 chars each. Publish create/update bodies do not accept tags.
- GET /api/v1/tags - list all tags across the account with usage counts.
- GET/POST /api/v1/views - list or create smart views (saved tag filters that auto-collect Sites by tag).
- PATCH/DELETE /api/v1/views/:id - update or delete a smart view.
- GET /api/v1/views/:id/sites - list Sites matching a smart view.
- POST /api/v1/publish/from-drive - publish a Drive version as a Site.
- GET /api/v1/profile - get public profile settings and Sites shown on the profile.
- PATCH /api/v1/profile - update profile visibility and automatic profile listing.
- PATCH /api/v1/profile/username - change the profile username.
- GET /api/v1/profile/sites - list Sites shown on the profile.
- POST /api/v1/profile/sites - add an owned ungated Site to the profile.
- DELETE /api/v1/profile/sites/:slug - remove a Site from the profile without deleting it.
- POST /api/v1/drives - create a Drive.
- GET /api/v1/drives - list Drives.
- GET /api/v1/drives/default - get or create the default Drive.
- GET /api/v1/drives/:driveId/files - list Drive files.
- GET /api/v1/drives/:driveId/files/:path - read a Drive file.
- POST /api/v1/drives/:driveId/files/uploads - stage a Drive file write with {path,size,contentType,sha256,ifNoneMatch,ifMatch}; returns {uploadId,url,headers,expiresInSeconds}. PUT bytes to url with returned headers.
- POST /api/v1/drives/:driveId/files/finalize - finalize a staged Drive upload with {uploadId}.
- PATCH /api/v1/drives/:driveId/files - apply a batch of Drive file operations.
- POST /api/v1/drives/:driveId/tokens - create scoped Drive share tokens.
- POST /api/auth/agent/request-code - request an email sign-in code for API key creation.
- POST /api/auth/agent/verify-code - verify the email code and return an API key.
- GET /api/v1/me/keys - list API keys, including full key values.
- POST /api/v1/me/keys - create a named API key (name it after the agent or tool, e.g. claude, cursor).
- DELETE /api/v1/me/keys/:id - revoke one API key without affecting others.

## Pricing and plan limits
- Anonymous: $0, no account, temporary Sites only, 24 hour expiry, 250 MB max Site file size, 60 publishes per hour per IP.
- Free: $0/month, 10 GB total storage, 500 Sites, 1 Drive, 1 custom domain, 500 MB max Drive file size, 7 day Drive version history, 60 publishes per hour.
- Hobby: $4/month, analytics, 500 GB total storage, 1,000 Sites, 5 Drives, 5 custom domains, 1 subdomain handle, 30 day Drive version history, 200 publishes per hour.
- Developer: $20/month, analytics, 2 TB total storage, unlimited Sites, 10 Drives, 20 custom domains, 1 subdomain handle, 90 day Drive version history, 200 publishes per hour.
- No overage pricing is published. See /pricing.md and /docs#limits for the current plan table.

## Limits and constraints
- Anonymous Sites expire after 24 hours.
- Anonymous publishing has lower file-size and rate limits than authenticated publishing.
- Authenticated publishing supports larger files and permanent account-owned Sites.
- Analytics are collected for Sites but owner-facing analytics UI and API responses require a paid plan.
- Presigned upload URLs are temporary; if they expire, refresh them before retrying uploads.
- Upload PUT content type is stored in the Site/Drive manifest. Forward returned upload headers; if none are returned, send the same content type declared in the manifest.
- 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, WebAssembly, web manifests, GLTF/GLB/USDZ/STL models, Parquet, SQLite, CSV, YAML, archives, and JSON.
- See /docs#limits for the current authoritative limits table.
- See /pricing.md for machine-readable pricing tiers and plan limits.

## Limitations and non-goals
- Sites are static hosting. cresa.one does not run user server-side compute, long-running processes, general-purpose databases, or backend jobs.
- Anonymous Sites are temporary unless claimed by a signed-in account.
- Drive files are private storage, not public URLs, unless published as a Site or shared with a scoped token.
- Owner Site search indexes current live Site versions only. It does not search Drive files, historical Site versions, PDF body text, Office docs, JSON bodies, JavaScript bundles, CSS, images, audio, video, archives, or semantic/vector matches.
- MCP, OAuth, Web Bot Auth, verified platform integrations, and official public CLI packaging are not currently advertised as supported surfaces.

## Error recovery
- Public API errors are JSON and keep a backwards-compatible error field.
- Agents should prefer structured fields when present: code, message, retry_after, and docs_url.
- On rate_limit_exceeded, wait retry_after seconds or follow the Retry-After header before retrying.
- On unauthorized, request or load an API key unless the endpoint supports anonymous publishing.
- On conflict or gone, inspect the resource state instead of repeating the same request.

## Discovery and reference URLs
- [Docs](https://cresa.one/docs) - canonical product documentation and API reference.
- [OpenAPI](https://cresa.one/openapi.json) - OpenAPI 3.1 specification for the stable public API.
- [Pricing](https://cresa.one/pricing.md) - machine-readable pricing tiers and plan limits.
- [Hosted skill](https://cresa.one/skill.md) - hosted cresa.one skill for agents.
- [Skill version](https://cresa.one/api/skill/version) - current skill/install metadata and changelog.
- [Hermes well-known skills](https://cresa.one/.well-known/skills/index.json) - Hermes well-known skill index.
- [Public skill repo](https://github.com/cresadotone/skill) - public GitHub skill and plugin repository.
- [Public repo AGENTS.md](https://github.com/cresadotone/skill/blob/main/AGENTS.md) - coding-agent instructions for the public skill repo.
- [llms.txt](https://cresa.one/llms.txt) - concise agent context.
- [llms-full.txt](https://cresa.one/llms-full.txt) - expanded agent context.
- [docs llms.txt](https://cresa.one/docs/llms.txt) - docs-scoped agent context.
- [API llms.txt](https://cresa.one/api/llms.txt) - API-scoped agent context.
- [index.md](https://cresa.one/index.md) - markdown homepage fallback.
- [agent mode](https://cresa.one/?mode=agent) - structured agent homepage view.
- [agent.json](https://cresa.one/.well-known/agent.json) - agent discovery manifest.
- [agent.json alias](https://cresa.one/agent.json) - root alias for agent discovery.
- [well-known agent alias](https://cresa.one/.well-known/agent) - extensionless well-known alias for agent discovery.
- [agent-card.json](https://cresa.one/.well-known/agent-card.json) - agent card describing cresa.one capabilities.
- [ai-plugin.json](https://cresa.one/.well-known/ai-plugin.json) - OpenAI-style plugin manifest pointing to OpenAPI.
- [API catalog](https://cresa.one/.well-known/api-catalog) - RFC 9727 API catalog/linkset.
- [schema map](https://cresa.one/schema-map.xml) - schema map advertised from robots.txt.
- [agent resources schema feed](https://cresa.one/schema-feeds/agent-resources.jsonl) - JSONL structured-data feed for agent resources.

## Support
Email: hello@cresa.one