Append one retained video instruction
Generated from the checked-in source. Do not edit this reference by hand.
PUT /api/v1/organizations/{organization}/projects/{project}/generations/{session}/turns/{turn}
Actor-private within one workspace: installation credentials share the installation actor; each operator has an isolated owner. Current workspace Read is required for reads and Write for mutations; API-key inference credentials alone do not authorize these administrator routes. Saved-state reads and all writes never dispatch, refresh or replay inference. New writes use video category only; legacy Chat writes remain unchanged, while category=chat reads use a compatible projection. Revisions and sequences are decimal strings. Instructions follow existing Chat/intents JSON storage (not application-encrypted at rest); content expires after 30 days and is hidden immediately, then cleared by retention maintenance. Task identity and history remain. Archive does not cancel tasks or remove outputs/billing. At most 100 turns per session and 60 KiB prompt. Changed instruction creates a new client-generated turn UUID. Identical UUID/instruction retry is idempotent even after a lost response or content expiry; a changed instruction conflicts. No client execution state, output URL or arbitrary input object is accepted.
Operation: generationsSessionAppend.
Authentication
Section titled “Authentication”Use the credential and permission scope described above. Each object below is an alternative; schemes within one object are required together.
[ { "bearerAuth": [] }]HTTP request
Section titled “HTTP request”Set NIU_ORIGIN to your installation origin (without /v1). Replace path, query and header placeholders with the required values. Query examples use curl 7.87 or newer to encode values with --url-query. Use the credential scope described above; a bearer token must have the authority required by this operation.
curl --fail-with-body -X PUT "$NIU_ORIGIN/api/v1/organizations/{organization}/projects/{project}/generations/{session}/turns/{turn}" \ -H "Authorization: Bearer $NIU_BEARER_TOKEN" \ -H 'Content-Type: application/json' \ --data @request.jsonParameters
Section titled “Parameters”organization
Section titled “organization”Location: path. Required.
{ "type": "string", "format": "uuid"}project
Section titled “project”Location: path. Required.
{ "type": "string", "format": "uuid"}session
Section titled “session”Location: path. Required.
{ "type": "string", "format": "uuid"}Location: path. Required.
{ "type": "string", "format": "uuid"}Request body
Section titled “Request body”application/json
Section titled “application/json”Required.
{ "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "instruction": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "video" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 61440 } }, "required": [ "kind", "prompt" ] } }, "required": [ "expected_revision", "instruction" ]}Responses
Section titled “Responses”HTTP 200
Section titled “HTTP 200”Append one retained video instruction
Content type: application/json.
{ "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "category": { "type": "string", "const": "video" }, "title": { "type": "string" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "archived": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "turns": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "sequence": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "created_at": { "type": "string", "format": "date-time" }, "content_state": { "type": "string", "enum": [ "retained", "deleted", "expired" ] }, "instruction": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "video" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 61440 } }, "required": [ "kind", "prompt" ] }, { "type": "null" } ] }, "content_expires_at": { "type": "string", "format": "date-time" }, "task_id": { "type": [ "string", "null" ], "format": "uuid" }, "task": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "const": "video" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "submission_unknown", "queued", "running", "succeeded", "failed", "unknown", "reconciliation_required" ] }, "artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "task_id", "kind", "availability" ], "properties": { "task_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "video", "last_frame" ] }, "availability": { "type": "string", "enum": [ "available", "expired", "deleted", "unavailable" ] } } } } }, "required": [ "id", "kind", "model", "status", "artifacts" ] }, { "type": "null" } ] }, "intent": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "model", "content_state", "submission_state", "task_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "model": { "type": "string" }, "content_state": { "enum": [ "retained", "deleted", "expired" ] }, "submission_state": { "enum": [ "saved", "not_dispatched", "dispatched" ] }, "task_id": { "type": [ "string", "null" ], "format": "uuid" } }, "description": "Canonical retained model/controls/material draft is restored through the existing getVideoIntent contract; this safe reference contains no raw request. The turn instruction is the separately saved user instruction/review note, not asserted to be the historical submitted prompt." }, { "type": "null" } ] } }, "required": [ "id", "sequence", "created_at", "content_state", "instruction", "content_expires_at", "task_id", "task", "intent" ] } }, "owner": { "type": "string", "description": "Internal authenticated actor reference; never a product display label." } }, "required": [ "id", "workspace_id", "category", "title", "revision", "archived", "created_at", "updated_at", "turns", "owner" ] } }, "required": [ "data" ]}HTTP 400
Section titled “HTTP 400”Invalid request or cursor
HTTP 401
Section titled “HTTP 401”Invalid administrator session or unauthorized historical task
HTTP 403
Section titled “HTTP 403”Current workspace permission denied
HTTP 404
Section titled “HTTP 404”Actor-owned session is absent
HTTP 409
Section titled “HTTP 409”Stale revision, changed idempotent identity, archive or task association conflict
Behavior and supported scope
Section titled “Behavior and supported scope”Actor-private within one workspace: installation credentials share the installation actor; each operator has an isolated owner. Current workspace Read is required for reads and Write for mutations; API-key inference credentials alone do not authorize these administrator routes. Saved-state reads and all writes never dispatch, refresh or replay inference. New writes use video category only; legacy Chat writes remain unchanged, while category=chat reads use a compatible projection. Revisions and sequences are decimal strings. Instructions follow existing Chat/intents JSON storage (not application-encrypted at rest); content expires after 30 days and is hidden immediately, then cleared by retention maintenance. Task identity and history remain. Archive does not cancel tasks or remove outputs/billing. At most 100 turns per session and 60 KiB prompt. Changed instruction creates a new client-generated turn UUID. Identical UUID/instruction retry is idempotent even after a lost response or content expiry; a changed instruction conflicts. No client execution state, output URL or arbitrary input object is accepted.
Supported scope: implemented