Eve library

API guide — controlled human video

Guide

Revision 1

On this page

Phase 182, 182.C.39.03. The endpoint surface, the examples, and what the examples are allowed to claim.

Three things to know before the first request#

This is mounted now, and most of it still answers 503. That sentence replaced "nothing here is mounted" on 2026-09-12: server.ts registers all thirty-two endpoints, and a deployment with no database binds exactly one of them. Which is which is in the boot line, and the boot line from a real run is archived at evidence/2026-09-12-live-surface-capture/boot-line.txt.

Four responses in this guide were captured from a running server, and they are the four that say what the surface does when it is not fully configured:

capture what it shows
evidence/2026-09-12-live-surface-capture/presets-200.json GET /presets with an hv:* token — the catalogue, served with no database at all
.../identity-packs-503.json GET /identity-packs — hv.internal.store_unavailable, with the detail naming the operation
.../presets-403-domain.json the same request with domain:* — refused, because that scope must not reach this surface
.../boot-line.txt what a 503 will mean on that deployment, port by port

Every OTHER payload below is derived from the schema and labelled as such. A hand-written 200 presented as a capture is exactly the misleading mocked success claim this item exists to prevent, and the way you tell the difference is that a captured response carries a dated evidence path under docs/domains/isis/human-video/evidence/ (182.C.01.04).

A complete example needs an input, and the input is a person's face. A runnable quickstart therefore has to ship either biometric data or something that is not the real input. It ships neither: the only publishable subject is the 182.C.33.10 smoke corpus, which is a test pattern and a tone with no face in it. So a quickstart against the smoke corpus exercises the transport — auth, idempotency, preconditions, polling, error shapes — and proves nothing about identity or sync. That limit is the honest one, and it is stated rather than worked around.

Credentials never appear in an example. Every snippet reads its token from the environment. A key written into documentation is a leaked key from the moment it is written, and rotating it later does not unpublish it.

Two versions, and conflating them is the bug#

The URL version pins the shape of the route. schemaVersion on the payload pins the shape of the document. They move independently, and the case that proves it is a stored one: a candidate written under schemaVersion 1 and read back tomorrow through a later route is still a v1 document — the route cannot change what was written last week. A response carries the schema version of the document it contains, never the version of the path it arrived on (human-video-api-surface.ts, assertDocumentVersionHonest).

The surface#

Base path /v1/human-video. Forty operations, of which twenty-three accept an Idempotency-Key and seven require an If-Match, because they decide something somebody else may be deciding at the same time. One of the forty — POST /jobs/estimate — is a POST that accepts no key at all, because it writes nothing: it is a question whose argument is a plan, and a plan of eight shots in a query string is a URL a proxy truncates.

The table below is not the surface; human-video-api-surface.ts is, and the generated SDK is emitted from it. Rows here have gone missing before.

