cresa.one docs

Overview#

cresa.one gives an agent two primitives. Use Sites for public hosting and Drives for private agent storage.

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.

Quickstart#

Install the cresa.one skill so your agent can publish and store files:

npx skills add cresadotone/skill --skill cresa-one -g

Fallback installer:

curl -fsSL https://cresa.one/install.sh | bash

The fallback installer also installs /cresa-one at ~/.claude/commands/cresa-one.md. Typing /cresa-one checks the live skill version and automatically runs the hosted installer when a newer version exists.

No account is needed for temporary anonymous Sites — they expire after 24 hours. Add an API key for permanent Sites, higher limits, and account-owned resources.

Authentication & API keys#

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

Sites#

Sites are static file publishes served at {slug}.cresa.one or a configured custom domain. They can contain HTML, CSS, JS, images, PDFs, video, audio, and documents. If a Site has no index.html, cresa.one renders an automatic file viewer or directory listing.

Uploads preserve explicit content types. Common mapped formats include 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, archives, CSV, YAML, and JSON.

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. You can update Sites, refresh upload URLs, patch metadata, enable SPA routing, duplicate, publish from a Drive, and delete.

Search your own active Sites by slug, URL/domain, viewer metadata, file path, and indexed text content via GET /api/v1/publishes/search?q=<query>.

Dashboard/UI title, description, and share-preview image are Site viewer metadata. Update them with PATCH /api/v1/publish/:slug/metadata, for example {"viewer":{"title":"...","description":"...","ogImagePath":"/og.png"}}. Do not re-upload or rewrite HTML just to change these fields. The ogImagePath value is Site-relative, so /og.png must be included in the published Site files; Drive files are private and are not public share-preview assets.

Site Data#

Site Data gives static pages built-in validated record storage — for forms, surveys, polls, feedback, interactive widgets, and shared checklists. Enable it by publishing a .cresaone/data.json manifest with your Site. Browser JavaScript can then save and read validated records.

Owner-facing record APIs live under /api/v1/publishes/:slug/data/:collection (list, create, read, update, delete). Site Data is included for account-owned Sites on the Free plan and every paid plan; it is not available for anonymous Sites.

Drives#

Drives are private cloud folders for agents — documents, context, memory, plans, assets, media, research, code, and cross-agent handoff. Every signed-in account has a default Drive named My Drive.

Drive tokens share scoped access with another agent. Tokens can be read or write, restricted by pathPrefix, and given an optional TTL. Use narrow scopes and short TTLs for handoff. Drive files are private — never describe them as public URLs.

Publish & write flows#

Site publishing

1. Create a Site with POST /api/v1/publish and a manifest of files.
2. Upload every file to the returned presigned upload URLs.
3. Finalize the version with POST /api/v1/publish/:slug/finalize.
4. Share the returned siteUrl with the user.

For anonymous Sites, preserve the claimUrl from the create response and share it — claim tokens are only returned once.

After publish/finalize, use PATCH /api/v1/publish/:slug/metadata for owner-only metadata changes such as viewer title, viewer description, Open Graph image path, TTL, password, and SPA mode. Use PUT /api/v1/publish/:slug/tags for tags; tags are not accepted in the publish body.

To verify metadata, read GET /api/v1/publish/:slug and inspect .viewer, .tags, and .manifest. Viewer title, description, and ogImagePath are not top-level response fields.

Drive write

1. Stage an upload with POST /api/v1/drives/:driveId/files/uploads.
2. Upload the bytes to the returned presigned URL and forward returned upload headers.
3. Finalize with POST /api/v1/drives/:driveId/files/finalize.
4. Use ifNoneMatch: "*" for create-only writes, ifMatch with an ETag for replacements, and preserve ETags for future conditional writes.

API endpoints#

Stable public routes below. The authoritative, machine-readable contract is the OpenAPI 3.1 spec.

Sites

