# ClipZyn > ClipZyn turns podcast or video sources into ranked short clips. It is agents-first: signup is programmatic, keys authenticate every operational call, and there is one human step, once: a person confirms the account's email address. Use REST under `/v1` through OpenAPI 3.1, or use the hosted MCP endpoint through streamable HTTP or stdio. ## Get access ```bash curl -sS -X POST "$CLIPZYN_BASE/v1/signup" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: signup-one' \ -d '{"email":"agent@example.com"}' ``` The response contains a one-time API key and sandbox limits, and `email_confirmation` is `pending`: ClipZyn emails a confirmation link to the address, and the key answers `403 email_unconfirmed` until a person opens it. Later keys live on the web account key page. One account is allowed per normalized email; `409 account_exists` means the owner must sign in and mint a key there. An API key inherits the owning account's tier, caps and entitlements: a key minted from an unlimited account runs with unlimited uploads, and a sandbox signup's key carries the sandbox limits. A key is a credential for an account, never a plan of its own, so `GET /v1/account` is the authority on what this key may spend. Keys also manage keys only from the web page by design: `account:write` is neither a default scope nor one either mint door will grant on request, so a key minted from either door cannot mint, rotate, or revoke another. ## The three laws Poll first at `eta_sec`, then at most once every 60 to 120 seconds. Runs commonly take 10 to 45+ minutes. Download URLs expire after about 30 minutes. Mint one at the moment of use and never reuse a URL from history. Send `Idempotency-Key` on every POST. Replays are marked and safe. Apply these six rules exactly: 1. Send `Idempotency-Key` on **every** POST. Derive one key per intent (one per run you want to exist, one per checkout you want to offer), not per attempt; reuse the same key on every retry of that intent; never reuse a key across different intents. 2. Trust the envelope over your own heuristics: `retryable: false` means the same request will never succeed as-is (fix it or make the different call the hint names); `retryable: true` plus `retry_after_sec` is the whole retry policy. 3. If a response carries no envelope at all (edge faults, timeouts), retry once after 30 seconds with the same Idempotency-Key, then stop and report. 4. Never tighten a polling interval in response to a 429; wait `retry_after_sec` and resume the documented cadence. 5. A replay is marked `Idempotent-Replay: true`, returns the original outcome, never re-charges, and never re-shows a credential (signup replays omit `api_key` by design: mint a fresh key from the web key page if you lost one). 6. On 409 `duplicate_run` / `idempotency_key_reuse` / `idempotency_in_progress`, the work (or the key) already exists: recover ids via `GET /v1/runs` rather than starting again. ## The core loop 1. `POST /v1/signup` 2. `GET /v1/account` 3. `POST /v1/runs` 4. `GET /v1/runs/{run_id}/progress` 5. `GET /v1/runs/{run_id}/artifacts` 6. `POST /v1/runs/{run_id}/clips/{clip_id}/download-url` The sandbox allows one lifetime run, sources up to 30 minutes, and `top_n` up to 3. ## Connect your harness - [Claude Code](/v1/docs/configs/claude-code.md) - [Claude Desktop](/v1/docs/configs/claude-desktop.md) - [ChatGPT connector](/v1/docs/configs/chatgpt-connector.md) - [ChatGPT Actions](/v1/docs/configs/chatgpt-actions.md) - [Codex](/v1/docs/configs/codex.md) - [curl](/v1/docs/configs/curl.md) The hosted MCP endpoint is `https://clipzyn-mcp-production.up.railway.app/mcp`. Signup is REST-only by design. ## Reference - [OpenAPI 3.1](/v1/openapi.json) - [ChatGPT-Actions import profile](/v1/openapi.actions.json) - [Quickstart](/v1/docs/quickstart.md) - [Error catalog](/v1/docs/errors.md) - [Webhook guide](/v1/docs/webhooks.md) - [Stability contract](/v1/docs/stability.md) - [Changelog](/v1/changelog.json) - [Plans and limits](/v1/pricing.json) - [Schema index](/v1/schemas/) - [Full agent reference](/llms-full.txt) ## Stability Additive-only: a documented operation, request field, or response field is never removed or repurposed, and operationIds are stable, so an integration written today keeps working. A deprecation, if one is ever scheduled, is announced with a `Deprecation` response header and served through a dated `Sunset` header, never removed silently. Every change is recorded machine-readably at [/v1/changelog.json](/v1/changelog.json). ## Before you spend `POST /v1/runs/preflight` dry-runs a run body and returns whether it would be admitted, its quota cost, and the exact rejection it would otherwise produce. It enqueues nothing, spends no quota, and consumes no `Idempotency-Key`. Read plans, quota shapes, and per-key rate limits without a key at [/v1/pricing.json](/v1/pricing.json). ## Limits, billing, and your human Sandbox accounts get one lifetime run with a source no longer than 30 minutes. Your key spends the OWNING ACCOUNT's caps, not a per-key allowance, so several keys on one account share one quota and a key minted from an upgraded account is upgraded the moment the account is. `POST /v1/billing/checkout` returns a Stripe-hosted checkout URL; relay it to your human principal, then confirm the tier with `GET /v1/billing`. When plans are not on sale on this deployment, checkout answers `403 billing_not_offered` with the reason, and `/v1/pricing.json` reports the same reason in `purchase_unavailable_reason` and marks every plan `purchasable: false` -- read it before offering your principal a price. Humans use the web app to view what their agent made. ## Support Cite `request_id` from the error envelope when contacting support at contact@clipzyn.com.