Operation Idempotency-Key If-Match What it does
POST /upload-sessions yes — open a resumable upload for a reference image or an audio track
GET /upload-sessions/:sessionId — — where a resumable upload got to, so a client can continue it
POST /upload-sessions/:sessionId/chunks/:offset yes — the bytes at that offset, sent as application/octet-stream — the body is the chunk, not a description of it
POST /upload-sessions/:sessionId/completion yes — stop the upload and digest what was stored; the digest is what an authorization later binds to
POST /upload-sessions/:sessionId/abandonment yes — give up on an upload, release its quota, and destroy the bytes it staged
POST /identity-packs yes — declare a reference set with its roles and authorizations
GET /identity-packs — — the reference sets in reach
GET /identity-packs/:packId — — one reference set, with its per-reference quality findings
POST /audio yes — register a speech track and its word alignment
GET /audio/:audioId — — one speech track with its alignment, exactness and approval state — and the ETag the approval demands
POST /audio/:audioId/approval yes yes approve the exact audio a render will be measured against; deciding, because every sync verdict downstream is a fact about this take
POST /jobs/estimate no — what a plan would cost on each route that could serve it, before anything is submitted — a floor from a live price list, and no route is proven
POST /jobs yes — submit a directed human-video request
GET /jobs — — jobs in reach, newest first
GET /jobs/:jobId — — one job with its stage and honest progress
POST /jobs/:jobId/cancellation yes — stop waiting for a job; its own verb rather than a DELETE, because 182.C.15.05 established that cancelling a submitted render recovers nothing
GET /jobs/:jobId/candidates — — the takes a job produced
GET /candidates/:candidateId — — one take with its lineage
GET /candidates/:candidateId/measurements — — what was measured, and what could not be
GET /reviews — — candidates waiting for a human decision, each with what THIS reviewer may hold
POST /candidates/:candidateId/approval yes yes accept a take against the measurements currently on it
POST /candidates/:candidateId/rejection yes yes set a take aside, keeping its measurements on the record
POST /candidates/:candidateId/corrections yes yes send a take back to be corrected; deciding, because 182.C.21.09 invalidates eight gates and most of what was just reviewed stops being true
POST /jobs/:jobId/shots/:shotId/regenerations yes yes rebuild a shot, having been shown what else it invalidates
POST /candidates/:candidateId/release yes yes publish a cleared take
POST /candidates/:candidateId/release/withdrawal yes — pull a published take back
DELETE /assets/:assetId yes — destroy an asset and every derived copy, returning what was destroyed rather than a bare 204
POST /authorizations/:authorizationId/withdrawal yes — withdraw an authorization and destroy what it permitted, including the embeddings that outlive the images
GET /projects — — projects in reach
POST /projects yes — start a project: the row the authoring work waits in while the subject enrols
GET /projects/:projectId — — the authoring state — cast, references, script, audio refs, shots, preset
PATCH /projects/:projectId yes — replace the authoring content, against the version it was edited from
GET /presets — — the presets and advanced settings a creator may choose from, and the three settings deliberately not offered

A session was not an upload, and for most of the phase that is all there was#

POST /upload-sessions opened one and GET /upload-sessions/:id answered a nextOffset — "send the next chunk here" — and there was nowhere to send it. Two operations that start a resumable upload and report its progress, and none that moves a byte. The three above are the rest of the protocol human-video-upload-session.ts has implemented since the phase began.

The chunk's body is the chunk. application/octet-stream, parsed inside the human-video routes' own encapsulated Fastify scope so the parser is not imposed on the rest of the BFF, and declared on the endpoint (bodyMedia) so the generated SDK sets the same header it will be parsed under. Base64 in a JSON field costs a third again on every biometric byte sent over a phone connection.

The offset is in the path, not a query parameter. It is part of what is being addressed — the chunk at this position — and a client that omits a query parameter gets a refusal it could have been given a URL for instead.

The digest is computed at completion by reading the stored object back. It used to be accumulated in a process-local Map, with createHash('sha256').digest('hex') — the digest of an empty file — as the fallback whenever that Map had no entry: a session resumed after a restart, or completed on a second worker. 182.C.26 binds an AUTHORIZATION to that value, so every such record would have bound to the same constant and any two subjects would have appeared to consent to the same bytes. Computing it from storage is process-independent and has a property the running hash never had: it hashes what a later reader will actually get, so a sink that lost a chunk produces a mismatch rather than a confident wrong answer.

The resume offset comes from the bytes, not from the row. receivedBytes is a projection and the two can disagree for one transaction's worth of time. A row that is AHEAD of the object — it committed and the byte write did not — makes a client resume past the end and leave a hole in the middle of a file whose length still comes out right, which nothing downstream can detect. So the sink is asked on every append and the row is repaired from it.

Abandoning destroys the bytes and returns a manifest. Not a 204: a bare success cannot be told apart from a success that removed nothing. An abandoned upload left staged is a copy of somebody's face that no record points at, and is therefore outside every retention rule and every erasure sweep.

Why GET /presets is not GET /presets plural rows#

It is the one endpoint here that reads nothing a tenant wrote. The presets are the product's own vocabulary — the same five for everybody — so the operation is get-preset-catalogue rather than list-presets: naming it a list would put it under assertListsArePaginated, correctly for rows, and paginating a fixed vocabulary tells a client the set grows with use, so it pages for a sixth preset that will never arrive.

It is still gated, on hv:projects:read. Having no store does not make it public: the catalogue names the capability classes this deployment intends to serve.

