CineSignal API: start here
This document describes personal-key access. A user creates an expiring key at https://cinesignal.com/settings/api-keys. Only use a key when its owner explicitly authorizes you to act for them. Never include it in a URL, logs, generated content, or requests to another domain. Ask before making changes, especially destructive ones.
Base URL: https://cinesignal.com/api/agent/v1
Authentication: send the user's key in the Authorization header as Bearer <key>. Do not send cookies. All responses are JSON, and authenticated responses must not be cached. A key expires after its selected lifetime or immediately when revoked in settings. A 401 means the key is invalid, expired, or revoked.
Endpoints:
- GET /me — returns { "profile": { "id", "name", "slug", "bio", "location", "website" } }.
- PATCH /me — update your profile with JSON fields "name", "bio", "location", or "website" (HTTP(S) URL). Unrecognized fields are ignored.
- GET /drafts — returns { "drafts": [...] }, up to 100 most recently updated private screenplay drafts (metadata, no source). Each draft carries "source_updated_at" (see PATCH /drafts/:id).
- GET /drafts/:id — returns { "draft": { "id", "title", "logline", "fountain_source", "status", "created_at", "updated_at", "source_updated_at" } } for your own draft. "updated_at" moves when anything on the draft changes. "source_updated_at" moves only when "fountain_source" changes; it is the version of the script text.
- POST /drafts — JSON object with required "title" (1–200 characters) and optional "logline" (up to 2000 characters), "fountain_source" (up to 900000 characters). Returns 201 with { "draft": ... }.
- PATCH /drafts/:id — JSON object with one or more of "title", "logline" (nullable), "fountain_source", and optionally "base_updated_at". Returns { "draft": ... }. Only your own drafts are writable.
- "base_updated_at" is the "source_updated_at" of the draft as you last read it, sent back exactly as you received it (an ISO 8601 instant with a time zone offset; anything else is a 400). Send it whenever you change "fountain_source". If the script text has changed since that version, nothing is written and the answer is 409 with { "error", "reference", "draft": { ..., "fountain_source", "source_updated_at" } }, where "draft" is the current copy on the server. Compare "source_updated_at" for equality; it is not a clock. A change to only the title or logline never makes a base stale, and "base_updated_at" is not needed for those.
- Read, edit, write back with the version you read: GET the draft, edit its "fountain_source", then PATCH it with "base_updated_at" set to the "source_updated_at" you read. On 409, merge your edit into the "fountain_source" in the response (the writer may have typed or saved since), then PATCH again with the "source_updated_at" from that response.
- A write without "base_updated_at" still succeeds, as it always has. When it replaces script text that differs from the new text, the replaced text is first kept as an unnamed copy in the draft's History, so the writer can get it back. If that copy cannot be saved, nothing is written and the answer is 500 with a "reference" you can quote.
For writes set Content-Type: application/json. Use the draft ID returned by list or create. A 404 means the draft does not exist or does not belong to the key owner; 400 means invalid input. Do not expose the user's private draft text to others.
Existing account API routes under https://cinesignal.com/api/ also accept the same Authorization header wherever a signed-in user could use a cookie session. The account's existing permissions and authorization checks still apply. Examples: GET /api/galleries lists your galleries; POST /api/galleries creates a gallery using JSON fields "title" and optional "description" and "privacy"; GET /api/account-deletion shows your pending deletion request. Treat deletion, uploads, publishing, spending credits, and other write operations as sensitive: confirm their effects with the user first. These application endpoints have route-specific payloads and are not a stable versioned API; inspect the actual endpoint before constructing a request. Service webhooks, device pairing, and public endpoints use their own authentication protocols and do not impersonate an account.