Base: https://api.editorbrain.com. Client routes use /v1. This guide explains the main operations and contracts of the reviewed code; see versions 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:
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
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
POST /v1/workflow/check
{"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
GET /v1/documents/videos/my-project/brief.md
PUT /v1/documents/videos/my-project/brief.md
Write body:
{"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
POST /v1/search/brief
{
"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; 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.
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.
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:
{"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 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.
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 and checks the result again; it does not confirm charges for them.