It carries no availability count, and that absence is the design. How many routes can serve a preset is a question about one request against the lane registry at one moment — it is what the pre-submission summary answers immediately before submitting, from lanes this endpoint never reads. A catalogue that stated it would be stating it from a registry it did not consult, and the plausible filler is the dangerous one: eligibleRoutes: 0 is a claim that no route can serve the preset, and it disables the control. The field is null on the wire and the surface renders null as NOT CHECKED HERE.

And three settings are served as deliberately absent, with reasons. Mood, gestures and whether an action finishes are not offered, because nothing can score a delivered take against them — JUDGEMENT_REASONS in human-video-direction-adherence.ts carries the measured reason for each (52 blendshapes come back from a face; mapping them onto "warm" rather than "amused" is not a measurement). They are listed rather than omitted because an absent control reads as an oversight, and the fix somebody reaches for is a free-text box — which is the one control shape 182.C.23.05 forbids. The rule generalises the item's prohibition: raw provider JSON is forbidden not because it is JSON but because nothing downstream knows what it asked for, and a named dropdown nothing can score is the same failure in nicer clothing.

Scopes, and why a real session is still refused#

Every operation is gated on an hv: scope — hv:assets:read, hv:projects:write, and so on — and a held scope now satisfies a required one exactly or by a wildcard inside the namespace: hv:assets:* and hv:* cover hv:assets:read. That matches what every other gate in this BFF already does (oneroster-route.ts, sso-route.ts, lms-route.ts and output-catalog.ts all accept admin:* beside the specific scope). Until 2026-09-12 the comparison here was exact, so hv:* — the obvious thing for an entitlement layer to mint, and the scope this document has named since it was written — was a string that granted nothing.

The wildcard stops at hv: on purpose. domain:* is issued to every signed-in customer by customer-auth-store.ts. Letting it cover hv:assets:read would hand all of them the tenant's identity packs, which is listing the faces a project was built from — the exact thing REQUIRED_SCOPE separates from project access, and a bare * would be every scope on the platform.

So a real customer session is still refused by all thirty-two endpoints, and that is the honest state rather than an oversight: nothing mints an hv: scope yet. Who may author directed human video is an entitlement decision, and 182.C.24.05 already says it belongs in the entitlement layer rather than in a directory name. This change only makes the answer expressible; measured in the web e2e on 2026-09-11, the Studio's regions render the 403 as a failed read with its reason, which is what a creator should see until that decision is made.

What is actually mounted, and what a 503 means#

The surface is registered unconditionally in apps/oshun/bff/src/server.ts and is fail-closed: every port behind it is nullable, and an operation whose store is unbound answers 503 hv.internal.store_unavailable rather than an empty list — an empty list would tell a tenant they have no work.

Three adapters are real. human_video_project_draft, so POST /projects, GET /projects/:id and PATCH /projects/:id serve where the table exists; the idempotency record is bound with it. And human_video_upload_session together with a byte sink — both, because a session table with nowhere to put the bytes would accept an open, answer a nextOffset, and drop every chunk into nothing, which a client cannot tell from an upload that worked. The sink is a staging directory named by OSHUN_HUMAN_VIDEO_UPLOAD_ROOT; there is deliberately no default, because an implicit one takes biometric bytes into a location nobody chose and nobody backs up. The boot line says which half is missing.

A resumable upload straight to object storage is a multipart upload — part numbers, per-part ETags, a 5 MiB floor on every part but the last — and browser chunk sizes do not obey that floor. Staging where an append at an offset is a real operation and handing the object over once is the shape that works; finalize is that seam and this deployment stops there.

And human_video_identity_pack together with a face detector — both, for the same shape of reason. evaluateIdentityPack REJECTS a reference with no face in it, correctly; so a detector that was absent and answered "no faces" would tell a creator their photograph has nobody in it. The detector is YuNet running on CPU through tools/human-video/face-geometry.py, configured by OSHUN_HUMAN_VIDEO_PYTHON, _FACE_GEOMETRY_SCRIPT and _YUNET_MODEL; every failure of the child process throws, and nothing degrades to an empty face list.

