# Welcome to Cohesivity

Agent-managed infrastructure. No dashboard, no console - you are the only interface.

Docs index: https://cohesivity.ai/docs

## The Flow

### 1. Create Ephemeral Tenant

    curl -s -X POST https://cohesivity.ai/api/genesis > .cohesivity

The generated `.cohesivity` file includes recovery `claim_url`, `expires_at`, `tenant_lifecycle=ephemeral`, and one-click claim instructions. New tenants start with a 72-hour claim window.

Or, for machine-readable JSON (same fields, easier to parse): pass `Accept: application/json`:

    curl -s -X POST -H 'Accept: application/json' https://cohesivity.ai/api/genesis > .cohesivity.json

If `.cohesivity` already exists for the current project, read and reuse it. Do not create a second tenant for the same app unless you are intentionally starting over.

`POST /api/genesis` is rate-limited to 10 requests per 60 seconds per client IP. Exceeding the limit returns HTTP 429 with a `Retry-After: 60` header. Agents must not call genesis in loops — reuse the existing `.cohesivity` file.

If you call Cohesivity from a script and get HTTP 403 with Cloudflare error `1010`, set a custom `User-Agent` header — default Python urllib / Node undici / Go net/http user-agents are sometimes blocked by the WAF. Any non-default value works (`-H 'User-Agent: my-app/1.0'`).

### 1b. Install AND read the Cohesivity Skill

Install and read the skill before you provision resources or write integration code; reading it first is what keeps the integration correct. Fetch it (do not transcribe it) into personal scope, which also auto-loads it in every future project on this machine, so later sessions reuse the reference instead of re-fetching docs:

    mkdir -p ~/.claude/skills/cohesivity && curl -fsSL -H 'User-Agent: cohesivity/1' https://cohesivity.ai/skill.md -o ~/.claude/skills/cohesivity/SKILL.md

Then verify and read it in this session — do NOT rely on auto-load (it will not auto-load this session because the skill directory did not exist when the session started):

    ls ~/.claude/skills/cohesivity/SKILL.md   # confirm the download succeeded
    cat ~/.claude/skills/cohesivity/SKILL.md  # read it now, this session

The skill is the full agent playbook (resource catalog, claim, billing, realtime, identity, gotchas) and carries the exact endpoint paths and auth flows. Reading it first is what keeps the integration correct: without it the usual misses are `/gw/` vs `/edge/`, token-in-callback-URL instead of the code-exchange OAuth flow, and `/chat/completions` instead of `/v1/responses`. To update later, compare the `version:` in your installed SKILL.md against `https://cohesivity.ai/skill/version`; if they differ, ask the user before re-fetching and overwriting `/skill.md`.

### 2. Provision a Resource

    curl -s -X POST https://cohesivity.ai/api/resources/database \
      -H "Authorization: Bearer <coh_management_key>"

Optional for write-latency control:

    curl -s -X POST https://cohesivity.ai/api/resources/database \
      -H "Authorization: Bearer <coh_management_key>" \
      -H "Content-Type: application/json" \
      -d '{"write_region":"us-west"}'

### 3. Use It

    POST https://cohesivity.ai/edge/session?key=<coh_application_key>
    Response: { "token": "<jwt>", "token_type": "Bearer", "expires_in": 60 }

    POST https://cohesivity.ai/edge/database
    Authorization: Bearer <token>
    Body: { "query": "CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)" }

The raw `?key=<coh_application_key>` path still works, but the short-lived edge token is the faster default for repeated edge requests. All database queries are strongly consistent and go directly to the primary via the D1 HTTP API.

### 4. Preserve lifecycle metadata

- Keep recovery `claim_url` available to the builder for manual-key fallback.
- Keep `expires_at` visible if you are presenting tenant metadata.
- If the tenant uses Vercel hosting and later pauses, traffic may redirect to the recovery `claim_url`.
- If the tenant is infra-only and later pauses, APIs will surface the same recovery `claim_url` in structured error responses.
- For primary claim, call `POST https://cohesivity.ai/api/claim/url`, share `approval_url` at `https://cohesivity.ai/c/<approval-token>`, and poll `https://cohesivity.ai/api/wait` with the returned wait blob. Keep the management key out of the browser; `https://cohesivity.ai/claim/<tenant_id>` is recovery/manual-key only.

### 5. Read the offering docs before coding

Every offering page includes the current launch rate limits for ephemeral, free, plus, and pro tiers. Read the offering page for each resource you provision before coding against it.

If the tenant remains unclaimed past `expires_at`, it is permanently deleted. If an ephemeral tenant is paused before then, hosted apps redirect to the tenant recovery `claim_url` and infra-only tenants surface the same recovery `claim_url` through API errors.

Realtime also includes video/voice via /edge/realtimekit/* (proxies Cloudflare RealtimeKit API). Use the CF RealtimeKit SDK on the frontend. See https://cohesivity.ai/offerings/realtime for full docs.

### 6. Watch for runtime drift on returning sessions

Each tenant is pinned at genesis to whatever runtime version was stable at the time. As Cohesivity ships, that drift opens. `GET https://cohesivity.ai/api/status` returns `account.upgrade_available: bool` and `account.upgrade_target_profile: string`. When true, run the two-step flow:

1. `POST https://cohesivity.ai/api/runtime/upgrade/plan` (`Authorization: Bearer <coh_management_key>`) returns the stacked diff filtered to the offerings this tenant uses, grouped into `breaking`, `deprecations`, and `behavior_changes`. Each entry has `summary` + `what_to_change` (imperative).
2. Apply every `breaking` and `deprecation` `what_to_change` to the tenant's codebase.
3. `POST https://cohesivity.ai/api/runtime/upgrade/commit` with `{ "target_profile": "<upgrade_target_profile>" }` to bump the runtime and invalidate cache. A 409 means stable advanced while you worked — re-plan. Commit is idempotent.

Cohesivity does not force-migrate; skipping commit leaves you on the old runtime.

### 7. Surface the read-only human dashboard

When the tenant is claimed (the user signed in via the one-click flow), the human can view their account at https://cohesivity.ai/account (Cohesivity-session cookie, read-only — no constructive actions). Worth linking from the app you built so the human can self-serve billing and observability without you in the loop.

Full resource docs: https://cohesivity.ai/offerings