• POST/api/v1/publishCreate a Site, receive presigned upload URLs.
• PUT/api/v1/publish/:slugUpdate an existing Site.
• POST/api/v1/publish/:slug/finalizeMake an uploaded version live.
• PATCH/api/v1/publish/:slug/metadataPatch TTL, password, SPA mode, and viewer title/description/ogImagePath without uploading files.
• GET / PATCH/api/v1/publish/:slug/accessRead or set access policy & allowlists.
• POST/api/v1/publish/:slug/access/invitesEmail invites to allowed addresses.
• POST/api/v1/publish/from-drivePublish a Drive version as a Site.
• GET/api/v1/publishesList account Sites.
• GET/api/v1/publishes/search?q=Search active Sites (add includeShared=1).
• GET/api/v1/publish/:slugGet Site details.
• DELETE/api/v1/publish/:slugDelete a Site.
• POST/api/v1/publish/:slug/renameChange a Site's slug (subdomain).
• POST/api/v1/publish/:slug/statusChange publish status (published / pending / archived / disabled).
• GET/api/v1/publish/slug-available?slug=Check slug availability.
• GET/api/v1/publish/slug-suggestSuggest an available slug.
• PUT/api/v1/uploads/:kind/:idUpload bytes to a staged Site/Drive target (kind = site|drive).

Viewer metadata drives dashboard/UI labels and share previews. Use the metadata endpoint for title, description, and ogImagePath; HTML meta tags alone do not update the account Site record. The metadata PATCH response returns status fields such as success, passwordProtected, and spaMode. Read GET /api/v1/publish/:slug and inspect .viewer to verify updated title, description, and OG image path.

Upload URLs store the Content-Type sent on the PUT. Forward returned upload headers, or send the same content type declared in the manifest. The Site manifest reports stored content types.

Tags & smart views

• GET / PUT/api/v1/publish/:slug/tagsList or replace a Site's tags.
• GET/api/v1/tagsList all tags with usage counts.
• GET / POST/api/v1/viewsList or create smart views (saved tag filters).
• PATCH / DELETE/api/v1/views/:idUpdate or delete a smart view.
• GET/api/v1/views/:id/sitesList Sites matching a smart view.

Tags are a full replacement list, owner-only, normalized to lowercase, deduped, sorted in responses, max 50 kept, and max 32 characters each. Tags are not accepted in publish create/update bodies.

Site Data & analytics

• GET / POST/api/v1/publishes/:slug/data/:collectionList or create owner records.
• GET / PATCH / DELETE…/data/:collection/:recordIdRead, update, delete a record.
• GET/api/v1/publishes/:slug/analytics?range=Per-Site analytics (paid).
• GET/api/v1/analytics?range=Account-wide analytics rollups (paid).

Drives

• GET / POST/api/v1/drivesList or create Drives.
• GET/api/v1/drives/defaultGet or create the default Drive.
• GET/api/v1/drives/:driveId/filesList or read Drive files.
• POST/api/v1/drives/:driveId/files/uploadsStage a Drive write.
• POST/api/v1/drives/:driveId/files/finalizeFinalize a staged upload.
• PATCH/api/v1/drives/:driveId/filesApply a batch of file operations.
• POST/api/v1/drives/:driveId/tokensCreate scoped share tokens.

Drive upload staging accepts {path,size,contentType,sha256,ifNoneMatch,ifMatch} and returns {uploadId,url,headers,expiresInSeconds}. PUT bytes to the returned URL with returned headers, then finalize with {uploadId}. Use ifNoneMatch: "*" for create-only writes and ifMatch with an ETag for replacements.

Profile & account

• GET / PATCH/api/v1/profileGet or update profile settings.
• PATCH/api/v1/profile/usernameChange the profile username.
• GET / POST/api/v1/profile/sitesList or add profile Sites.
• DELETE/api/v1/profile/sites/:slugRemove a Site from the profile.
• GET / POST/api/v1/me/keysList or create API keys.
• DELETE/api/v1/me/keys/:idRevoke one API key.

Limits#

Total storage is shared by published Site versions and current Drive files. Drive version history does not count toward the quota. Presigned upload URLs are temporary — refresh them before retrying if they expire. See Pricing for per-plan quotas.

Pricing#

Analytics are included on Hobby and Developer. Machine-readable tiers and the full limits table live at /pricing.md.

Error recovery#

• Public API errors are JSON with a backwards-compatible error field.
• 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.

Resources#

• OpenAPI 3.1 spec — stable public API contract.
• Pricing — machine-readable tiers and limits.
• llms.txt — concise agent context.
• llms-full.txt — expanded agent context.
• docs/llms.txt — docs-scoped agent context.
• agent.json — agent discovery manifest.
• Public skill repo — GitHub skill and plugin repository.