Skip to content
EditorBrainDocsEspañolOpen EditorBrain ↗

Developers

HTTP API

Authentication, endpoints, files, errors and concurrency.

Download Markdown ↗

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:

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.

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

Terminal
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; 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

MethodRouteInput / purpose
GET/healthBasic status and version; it does not prove providers
GET/v1/meIdentity, workspace and limits
GET/v1/brandslimit, after; accessible brands
GET/v1/projectsbrand, limit, after; accessible projects
GET/v1/documentsprefix; bounded list
GET / PUT/v1/documents/{path}Read (optional revision) or write content, expectedRevision
GET/v1/historypath, optional before
POST/v1/history/restorepath, source revision and current expectedRevision
GET/v1/projects/{project}/style-policyEffective rules/hashes and the project's adaptation decisions; a query is not verification
POST/v1/projects/{project}/resolveEffective context
POST/v1/projects/{project}/exportadapter: neutral, hyperframes or remotion
GET / POST/v1/keysOwner: list or create with label, role
DELETE/v1/keys/{id}Owner: revoke a key; not the active one itself

Preferences, memory and editorial review

MethodRouteInput / purpose
GET / PUT/v1/workflowRead; write mode, expectedRevision
POST/v1/workflow/checkprojectId, previous versions, previousSourceHashes (up to 256) and optional questionNeeds
GET/v1/integrationsThe member's personal preferences
PUT/v1/integrations/{provider}Validated configuration and expected revision
GET/v1/brainbrandId; brain proposal status
POST/v1/brain/preparePrepare a proposal; its own availability and usage
POST/v1/brain/acceptAccept a reviewed proposal with its preconditions
GET / POST/v1/memoryQuery by scope, scopeId; change entries with a revision
POST/v1/memory/promoteExplicit promotion of learning to a scope
POST/v1/feedbackRecord a project observation
GET/v1/improvementsbrandId; improvement proposals
POST/v1/improvements/settingsProposal settings
POST/v1/improvements/runRequest a proposal for brandId; check availability
POST/v1/improvements/acceptAccept a specific proposal with a revision
GET / POST/v1/product-learningSeparate consent for product learning
POST/v1/product-learning/signalsA bounded signal under consent

Visual Studio and delivery evidence

MethodRouteInput / purpose
POST/v1/projects/{project}/review-artifactsdestination, contextVersion, artifact; local template or cloud descriptor of existing reviews
GET/v1/projects/{project}/review-artifacts/{id}/viewAuthenticated viewer; access and context revalidated
POST/v1/projects/{project}/preferences-studiodestination, optional contextVersion; shows preferences without applying them
GET/v1/projects/{project}/delivery-evidencesha256; origin and destination of the exact file, not a new pixel check
POST/v1/projects/{project}/delivery-evidenceRecord 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

MethodRouteInput / purpose
POST/v1/search/briefThe agent's brief; see the example above
GET/v1/style-sources/{id}/sourceversion, sha256; authorized style code with a temporary link
POST/v1/search/editExplicitly requested edit analysis
GET/v1/libraryquery, limit, after
GET/v1/library/{id}Record and accessible evidence
GET/v1/library/{id}/documentspath, optional sha256
GET/v1/library/{id}/media/{sha256}Bytes of an authorized medium
GET/v1/narrativequery, kind, channel, limit
GET/v1/library/{id}/narrativeeventOffset, relationOffset, limit, sha256
GET/v1/style-packsAvailable styles
POST/v1/projects/{project}/recommend-stylesRecommendations from material and capabilities
POST/v1/projects/{project}/preview-directionPrepare a direction, not a render
GET/v1/media-stylescategory: image or motion
GET/v1/media-styles/{id}Recipe version
GET/v1/motion-componentsq; reusable local components
GET/v1/motion-components/{id}Component version
GET/v1/authored-motionq, limit, after, version, material, funcion, encuadre, tresD
GET/v1/authored-motion/{id}Scene version
GET/v1/authored-motion/{id}/previewversion, ratio, kind, optional preset; preview link
GET / HEAD/v1/authored-motion/{id}/mediaAuthorized preview with version/format; bytes
GET/v1/authored-motion/{id}/sourceversion, bundle sha256; source link
GET / PUT/v1/library-favoritesRead by brandId; save or remove the member's selection
GET/v1/sfx/catalogbrandId, bankId; explore an accessible bank
GET / HEAD/v1/sfx/previewPreview with the bank/sound identity returned by the catalog
GET/v1/sfx/searchprojectId, query, bankId, limit, sceneRole
GET/v1/sfx/getProject, bank, soundId, catalogSha256 and scene role
POST/v1/sfx/checkprojectId in the query; plan and context hash in the body

