# HTTP API

Base: `https://api.editorbrain.com`. Client routes use `/v1`. This guide explains the main operations and contracts of the reviewed code; see [versions](https://editorbrain.com/en/docs/versiones) for availability. It is not an OpenAPI specification and it does not promise administrative endpoints to clients.

## Authentication and scope

For an authorized API credential:

```http
Authorization: Bearer YOUR_CREDENTIAL
Content-Type: application/json
```

Keep the secret in your credential manager. The workspace comes from the authorization; sending another `workspaceId` does not grant access. Workspace keys keep that scope; CLI account credentials select a current membership as explained below. OAuth connections can be limited further by member permissions and team scope.

- `reader`: queries allowed by its scope.
- `editor`: allowed writes; it does not imply access to every spending operation.
- `owner`: workspace administration, with no automatic access to other workspaces or the internal lab.

The web session uses its own flow and protections; do not copy browser cookies to build an integration. Notification, account, sign-up and recovery settings belong to that web flow. Use the CLI device consent or MCP OAuth to connect agents.

## CLI account consent

Published since 0.50.0, with migration 0162: `POST /v1/auth/device` with `scope: "account"` and `GET /v1/account/workspaces`. It requires a new consent; installing the CLI does not widen an old credential. The `eba_` credential represents the user and accepts `X-EditorBrain-Workspace: ID` for a current membership. Without the header it uses the workspace fixed at authorization, not the one later selected in another browser tab.

The header also accompanies files and render parts. Each request revalidates membership, team permissions and revocation; selecting an ID does not grant access. Older `eh_` keys keep their workspace and reject a contradictory header. MCP OAuth stays an independent authorization. Terminals are revoked from the web session at `/v1/auth/device/connections`; the CLI credential never gains the owner role.

## First query

```sh
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $EDITORBRAIN_API_KEY" \
  https://api.editorbrain.com/v1/me
```

The example assumes the secret manager already supplied the variable. Do not write its value into the command or turn on shell traces. `/v1/me` returns identity, workspace, scope and limits; do not assume the exact shape will be identical for a restricted team member.

## Read the context of an edit

```http
POST /v1/workflow/check
```

```json
{"projectId":"my-project"}
```

The response includes review mode, resolved preferences, `editorialSnapshot`, integrations and context versions. If you pass `previousVersion` and `previousContextVersion`, check both `changed` and `contextChanged`. A document change is not detected only with the review-preferences version.

`interaction`, added after 0.39.1, describes how to ask and review without imposing a wizard. Tolerate its absence on older APIs. The server records a read receipt; it does not certify that the agent understood or edited the video.

## Documents and concurrency

```http
GET /v1/documents/videos/my-project/brief.md
PUT /v1/documents/videos/my-project/brief.md
```

Write body:

```json
{"content":"# Goal\nExplain the product clearly.\n","expectedRevision":3}
```

Use the revision you just read; `0` creates a new document. The example `3` is illustrative, not a value you can reuse on any account. The response returns the new revision and hash.

On a 409 conflict: read again, keep other people's changes, rebuild the user's intent and send a write with the current revision. Do not retry the same write blindly. Encode each path segment with `encodeURIComponent`; keep the slashes that separate folders. Arbitrary server file paths are not accepted.

## Search from a brief

```http
POST /v1/search/brief
```

```json
{
  "projectId":"my-project",
  "mode":"both",
  "brief":{
    "source":{"kind":"script","summary":"Comparison of two ways to organize tasks","inspected":["script"],"coverage":"Full script read"},
    "goal":"Explain when each option fits",
    "audience":"Professionals starting with AI",
    "tone":"Clear and close",
    "pacing":"Brisk, with pauses to read",
    "availableAssets":["Our own screenshots"],
    "missingAssets":[],
    "hardConstraints":["Keep brand colors"],
    "uncertainty":[],
    "styleQuery":"visual comparison with a demonstration",
    "eventQueries":["contrast between two alternatives"]
  }
}
```

`inspected` and `coverage` must describe a real inspection. The API retrieves candidates; it does not make or approve the creative decision. `detail` is `summary` by default; ask for `full` only if you need more evidence. `search/edit` is optional explicit analysis, not an automatic fallback.

## Operations index

The following routes require authorization except `/health`. `{id}`, `{project}`, `{revision}` and `{path}` are placeholders. The exact bodies of many operations are also in the equivalent tools of the [MCP reference](https://editorbrain.com/en/docs/mcp-tools); in REST, route IDs are not always repeated in the body. The table does not describe internal operation routes, provider callbacks or signed URLs.

### Identity, brands and documents

| Method | Route | Input / purpose |
| --- | --- | --- |
| GET | `/health` | Basic status and version; it does not prove providers |
| GET | `/v1/me` | Identity, workspace and limits |
| GET | `/v1/brands` | `limit`, `after`; accessible brands |
| GET | `/v1/projects` | `brand`, `limit`, `after`; accessible projects |
| GET | `/v1/documents` | `prefix`; bounded list |
| GET / PUT | `/v1/documents/{path}` | Read (optional `revision`) or write `content`, `expectedRevision` |
| GET | `/v1/history` | `path`, optional `before` |
| POST | `/v1/history/restore` | `path`, source revision and current `expectedRevision` |
| GET | `/v1/projects/{project}/style-policy` | Effective rules/hashes and the project's adaptation decisions; a query is not verification |
| POST | `/v1/projects/{project}/resolve` | Effective context |
| POST | `/v1/projects/{project}/export` | `adapter`: neutral, hyperframes or remotion |
| GET / POST | `/v1/keys` | Owner: list or create with `label`, `role` |
| DELETE | `/v1/keys/{id}` | Owner: revoke a key; not the active one itself |

### Preferences, memory and editorial review

| Method | Route | Input / purpose |
| --- | --- | --- |
| GET / PUT | `/v1/workflow` | Read; write `mode`, `expectedRevision` |
| POST | `/v1/workflow/check` | `projectId`, previous versions, `previousSourceHashes` (up to 256) and optional `questionNeeds` |
| GET | `/v1/integrations` | The member's personal preferences |
| PUT | `/v1/integrations/{provider}` | Validated configuration and expected revision |
| GET | `/v1/brain` | `brandId`; brain proposal status |
| POST | `/v1/brain/prepare` | Prepare a proposal; its own availability and usage |
| POST | `/v1/brain/accept` | Accept a reviewed proposal with its preconditions |
| GET / POST | `/v1/memory` | Query by `scope`, `scopeId`; change entries with a revision |
| POST | `/v1/memory/promote` | Explicit promotion of learning to a scope |
| POST | `/v1/feedback` | Record a project observation |
| GET | `/v1/improvements` | `brandId`; improvement proposals |
| POST | `/v1/improvements/settings` | Proposal settings |
| POST | `/v1/improvements/run` | Request a proposal for `brandId`; check availability |
| POST | `/v1/improvements/accept` | Accept a specific proposal with a revision |
| GET / POST | `/v1/product-learning` | Separate consent for product learning |
| POST | `/v1/product-learning/signals` | A bounded signal under consent |

### Visual Studio and delivery evidence

| Method | Route | Input / purpose |
| --- | --- | --- |
| POST | `/v1/projects/{project}/review-artifacts` | `destination`, `contextVersion`, `artifact`; local template or cloud descriptor of existing reviews |
| GET | `/v1/projects/{project}/review-artifacts/{id}/view` | Authenticated viewer; access and context revalidated |
| POST | `/v1/projects/{project}/preferences-studio` | `destination`, optional `contextVersion`; shows preferences without applying them |
| GET | `/v1/projects/{project}/delivery-evidence` | `sha256`; origin and destination of the exact file, not a new pixel check |
| POST | `/v1/projects/{project}/delivery-evidence` | Record an explicit delivery exception per the `record_render_exception` schema; it does not change the account or authorize spend |

The local artifact does not transfer disk files to the server. The cloud descriptor only links authorized reviews of the same project. The API reads preferences from the context; it does not accept a `studio.preferences` fabricated by the client. Viewer proposals and comments require the existing save flow. See [Studio](https://editorbrain.com/en/docs/revision).

`POST /v1/feedback` with `captureMemory:true` captures the project note and suggestion without duplicates; it does not confirm memory or change preferences. Corrected reviews indicate `addresses` and `revisionKind`. When `localSync` is pending, the CLI updates its documents while preserving conflicts; MCP refreshes the context. See [memory](https://editorbrain.com/en/docs/memoria).

### Libraries

| Method | Route | Input / purpose |
| --- | --- | --- |
| POST | `/v1/search/brief` | The agent's brief; see the example above |
| GET | `/v1/style-sources/{id}/source` | `version`, `sha256`; authorized style code with a temporary link |
| POST | `/v1/search/edit` | Explicitly requested edit analysis |
| GET | `/v1/library` | `query`, `limit`, `after` |
| GET | `/v1/library/{id}` | Record and accessible evidence |
| GET | `/v1/library/{id}/documents` | `path`, optional `sha256` |
| GET | `/v1/library/{id}/media/{sha256}` | Bytes of an authorized medium |
| GET | `/v1/narrative` | `query`, `kind`, `channel`, `limit` |
| GET | `/v1/library/{id}/narrative` | `eventOffset`, `relationOffset`, `limit`, `sha256` |
| GET | `/v1/style-packs` | Available styles |
| POST | `/v1/projects/{project}/recommend-styles` | Recommendations from material and capabilities |
| POST | `/v1/projects/{project}/preview-direction` | Prepare a direction, not a render |
| GET | `/v1/media-styles` | `category`: image or motion |
| GET | `/v1/media-styles/{id}` | Recipe `version` |
| GET | `/v1/motion-components` | `q`; reusable local components |
| GET | `/v1/motion-components/{id}` | Component `version` |
| GET | `/v1/authored-motion` | `q`, `limit`, `after`, `version`, `material`, `funcion`, `encuadre`, `tresD` |
| GET | `/v1/authored-motion/{id}` | Scene `version` |
| GET | `/v1/authored-motion/{id}/preview` | `version`, `ratio`, `kind`, optional `preset`; preview link |
| GET / HEAD | `/v1/authored-motion/{id}/media` | Authorized preview with version/format; bytes |
| GET | `/v1/authored-motion/{id}/source` | `version`, bundle `sha256`; source link |
| GET / PUT | `/v1/library-favorites` | Read by `brandId`; save or remove the member's selection |
| GET | `/v1/sfx/catalog` | `brandId`, `bankId`; explore an accessible bank |
| GET / HEAD | `/v1/sfx/preview` | Preview with the bank/sound identity returned by the catalog |
| GET | `/v1/sfx/search` | `projectId`, `query`, `bankId`, `limit`, `sceneRole` |
| GET | `/v1/sfx/get` | Project, bank, `soundId`, `catalogSha256` and scene role |
| POST | `/v1/sfx/check` | `projectId` in the query; plan and context hash in the body |

### Material, storage and tools

| Method | Route | Input / purpose |
| --- | --- | --- |
| GET | `/v1/resources/guide` | Fields and uses of reusable material |
| GET | `/v1/resources` | `query`, `brand`, `kind`, `state`, `limit`, `after` |
| GET / PUT | `/v1/resources/{id}` | Read or save `resource`, `expectedRevision`, applicable confirmation |
| GET / PUT | `/v1/resources/{id}/index` | Segments (`offset`, `limit`) or save a versioned index |
| GET | `/v1/assets` | `limit`, `cursor`; accessible files |
| PUT | `/v1/assets/{sha256}` | Bytes, type and length; `name`, `purpose`, `projectId`, `sourceSha256` |
| GET / HEAD | `/v1/assets/{sha256}` | Download or look up a file |
| GET | `/v1/storage` | Quota, usage and cleanup candidates |
| GET | `/v1/storage/preview-upload` | `sha256`, `bytes`, `projectId`; prior plan |
| POST | `/v1/storage/cleanup` | Validated explicit selection; protects required files |
| GET | `/v1/studio/catalog` | Tools, prices, permissions and availability |
| GET | `/v1/studio/voices` | Public Vox alias catalog; filters `q`, `language`, `accent`, `gender` |
| GET | `/v1/studio/voices/{id}/preview` | Authenticated catalog sample, when one exists; it does not generate narration |
| GET | `/v1/studio/voice-selection` | Exactly one of `brandId` or `projectId`; selection, inheritance, canonical route and revision |
| PUT | `/v1/studio/voice-selection` | `brandId` or `projectId`, `voiceId`, `expectedRevision`; changes only `audio.json.voice` |
| POST | `/v1/studio/quotes` | Tempo/Prism/Vox/Aura request; a quote |
| POST | `/v1/studio/jobs` | `quoteId`, `maxCredits`, `userConfirmed`, batch lease when it applies |
| GET | `/v1/studio/jobs` | History; `after` |
| GET | `/v1/studio/jobs/{id}` | Status and results; look up without duplicating |
| GET | `/v1/billing/status` | Balance, plan, offer and availability |
| POST | `/v1/billing/checkout` | Authorized offer and attempt; requires an enabled owner |
| POST | `/v1/billing/portal` | Enabled membership/payment portal |
| POST | `/v1/billing/welcome` | Initial benefit subject to eligibility |
| POST | `/v1/billing/reward` | `rewardId`; an eligible benefit, not arbitrary credits |

### Projects, batches, feedback and teams

| Method | Route | Input / purpose |
| --- | --- | --- |
| POST | `/v1/projects/{project}/attachments` | `importId` UUID, host `file` and `userConfirmed:true`; import and link an attachment |
| GET | `/v1/projects/{project}/attachments/{importId}` | Attempt status; it does not restart the transfer |
| GET | `/v1/projects/progress` | Comma-separated `ids`; summary |
| GET / POST | `/v1/projects/{project}/progress` | Read or change with the expected version and applicable confirmation |
| GET / POST | `/v1/batches` | List (`after`) or create a batch of existing projects |
| GET / POST | `/v1/batches/{id}` | Status or action with the expected revision |
| POST | `/v1/batches/{id}/lease` | Claim, renew, release or attention for a turn |
| GET / POST | `/v1/projects/{project}/production-reviews` | List (`after`) or register a review |
| DELETE | `/v1/projects/{project}/production-reviews/{revision}` | Revoke a review |
| GET | `/v1/projects/{project}/production-reviews/{revision}/transcript` | Transcript of that version |
| POST | `/v1/projects/{project}/production-reviews/{revision}/approve` | User confirmation and exact context |
| POST | `/v1/projects/{project}/production-reviews/{revision}/changes` | A localized change and the exact context |
| GET | `/v1/projects/{project}/production-feedback` | `status`, `revisionId`, `after` |
| POST | `/v1/projects/{project}/production-feedback/{id}/resolve` | Evidence of the correction and the new version |
| GET / POST | `/v1/reviews` | List by `projectId` or create an explicit review link |
| DELETE | `/v1/reviews/{id}` | Revoke a link |
| GET | `/v1/team` | The member's scope and capabilities |
| GET | `/v1/team/members` | Members and invitations; owner only |
| PATCH | `/v1/team/members/{id}` | Owner only: `{expectedRevision,grants:[{kind,scopeId}],userConfirmed:true}`; replaces grants with concurrency control |
| DELETE | `/v1/team/members/{id}` | Remove an authorized member |
| POST | `/v1/team/invitations` | Invite an email with type and scope; sends a real email |
| DELETE | `/v1/team/invitations/{id}` | Revoke an invitation |
| POST | `/v1/team/preview` | Authenticated browser: `{token}`, verified recipient; shows scope without accepting |
| POST | `/v1/team/accept` | Authenticated browser: `{token}`; explicit acceptance, selects the shared workspace |
| GET | `/v1/team/projects` | Projects the team can access |
| GET | `/v1/team/projects/{project}/reviews` | Shared versions; `after` |
| GET | `/v1/team/projects/{project}/reviews/{revision}/comments` | Public comments on this version, `after`, `nextCursor`; access revalidated on every page |
| POST | `/v1/team/projects/{project}/reviews/{revision}/share` | Share or withdraw a version according to the action |
| POST | `/v1/team/projects/{project}/reviews/{revision}/comment` | Comment and optional moment |
| POST | `/v1/team/projects/{project}/reviews/{revision}/approve` | Explicit approval of version and context |

`GET /v1/team/members` includes `permissionsRevision` for each restricted collaborator. Use that value as `expectedRevision` when you save the complete list of 1–100 grants (`brand_editor` or `project_reviewer`); do not send a workspace ID. `team_permissions_changed` (409) requires you to read again and reconcile. Saving invalidates earlier links. If the member is left only as a reviewer, their agent connections are revoked; files are not deleted. To remove every access, use DELETE.

## Pagination

Not every endpoint uses the same cursor. Return the value you received to the same endpoint, with the same filters. In motion, `after` is opaque and tied to the query, facets and version. If you build URLs with `URLSearchParams`, pass the original cursor and let that function encode it once. Do not run `decodeURIComponent` on it.

A filter change starts a new query. An empty list does not mean permissions were lost and does not prove there is no material on another page. Do not widen the search to another client to fill it.

## Files and temporary URLs

An asset upload requires `Content-Length` between 1 byte and 90 MiB and an accepted MIME (MP4/MOV/WebM, PNG/JPEG/WebP, MP3/WAV/M4A/OGG). The ID is the SHA-256 of the bytes; the service verifies it. The workspace quota can be smaller than the technical maximum.

Files are authorized by workspace and project, not by knowing the hash. Store IDs and hashes, not temporary signed URLs. When a link expires, request it again with the right credential. On partial downloads, respect `Range`, 206 and 416.

## Errors and retries

Usual HTTP error shape:

```json
{"error":{"code":"revision_conflict","message":"The document changed; read it again."}}
```

The example text is illustrative. Use `error.code`, the HTTP status and `error.recovery` when it exists; do not parse the message. 401: authentication; 403: permissions; 404: resource not accessible; 409: conflict; 413/415: size or format; 429: wait; 503: capacity unavailable. The API adds `Retry-After` on 429 responses.

GETs can be retried with a bounded wait when the failure is transient. Do not retry a spending POST after a timeout without looking up the original attempt. For Studio, keep `quoteId` and the job ID; for payments, keep the attempt ID. Do not invent a universal idempotency header: each operation defines its own mechanism.

## Discover and resume projects

This contract requires API **0.45.0 or later**. Check [availability](https://editorbrain.com/en/docs/versiones) before you depend on these routes. `GET /v1/projects` accepts `brand`, `query`, `updatedSince`, `updatedBefore`, `sort=recent|id`, `limit` and `after`. Dates are ISO UTC; the interval includes the start and excludes the end. The query compares ID, name and topic literally. `lastActivityAt` uses server times of documents and progress. `checkpoint` summarizes the latest milestone with its revision, hash and server date, not the date the agent declared; it does not imply approval. Continue with `nextCursor` without modifying it and keep filters and workspace. It is a live list: deduplicate by ID and restart without a cursor for a fresh read. Current brand and project permissions apply on every page. There is no archived-project filter; a `completed` milestone does not hide the project.

`GET /v1/projects/ID/continuity` gathers context, checkpoint, reviews, pending feedback, batch, jobs and the catalog of authorized assets. Each section indicates `available` with `value`, or `unavailable` with the reason; bounded lists declare `complete` / `nextCursor`. Studio jobs belong to the current connection. Each section respects the account's capabilities and permissions. Providers and private device paths are not exposed. The query does not start jobs, refresh billing or download media. Each device's folder registry is private and is not part of this API. `lastApprovedReview` recovers the latest historical approval even if it is not on the first page. Only `effectiveApproval=true` confirms it is still current; it may have been invalidated by context changes, feedback or availability.

It accepts `reviewsAfter`, `feedbackAfter` and `studioAfter` to continue those lists. A 409 `continuity_changed` requires you to read again, because the context changed. A catalogued resource does not attest its bytes and is not a public link: to recover it, use the authorized download endpoint and verify its hash. Saved preferences do not grant spending permission.

Checkpoints v1 and v2 travel through the existing document API, with their expected revision. V2 keeps the declared version, relative artifacts, dependencies, an orienting command and context hashes; saved content is never executed. History and restore use the existing document endpoints: restoring creates a new revision, it does not delete previous versions or change approvals.

## Task map and compact orientation

`GET /v1/guide/tasks` returns the public help topics; `?topic=sound` returns a route with commands, tools and references. It requires the usual authenticated session; it does not search resources, run tasks or announce private capabilities. Each operation's handlers still check their permissions.

`POST /v1/workflow/check` accepts `detail: "compact" | "summary" | "full"` in the current contract. Compact keeps a complete `editorialSnapshot`, replaces identical copies with `sameAs` markers and keeps the recent receipt with the count of omitted items. Full recovers the previous complete shape. The summary has `kind: "editorbrain.workflow-summary"`, explicit `coverage` and the way back to the detail; it does not contain a complete `editorialSnapshot`. `nextActions` only orients, even when there are unregistered resources.

### Import a host attachment

`file` contains `download_url` and `file_id`, optionally `mime_type` and `file_name`. Only the HTTPS transport of `files.oaiusercontent.com` and its subdomains is accepted, with no redirects. Do not pass disk paths, base64 or web page URLs. Maximum 90 MiB, known size and media MP4/MOV/WebM, PNG/JPEG/WebP or MP3/WAV/M4A/OGG; signature, size and SHA-256 are verified. URLs are not persisted.

Use a stable UUID per file and project. `receiving`, `stored`, `complete` and `failed` distinguish transfer from registration: on an uncertain response, look up the status; `stored` lets you retry registration without downloading again. A renewed URL keeps the same file ID and name/type. The upload does not spend credits or start jobs; it respects quota, member, project and `allowUploads`. A current explicit exception can allow the upload without changing saved preferences; check the contract your account announces. The objects are private originals; preview policies do not delete them.

## Cleanup after approval and plan changes

The current code includes `GET/PUT /v1/storage/after-approval` and `POST /v1/storage/preview-cleanup`. Looking up the option does not delete files; changing it requires confirmation, revision and permissions. Cloud cleanup keeps history and can respond `preview_expired` / 410 for expired bytes. Check capability and deployment; the matching local commands require CLI 0.52.0 or later. [Storage](https://editorbrain.com/en/docs/material).

Compatible subscription changes use `POST /v1/billing/plan-change-preview` and `POST /v1/billing/plan-change-confirm`, with an owner and billing enabled. The second receives the proposal's ID and accepted maximum according to its contract, not values from a screenshot. Another checkout is not used to duplicate a subscription. The agent sends the owner to [Plan and credits](https://editorbrain.com/en/docs/creditos) and checks the result again; it does not confirm charges for them.