A face id has to survive a second run, and the type does not say so. DetectedFace.faceId is documented as "stable id within one detection run", which is not enough for the flow it serves: a two-face reference comes back awaiting-mapping, the creator answers which face is the cast member, the pack is POSTed again — and the detector runs again. An id that is the array index is stable only within a run, and YuNet orders by confidence, which can flip between two faces of near-equal score; the creator's answer would then name a face "the detector did not find". So the id is derived from WHERE the face is — the box, quantised to whole percent of the frame — and two faces that quantise to one id are refused rather than deduplicated, because dropping one loses a person from the image. GET /presets serves on every deployment, because it has no store to be unbound — so a 503 from THAT one means the service itself is failing rather than an adapter being absent, and the web client says so in different words from the ones it uses everywhere else. Everything else — upload sessions, identity packs, audio takes, jobs, candidates, reviews, releases, erasure and the project listing — has no adapter yet and says so at boot, in a line naming each one, so an operator meeting a 503 can tell a misconfigured database from an operation that was never meant to serve yet.

A deployment whose generated Prisma client predates those tables is treated exactly like no database: the delegate is checked for the methods it must have, and a missing one leaves the port null. Binding it anyway would produce Cannot read properties of undefined (reading 'findUnique') on the first request — a 500 that tells nobody anything.

Why there is a GET /reviews#

182.C.29.02 built the review queue and 182.C.29.04 built the rule for what a reviewer may hold, and neither was reachable: an operator could record a decision through POST /candidates/:id/approval and could not see what was waiting for one.

The listing carries the access decision per artifact, taken here rather than by the client: the take and the approved audio come with a URL, the biometric original comes back with the sentence explaining why not, and the URL never travels beside a refusal. The reviewer role is read from the caller's SCOPES — hv:reviews:senior, hv:reviews:trust-and-safety — because a role a client could name is a role a client could claim, and role is half of what unlocks the most sensitive artifact in the system. The other half is an open case about that subject, which the deployment supplies; a senior reviewer with no case still gets the refusal.

Why there is a GET /audio/:audioId#

approve-audio is a deciding operation: it requires an If-Match carrying the version being approved. Until this read existed, the only place that tag ever appeared was the response to POST /audio — so a creator who closed the tab between submitting and approving could not approve at all, and a surface reopened days later could not show what it was about to approve. In a flow whose normal state is waiting days on somebody else, that is not an edge case: a read is what makes the deciding operation reachable a second time.

The project draft, and the two things it deliberately does not do#

A project holds the creator's work between sessions. It has to: the flow waits for the subject to enrol and 182.C.23.01 establishes that may take days, which is longer than a browser tab lives.

It carries no consent state, no quality, and no approval. Those belong to resources the creator does not own, and a draft that stored them would let an autosave from an old tab write back a consent that has since been withdrawn — undoing a withdrawal through the one path nobody audits, because it is not a decision, it is typing. The draft holds identifiers and the creator's own choices (role, crop, which face, the words, the shots); everything else is read from the resource that owns it, every time.

And its concurrency control is a version in the body, not an If-Match. The precondition path is for deciding operations, where the ETag also carries the digest of the evidence being decided against; saving a draft decides nothing, and sending an autosave through that machinery would make it look like an approval. A save states the expectedVersion it was edited from. Omitting the field is refused rather than defaulted, because a client that forgets it would otherwise win every race silently.

What a withdrawal does to a draft#

A draft holds no image. It holds the subject's name, the identifiers of their references and the creator's crop over them — and a project that was never submitted has no job, so the job-based enumeration a withdrawal runs finds nothing for exactly the most sympathetic case there is: somebody withdrew before anything was generated, and the surface goes on offering them as cast.

So authoring-drafts is a copy location, and POST /authorizations/:id/withdrawal clears it:

  • the cast entry and their references go;
  • the recorded voice goes too, because a recorded or cloned voice is the subject's likeness in its own right (182.C.26.01);
  • the words stay, with the speaker cleared. They are the creator's, written by them and reusable with a different performer, and destroying them is a second wrong committed while righting the first;
  • the draft's version does not move, so the creator's next save is not reported as somebody else's conflict.