Material, storage and tools

MethodRouteInput / purpose
GET/v1/resources/guideFields and uses of reusable material
GET/v1/resourcesquery, brand, kind, state, limit, after
GET / PUT/v1/resources/{id}Read or save resource, expectedRevision, applicable confirmation
GET / PUT/v1/resources/{id}/indexSegments (offset, limit) or save a versioned index
GET/v1/assetslimit, 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/storageQuota, usage and cleanup candidates
GET/v1/storage/preview-uploadsha256, bytes, projectId; prior plan
POST/v1/storage/cleanupValidated explicit selection; protects required files
GET/v1/studio/catalogTools, prices, permissions and availability
GET/v1/studio/voicesPublic Vox alias catalog; filters q, language, accent, gender
GET/v1/studio/voices/{id}/previewAuthenticated catalog sample, when one exists; it does not generate narration
GET/v1/studio/voice-selectionExactly one of brandId or projectId; selection, inheritance, canonical route and revision
PUT/v1/studio/voice-selectionbrandId or projectId, voiceId, expectedRevision; changes only audio.json.voice
POST/v1/studio/quotesTempo/Prism/Vox/Aura request; a quote
POST/v1/studio/jobsquoteId, maxCredits, userConfirmed, batch lease when it applies
GET/v1/studio/jobsHistory; after
GET/v1/studio/jobs/{id}Status and results; look up without duplicating
GET/v1/billing/statusBalance, plan, offer and availability
POST/v1/billing/checkoutAuthorized offer and attempt; requires an enabled owner
POST/v1/billing/portalEnabled membership/payment portal
POST/v1/billing/welcomeInitial benefit subject to eligibility
POST/v1/billing/rewardrewardId; an eligible benefit, not arbitrary credits

Projects, batches, feedback and teams

MethodRouteInput / purpose
POST/v1/projects/{project}/attachmentsimportId 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/progressComma-separated ids; summary
GET / POST/v1/projects/{project}/progressRead or change with the expected version and applicable confirmation
GET / POST/v1/batchesList (after) or create a batch of existing projects
GET / POST/v1/batches/{id}Status or action with the expected revision
POST/v1/batches/{id}/leaseClaim, renew, release or attention for a turn
GET / POST/v1/projects/{project}/production-reviewsList (after) or register a review
DELETE/v1/projects/{project}/production-reviews/{revision}Revoke a review
GET/v1/projects/{project}/production-reviews/{revision}/transcriptTranscript of that version
POST/v1/projects/{project}/production-reviews/{revision}/approveUser confirmation and exact context
POST/v1/projects/{project}/production-reviews/{revision}/changesA localized change and the exact context
GET/v1/projects/{project}/production-feedbackstatus, revisionId, after
POST/v1/projects/{project}/production-feedback/{id}/resolveEvidence of the correction and the new version
GET / POST/v1/reviewsList by projectId or create an explicit review link
DELETE/v1/reviews/{id}Revoke a link
GET/v1/teamThe member's scope and capabilities
GET/v1/team/membersMembers 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/invitationsInvite an email with type and scope; sends a real email
DELETE/v1/team/invitations/{id}Revoke an invitation
POST/v1/team/previewAuthenticated browser: {token}, verified recipient; shows scope without accepting
POST/v1/team/acceptAuthenticated browser: {token}; explicit acceptance, selects the shared workspace
GET/v1/team/projectsProjects the team can access
GET/v1/team/projects/{project}/reviewsShared versions; after
GET/v1/team/projects/{project}/reviews/{revision}/commentsPublic comments on this version, after, nextCursor; access revalidated on every page
POST/v1/team/projects/{project}/reviews/{revision}/shareShare or withdraw a version according to the action
POST/v1/team/projects/{project}/reviews/{revision}/commentComment and optional moment
POST/v1/team/projects/{project}/reviews/{revision}/approveExplicit 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 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.

Next in developersIntegrate from code →