Two things this deliberately does not do. It never blocks the withdrawal: a deployment with no draft store bound, or a store that cannot answer, reports authoring-drafts as not reached in the manifest and the retraction goes ahead — refusing a retraction until an operator binds a store is the sentence the whole retraction path exists to avoid saying. And an unbound store is never read as "no drafts": absent is not none, and the manifest says whether any unsubmitted project still names the person is not known here.

A version mismatch answers 409 hv.validation.draft_conflict with the other side's draft in the body. A bare 409 leaves a client choosing between discarding the creator's typing and refetching; with both documents in hand it can keep the unsent edits and say which version it did not apply.

Two properties hold across the whole set rather than per handler, which is why the surface is a table and not thirty hand-written routes: every deciding operation requires a precondition, and every mutation accepts an idempotency key. assertSurfaceCoherent() checks both, and a new endpoint that forgets either fails that test rather than review.

There is no DELETE /jobs. Cancellation is its own verb, because 182.C.15.05 established that cancelling a submitted render recovers nothing — the money is spent — and a DELETE would suggest otherwise.

The shape of a call#

Schema-derived, not captured. Read these for the headers and the sequence, not as evidence that a server answered.

http
POST /v1/human-video/jobs
Authorization: Bearer $OSHUN_API_TOKEN
Idempotency-Key: 8f1c…            # any mutation; replaying it returns the first result
Content-Type: application/json

The sequence is fixed by the workflow rather than by taste (creator-workflow.md): upload sessions produce assets, an identity pack declares what they are, an authorization binds a subject to their digests, audio is registered and then approved, and only then can a job be submitted. Submitting before the authorization exists is not an ordering preference — it is hv.consent.missing, and it is terminal.

Lead with the refusals, because they are what you will hit first#

An API guide made of 200s teaches an integrator to write a client that only handles success. Every failure carries a stable code, an HTTP status, and a retry disposition that says whether retrying can ever help (libs/contracts/src/human-video/failure-codes.ts). The disposition is the contract; the message is not.

Code Status Retry What it means for your client
hv.consent.missing 403 after change No authorization binds this subject to these reference digests. Terminal; nothing to wait for.
hv.capability.no_eligible_lane 409 other lane No route can serve this request as written. Another may, and waiting will not change that.
hv.validation.unsupported_version 400 after change The contract version is not served. If your client did not change, we rolled back — see below.
hv.budget.rate_limited 429 later A window has to reset. Retry-After is present and honest.
hv.transport.submission_ambiguous 500 never The provider may have accepted it. Do not retry; reconcile with the idempotency key.

The statuses are worth reading twice. consent.missing is a 403, not a 400: the request is well-formed and you are not permitted to make it. no_eligible_lane is a 409, because nothing about the request is invalid — the platform has no route for it today, which is why the catalog blames platform rather than the caller. And submission_ambiguous is a 500 whose disposition is never: a retry could pay twice for a render the provider already accepted.

Two rules follow from that table and both are enforced rather than advised:

  • A Retry-After never appears on a failure waiting will not fix. A well-behaved client obeys one, sleeps, and sends the identical request again; attaching one to a settled refusal turns an answer into a polling loop (assertRetryAfterHonest).
  • unsupported_version blames the request, and after a rollback that is our fault, not yours. The catalog marks it blame: request, which is right when a client is behind and wrong when the server moved. A rollback-caused refusal discloses the rollback (182.C.38.06); if you see this code and your client has not changed, that is what happened.

What a measurements response is and is not#

GET /candidates/:candidateId/measurements returns what was measured, and what could not be. Those are different fields for a reason a client has to respect: a window nobody could score is not a window that passed. A client that treats "no findings" as "no problems" reproduces the exact failure the evaluator stack was built to prevent, and a shot of the back of somebody's head passes every check there is.

Read limitations.md before writing the code that consumes this endpoint.

What this guide will not do#

  1. Show a captured success. There is no server to capture one from, and a fabricated one would be worse than the gap.
  2. Ship a face. The smoke corpus has none, and a quickstart that needs one is a quickstart that ships biometric data.
  3. Quote a pass rate. Those are 182.C.30.03's and they wait on a corpus.