{ "openapi": "3.1.0", "info": { "title": "Niu Gateway API", "version": "0.1.0", "description": "Model inference and management APIs for Niu. Browse the resource groups in the sidebar,\nsearch by operation or path, and expand the request and response schemas for exact fields.\n\n## Getting started\nUse the [HTTP quickstart](/help/guides/api-quickstart/) for your first model request,\nor the [JavaScript SDK guide](/help/guides/sdk-quickstart/) for typed clients.\n[Download the complete OpenAPI 3.1 document](/docs/openapi/public.json).\n\n## Authentication and scope\nInference uses a workspace API key. Management operations require the member session,\nplatform authority or Provider membership stated by that operation. These credentials\nare not interchangeable. See each operation's security scheme and access description.\nLegacy `project` path segments refer to workspaces; legacy `provider` paths refer to Providers.\n\n## Requests and responses\nSend the documented Content-Type and use the declared request schema. Response status codes,\nerror bodies and pagination fields are operation-specific. Follow the returned cursor rather\nthan assuming a list is complete. Streaming operations document their event format separately.\n\nMonetary amounts and large counters use the exact string representation in their schemas.\nPreserve currency and rate units; Provider purchase rates and customer charges are separate.\n\n## Writes and retries\nWhere an operation documents an idempotency key, retry an uncertain outcome with the same\nkey and identical input. Preserve expected revisions for configuration updates; reload after\na conflict. A timeout does not prove that a write or an upstream generation did not execute.\nRead the individual operation's retry and reconciliation behavior before resubmitting.\n" }, "servers": [ { "url": "/" } ], "paths": { "/api/v1/organizations/{organization}/billing/units/charges/{attempt}/refunds": { "post": { "operationId": "refundCustomerUnitCharge", "summary": "Restore original consumed Credits ranges", "description": "Platform administration required. Restores the next unrefunded prefix of an original resolved charge. Original source, definition and expiry remain unchanged; expired restored units stay expired. Purchase conversion and current tariffs are never used. Identical idempotent replay returns the original immutable receipt; conflicting replay and cumulative over-refund are rejected. Concurrent refunds serialize on the unit account. This does not execute an external payment refund, reverse a purchase, or release an unresolved inference hold. No monetary backing or procurement information is returned. Quantities are exact decimal strings.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attempt", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "credit_atoms", "reason", "idempotency_key" ], "properties": { "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Original immutable refund receipt", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "credit_atoms", "reason", "atoms_per_unit", "created_at", "sources" ], "properties": { "id": { "type": "string", "format": "uuid" }, "credit_atoms": { "type": "string" }, "reason": { "type": "string" }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "created_at": { "type": "string", "format": "date-time" }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "credit_atoms", "definition_revision", "name", "display_precision", "provenance", "expires_at_ms" ], "properties": { "credit_atoms": { "type": "string" }, "definition_revision": { "type": "string" }, "name": { "type": "string" }, "display_precision": { "type": "integer" }, "provenance": { "type": "string", "enum": [ "purchased", "promotional", "simulated" ] }, "expires_at_ms": { "type": [ "string", "null" ] } } } } } } } } } } }, "400": { "description": "Invalid exact quantity or reason" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "No Credits reservation in the specified organization" }, "409": { "description": "Unresolved or released charge, over-refund or conflicting retry" }, "422": { "description": "Malformed request" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/units/purchases/{order}/reversals": { "get": { "operationId": "previewCustomerUnitPurchaseReversal", "summary": "Preview a Credits purchase reversal and read committed reversal receipts", "description": "Platform administration required. Evaluates the unoccupied (unconsumed, unreserved and unreversed) ranges of an original Credits purchase lot and computes the exact processor-representable refund amount (whole minor units of 10000000 nanounits), the reversible atom prefix and any residual atoms or monetary backing that cannot be represented at processor precision without discarding value. Also returns all previously committed reversal receipts on the order. Consumed ranges require an explicit charge refund before they become reversible. Does not mutate state or execute an external payment refund.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "credit_atoms", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "description": "Optional target unoccupied atom prefix to evaluate; defaults to all currently available unoccupied atoms on the purchase lot." } ], "responses": { "200": { "description": "Purchase reversal preview and committed reversal history", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "order_id", "lot_id", "definition_revision", "name", "display_precision", "atoms_per_unit", "provenance", "payment_currency", "processor_minor_unit_nanos", "payment_nanos", "backing_nanos", "issued_atoms", "held_atoms", "charged_atoms", "restored_atoms", "reversed_atoms", "available_atoms", "available_payment_nanos", "available_backing_nanos", "requested_atoms", "reversible_atoms", "refund_payment_nanos", "refund_backing_nanos", "residual_credit_atoms", "residual_payment_nanos", "residual_backing_nanos", "ranges", "reversals" ], "properties": { "order_id": { "type": "string", "format": "uuid" }, "lot_id": { "type": "string", "format": "uuid" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "provenance": { "type": "string", "enum": [ "purchased", "simulated" ] }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "processor_minor_unit_nanos": { "type": "string", "const": "10000000" }, "payment_nanos": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "backing_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "issued_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "held_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "charged_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "restored_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "reversed_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "available_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "available_payment_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "available_backing_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "requested_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "reversible_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "refund_payment_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "refund_backing_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "residual_credit_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "residual_payment_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "residual_backing_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "ranges": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "first_atom", "end_atom", "credit_atoms", "payment_nanos", "backing_nanos" ], "properties": { "first_atom": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "end_atom": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "payment_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "backing_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } }, "reversals": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "order_id", "lot_id", "definition_revision", "name", "display_precision", "atoms_per_unit", "provenance", "payment_currency", "processor_minor_unit_nanos", "credit_atoms", "refund_payment_nanos", "refund_backing_nanos", "reason", "created_at", "ranges" ], "properties": { "id": { "type": "string", "format": "uuid" }, "order_id": { "type": "string", "format": "uuid" }, "lot_id": { "type": "string", "format": "uuid" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "provenance": { "type": "string", "enum": [ "purchased", "simulated" ] }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "processor_minor_unit_nanos": { "type": "string", "const": "10000000" }, "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "refund_payment_nanos": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "refund_backing_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "ranges": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "first_atom", "end_atom", "credit_atoms", "payment_nanos", "backing_nanos" ], "properties": { "first_atom": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "end_atom": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "payment_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "backing_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } } } } } } } } } }, "400": { "description": "Invalid query parameter" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "No settled Credits purchase lot for the specified organization and order" }, "409": { "description": "Requested atoms exceed currently available unoccupied purchase capacity" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "operationId": "reverseCustomerUnitPurchase", "summary": "Reverse unoccupied Credits purchase ranges at processor minor-unit precision", "description": "Platform administration required. Records an immutable reversal of unoccupied ranges belonging to an original Credits purchase lot. The requested atom quantity must map to a positive whole minor-unit payment refund (divisible by 10000000 nanounits) with zero discarded residual atoms or backing. Simulated purchases preserve zero cash backing and never enter verified cash funding reversals. Identical idempotent replay returns the original receipt even after later charges, reversals or rule changes; conflicting reuse returns 409. Recording a reversal does not execute an external payment-processor transfer.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "credit_atoms", "reason", "idempotency_key" ], "properties": { "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Immutable purchase reversal receipt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "order_id", "lot_id", "definition_revision", "name", "display_precision", "atoms_per_unit", "provenance", "payment_currency", "processor_minor_unit_nanos", "credit_atoms", "refund_payment_nanos", "refund_backing_nanos", "reason", "created_at", "ranges" ], "properties": { "id": { "type": "string", "format": "uuid" }, "order_id": { "type": "string", "format": "uuid" }, "lot_id": { "type": "string", "format": "uuid" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "provenance": { "type": "string", "enum": [ "purchased", "simulated" ] }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "processor_minor_unit_nanos": { "type": "string", "const": "10000000" }, "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "refund_payment_nanos": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "refund_backing_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "ranges": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "first_atom", "end_atom", "credit_atoms", "payment_nanos", "backing_nanos" ], "properties": { "first_atom": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "end_atom": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "payment_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "backing_nanos": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } } } } } } }, "400": { "description": "Invalid atom quantity, inexact processor minor-unit refund, residual atoms or invalid reason" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "No settled Credits purchase lot for the specified organization and order" }, "409": { "description": "Requested atoms exceed unoccupied capacity or idempotency key reused with different input" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/units": { "get": { "operationId": "getCustomerUnitBalance", "summary": "Read exact Credits quantities by original definition and provenance", "description": "Organization-wide billing owner/admin or installation read access required. One database statement reports original issuance, unresolved held ranges, gross charged ranges, original-range restorations, expired unheld remainder and available unexpired remainder. Expiry never releases an unresolved request hold or renews a restored lot. For each group, issued + restored = held + charged + expired + available. A balance is not proof that inference routes, tariffs or admission are configured. Historical unit definitions remain separate. No payment backing, procurement rates or financial margin enters this response. Quantities are exact decimal strings; an empty array means no issuance. Reads do not activate Credits or convert monetary balances.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current unit balance snapshot", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "billing_mode", "atoms_per_unit", "definition", "purchase_rules", "balances", "purchases", "recent_charges" ], "properties": { "billing_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "definition": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } }, "purchase_rules": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "revision", "definition_revision", "payment_currency", "numerator", "denominator" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "numerator": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } }, "balances": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "definition_revision", "name", "display_precision", "provenance", "issued_atoms", "held_atoms", "charged_atoms", "restored_atoms", "expired_atoms", "available_atoms" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "provenance": { "type": "string", "enum": [ "purchased", "promotional", "simulated" ] }, "issued_atoms": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative integer atoms. May exceed signed 64-bit range when aggregated across lots." }, "held_atoms": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative integer atoms. May exceed signed 64-bit range when aggregated across lots." }, "charged_atoms": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative integer atoms. May exceed signed 64-bit range when aggregated across lots." }, "restored_atoms": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative integer atoms. May exceed signed 64-bit range when aggregated across lots." }, "expired_atoms": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative integer atoms. May exceed signed 64-bit range when aggregated across lots." }, "available_atoms": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative integer atoms. May exceed signed 64-bit range when aggregated across lots." } } } }, "purchases": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "order_id", "created_at", "definition_revision", "name", "display_precision", "provenance", "payment_currency", "payment_nanos", "issued_atoms", "reversed_atoms", "available_atoms" ], "properties": { "order_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "provenance": { "type": "string", "enum": [ "purchased", "simulated" ] }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "payment_nanos": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "issued_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "reversed_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "available_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } }, "recent_charges": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "attempt_id", "reference", "charged_at", "model_alias", "definition_revision", "name", "display_precision", "charged_atoms", "restored_atoms", "refundable_atoms" ], "properties": { "attempt_id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "charged_at": { "type": "string", "format": "date-time" }, "model_alias": { "type": "string" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "charged_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "restored_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "refundable_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } } } } } } }, "401": { "description": "Authentication unavailable or revoked" }, "403": { "description": "Management read access required" }, "404": { "description": "Company absent or outside permitted billing scope" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/platform/units/tariffs": { "get": { "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Original immutable Credits text tariff", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "definition_revision", "model_alias", "price" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "price": { "type": "object", "additionalProperties": false, "required": [ "prompt_rate", "completion_rate", "request_fee_atoms", "minimum_charge_atoms", "context_tiers" ], "properties": { "prompt_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "completion_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "request_fee_atoms": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "minimum_charge_atoms": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "completion_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." } } } } } } } } } } } } }, "400": { "description": "Invalid model, exact quantity or context schedule" }, "401": { "description": "Authentication unavailable or revoked" }, "403": { "description": "Platform administration required" }, "404": { "description": "No explicitly published Credits text tariff" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "operationId": "getCustomerUnitTextTariff", "summary": "Read the latest explicit Credits text tariff for a model", "description": "Platform administration required. Reads the latest saved Credits consumption tariff, not a conversion from payment currency. It does not establish route readiness, enable billing mode or reserve capacity. Historical requests must retain their bound revision. Category null means ordinary pricing, not zero; each context tier is a complete schedule. No Provider procurement price is exposed.", "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Original immutable Credits text tariff", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "definition_revision", "model_alias", "price" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "price": { "type": "object", "additionalProperties": false, "required": [ "prompt_rate", "completion_rate", "request_fee_atoms", "minimum_charge_atoms", "context_tiers" ], "properties": { "prompt_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "completion_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "request_fee_atoms": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "minimum_charge_atoms": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "completion_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." } } } } } } } } } } } } }, "400": { "description": "Invalid model, exact quantity or context schedule" }, "401": { "description": "Authentication unavailable or revoked" }, "403": { "description": "Platform administration required" }, "409": { "description": "Stale installation/unit revision or conflicting idempotency input" }, "422": { "description": "Malformed request" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "operationId": "publishCustomerUnitTextTariff", "summary": "Publish a versioned Credits text consumption tariff", "description": "Platform administration required and rechecked transactionally for operators. Publish atom-denominated rates independently of purchase conversion and monetary tariffs. New publication requires the current unit definition and installation revision. Concurrent stale writes conflict. Equal idempotent retries return their original normalized publication, even after later price or unit changes; changed input conflicts. Rates and quantity thresholds use exact decimal strings; context thresholds are unique and normalized in ascending order. Nullable category rates use ordinary rates, never inherit another tier. Rates are per million tokens, rounded upward once after adding applicable exact token products. Add the fixed request fee, then apply the minimum charge. Explicit zero is valid; absence of a publication is unavailable. Publishing a tariff does not activate billing mode, issue Credits, convert money balances, admit requests or change prior request bindings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model_alias", "definition_revision", "expected_revision", "idempotency_key", "price" ], "properties": { "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$" }, "idempotency_key": { "type": "string", "format": "uuid" }, "price": { "type": "object", "additionalProperties": false, "required": [ "prompt_rate", "completion_rate", "request_fee_atoms", "minimum_charge_atoms", "context_tiers" ], "properties": { "prompt_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "completion_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "request_fee_atoms": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "minimum_charge_atoms": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "completion_rate": { "type": "string", "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,16}$", "description": "Exact integer Credits atoms, from 0 through 1000000000000000. Token rates are atoms per million tokens; fixed fees are atoms per completed request." } } } } } } } } } } }, "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/platform/units/media/tariffs": { "get": { "operationId": "listCustomerUnitMediaTariffs", "summary": "List latest explicit Credits media tariffs", "description": "Platform administration required. Reads the latest saved Credits media consumption tariff per dimension tuple (model_alias, channel, resolution, reference_video), not a conversion from payment currency. Optional model filter scopes to one model alias. No Provider procurement price is exposed.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Latest explicit Credits media tariffs by dimension tuple", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "revision", "definition_revision", "model_alias", "channel", "resolution", "reference_video", "meter", "price" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "channel": { "type": "string", "minLength": 1, "maxLength": 200 }, "resolution": { "type": "string", "minLength": 1, "maxLength": 200 }, "reference_video": { "type": "boolean" }, "meter": { "type": "string", "enum": [ "video_tokens" ] }, "price": { "type": "object", "additionalProperties": false, "required": [ "dimensions", "meter", "amount_atoms", "per_quantity", "minimum_quantity", "rounding" ], "properties": { "dimensions": { "type": "object", "additionalProperties": false, "required": [ "model", "channel", "resolution", "reference_video" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "channel": { "type": "string", "minLength": 1, "maxLength": 200 }, "resolution": { "type": "string", "minLength": 1, "maxLength": 200 }, "reference_video": { "type": "boolean" } } }, "meter": { "type": "string", "enum": [ "video_tokens" ] }, "amount_atoms": { "type": "string", "pattern": "^[0-9]{1,16}$" }, "per_quantity": { "$ref": "#/components/schemas/handler_operations_json_VideoBillingQuantity" }, "minimum_quantity": { "$ref": "#/components/schemas/handler_operations_json_VideoBillingQuantity" }, "rounding": { "type": "string", "enum": [ "Down", "Up", "HalfEven" ] } } } } } } } } } } }, "400": { "description": "Invalid model query" }, "401": { "description": "Authentication unavailable or revoked" }, "403": { "description": "Platform administration required" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "operationId": "publishCustomerUnitMediaTariff", "summary": "Publish a versioned Credits media consumption tariff", "description": "Platform administration required and rechecked transactionally for operators. Publish atom-denominated media consumption rates independently of purchase conversion and monetary media rate cards. New publication requires the current unit definition and installation revision. Concurrent stale writes conflict. Equal idempotent retries return their original normalized publication; changed input conflicts. Explicit zero is valid; absence of a publication is unavailable. Publishing a tariff does not activate billing mode, issue Credits, convert money balances, admit requests or change prior request bindings.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model_alias", "definition_revision", "expected_revision", "idempotency_key", "price" ], "properties": { "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$" }, "idempotency_key": { "type": "string", "format": "uuid" }, "price": { "type": "object", "additionalProperties": false, "required": [ "dimensions", "meter", "amount_atoms", "per_quantity", "minimum_quantity", "rounding" ], "properties": { "dimensions": { "type": "object", "additionalProperties": false, "required": [ "model", "channel", "resolution", "reference_video" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "channel": { "type": "string", "minLength": 1, "maxLength": 200 }, "resolution": { "type": "string", "minLength": 1, "maxLength": 200 }, "reference_video": { "type": "boolean" } } }, "meter": { "type": "string", "enum": [ "video_tokens" ] }, "amount_atoms": { "type": "string", "pattern": "^[0-9]{1,16}$" }, "per_quantity": { "$ref": "#/components/schemas/handler_operations_json_VideoBillingQuantity" }, "minimum_quantity": { "$ref": "#/components/schemas/handler_operations_json_VideoBillingQuantity" }, "rounding": { "type": "string", "enum": [ "Down", "Up", "HalfEven" ] } } } } } } } }, "responses": { "200": { "description": "Original immutable Credits media tariff", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "definition_revision", "model_alias", "channel", "resolution", "reference_video", "meter", "price" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "channel": { "type": "string", "minLength": 1, "maxLength": 200 }, "resolution": { "type": "string", "minLength": 1, "maxLength": 200 }, "reference_video": { "type": "boolean" }, "meter": { "type": "string", "enum": [ "video_tokens" ] }, "price": { "type": "object", "additionalProperties": false, "required": [ "dimensions", "meter", "amount_atoms", "per_quantity", "minimum_quantity", "rounding" ], "properties": { "dimensions": { "type": "object", "additionalProperties": false, "required": [ "model", "channel", "resolution", "reference_video" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "channel": { "type": "string", "minLength": 1, "maxLength": 200 }, "resolution": { "type": "string", "minLength": 1, "maxLength": 200 }, "reference_video": { "type": "boolean" } } }, "meter": { "type": "string", "enum": [ "video_tokens" ] }, "amount_atoms": { "type": "string", "pattern": "^[0-9]{1,16}$" }, "per_quantity": { "$ref": "#/components/schemas/handler_operations_json_VideoBillingQuantity" }, "minimum_quantity": { "$ref": "#/components/schemas/handler_operations_json_VideoBillingQuantity" }, "rounding": { "type": "string", "enum": [ "Down", "Up", "HalfEven" ] } } } } } } } } } }, "400": { "description": "Invalid model, dimensions, exact quantity or rounding mode" }, "401": { "description": "Authentication unavailable or revoked" }, "403": { "description": "Platform administration required" }, "409": { "description": "Stale installation/unit revision or conflicting idempotency input" }, "422": { "description": "Malformed request" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/units/grants": { "post": { "operationId": "issueCustomerUnitGrant", "summary": "Issue noncash Credits with an immutable provenance and expiry", "description": "Platform administration required. New issuance requires active Credits mode and the current unit definition. Promotional and simulated grants have zero monetary backing and create neither a payment receipt nor a monetary balance entry. Provide a customer-appropriate reason. Expiry is optional and must be in the future when new issuance commits. Reusing an idempotency key with the same semantic input returns the original grant without extending expiry, even after expiry or later unit publications. Different input conflicts. The returned amount is original issuance, not current spendable capacity. Purchased provenance is reserved for independently verified payments. Operator authority is rechecked under a transaction lock.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "definition_revision", "credit_atoms", "provenance", "reason", "idempotency_key" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive decimal integer, at most 9223372036854775807." }, "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive decimal integer, at most 9223372036854775807." }, "provenance": { "type": "string", "enum": [ "promotional", "simulated" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "expires_at_ms": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]{0,14}$", "description": "Optional future Unix milliseconds, at most 253402300799000. Null means no expiry." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Original immutable grant", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "definition_revision", "credit_atoms", "provenance", "reason", "expires_at_ms", "id", "name", "display_precision", "atoms_per_unit", "created_at" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive decimal integer, at most 9223372036854775807." }, "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive decimal integer, at most 9223372036854775807." }, "provenance": { "type": "string", "enum": [ "promotional", "simulated" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "expires_at_ms": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]{0,14}$", "description": "Optional future Unix milliseconds, at most 253402300799000. Null means no expiry." }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid unit, quantity, provenance, reason or expiry" }, "401": { "description": "Authentication unavailable or revoked" }, "403": { "description": "Platform administration required" }, "409": { "description": "Credits mode inactive, stale definition, missing company or conflicting idempotency input" }, "422": { "description": "Malformed request" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/quotes": { "post": { "operationId": "prepareCustomerUnitQuote", "summary": "Prepare an exact versioned Credits purchase quote", "description": "Platform administration required. A saved preview does not activate Credits, issue units, create a payment or prove processor amount eligibility. New quotes require the latest rule for its payment currency and latest definition. Inexact conversions and overflow are rejected. The quote pins amount, rule and unit definition for fifteen minutes. Identical idempotent retries retain the original quote and expiry even after rule changes or expiry; checkout must separately enforce validity. Reading historical quotes does not revalue them. No procurement data is returned.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Original immutable quote", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "rule_revision", "definition_revision", "payment_nanos", "credit_atoms", "numerator", "denominator", "id", "payment_currency", "name", "display_precision", "atoms_per_unit", "created_at", "expires_at" ], "properties": { "rule_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "payment_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "numerator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "id": { "type": "string", "format": "uuid" }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid amount, inexact conversion or overflow" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Quote not found in the requested organization" }, "409": { "description": "Stale rule, missing organization or conflicting idempotency input" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "rule_revision", "payment_nanos", "idempotency_key" ], "properties": { "rule_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "payment_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/quotes/{quote}": { "get": { "operationId": "getCustomerUnitQuote", "summary": "Read a saved Credits purchase quote", "description": "Platform administration required. A saved preview does not activate Credits, issue units, create a payment or prove processor amount eligibility. New quotes require the latest rule for its payment currency and latest definition. Inexact conversions and overflow are rejected. The quote pins amount, rule and unit definition for fifteen minutes. Identical idempotent retries retain the original quote and expiry even after rule changes or expiry; checkout must separately enforce validity. Reading historical quotes does not revalue them. No procurement data is returned.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "quote", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Original immutable quote", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "rule_revision", "definition_revision", "payment_nanos", "credit_atoms", "numerator", "denominator", "id", "payment_currency", "name", "display_precision", "atoms_per_unit", "created_at", "expires_at" ], "properties": { "rule_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "payment_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "numerator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Exact positive integer at most 9223372036854775807." }, "id": { "type": "string", "format": "uuid" }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid amount, inexact conversion or overflow" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Quote not found in the requested organization" }, "409": { "description": "Stale rule, missing organization or conflicting idempotency input" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/platform/units/mode/previews": { "post": { "operationId": "prepareCustomerUnitMode", "summary": "Save a billing-mode change preview", "description": "Platform administration required. Saves an immutable fifteen-minute compatibility snapshot without changing mode, balances or prices. Requires the current installation revision. A blocked or same-mode snapshot may be saved for review but cannot authorize publication. Identical idempotent replay returns the original snapshot and expiry even after later configuration changes; conflicting reuse is rejected. The actual mode publication must recheck current financial state. Quantities and revisions are exact strings.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Original durable result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "expected_revision", "source_mode", "target_mode", "snapshot", "created_at", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "source_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "target_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "snapshot": { "type": "object", "additionalProperties": false, "required": [ "revision", "billing_mode", "target_mode", "change_required", "blockers_empty", "observed_at", "blockers", "preserved_configuration" ], "properties": { "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "billing_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "target_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "change_required": { "type": "boolean" }, "blockers_empty": { "type": "boolean" }, "observed_at": { "type": "string", "format": "date-time" }, "blockers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "category", "record_count", "organization_count", "accounts_truncated", "accounts" ], "properties": { "category": { "type": "string" }, "record_count": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "organization_count": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "accounts_truncated": { "type": "boolean" }, "accounts": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "name", "record_count" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "record_count": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } } }, "preserved_configuration": { "type": "object", "additionalProperties": false, "required": [ "monetary_workspace_limits", "monetary_key_limits", "monetary_text_tariffs", "credits_text_tariffs", "monetary_retail_prices", "monetary_media_rate_history" ], "properties": { "monetary_workspace_limits": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_key_limits": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_text_tariffs": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "credits_text_tariffs": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_retail_prices": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_media_rate_history": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Platform administration required" }, "409": { "description": "Stale, incompatible, expired or conflicting intent; concurrent financial activity" }, "422": { "description": "Malformed request" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "target_mode", "expected_revision", "idempotency_key" ], "properties": { "target_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/platform/units/mode/previews/{preview}": { "get": { "operationId": "getSavedCustomerUnitModePreview", "summary": "Read an original saved billing-mode preview", "description": "Platform administration required. Returns the immutable original snapshot, including expired or subsequently incompatible previews. Reading does not renew expiry or authorize a switch. Current compatibility can differ; publication always rechecks it.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Original durable result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "expected_revision", "source_mode", "target_mode", "snapshot", "created_at", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "source_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "target_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "snapshot": { "type": "object", "additionalProperties": false, "required": [ "revision", "billing_mode", "target_mode", "change_required", "blockers_empty", "observed_at", "blockers", "preserved_configuration" ], "properties": { "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "billing_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "target_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "change_required": { "type": "boolean" }, "blockers_empty": { "type": "boolean" }, "observed_at": { "type": "string", "format": "date-time" }, "blockers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "category", "record_count", "organization_count", "accounts_truncated", "accounts" ], "properties": { "category": { "type": "string" }, "record_count": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "organization_count": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "accounts_truncated": { "type": "boolean" }, "accounts": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "name", "record_count" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "record_count": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } } }, "preserved_configuration": { "type": "object", "additionalProperties": false, "required": [ "monetary_workspace_limits", "monetary_key_limits", "monetary_text_tariffs", "credits_text_tariffs", "monetary_retail_prices", "monetary_media_rate_history" ], "properties": { "monetary_workspace_limits": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_key_limits": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_text_tariffs": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "credits_text_tariffs": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_retail_prices": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_media_rate_history": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Platform administration required" }, "404": { "description": "Saved preview not found" }, "409": { "description": "Stale, incompatible, expired or conflicting intent; concurrent financial activity" }, "422": { "description": "Malformed request" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "parameters": [ { "name": "preview", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/platform/units/mode": { "put": { "operationId": "publishCustomerUnitMode", "summary": "Publish a preview-confirmed installation billing mode", "description": "Platform administration required and rechecked under lock. Requires an unexpired originally compatible saved preview, its matching current revision and a distinct target mode. Rechecks customer obligations atomically while holding financial-table locks. Concurrent financial activity returns a retryable 409; re-read compatibility if state changed. Balances, prices, monetary limits and historical records are never converted. A successful publication creates an immutable change receipt and advances the installation revision once. Identical idempotent retry returns the original receipt even after subsequent mode changes; it does not reapply the old mode. Mode activation alone does not establish configured unit prices, compatible spending limits, model availability or media readiness. Existing monetary limits require explicit compatible configuration before affected Credits admission. New monetary grants/funding require currency mode and new unit issuance requires Credits mode.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Original durable result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "previous_mode", "billing_mode", "preview_id", "created_at" ], "properties": { "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "previous_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "billing_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "preview_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Platform administration required" }, "409": { "description": "Stale, incompatible, expired or conflicting intent; concurrent financial activity" }, "422": { "description": "Malformed request" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "preview_id", "expected_revision", "idempotency_key" ], "properties": { "preview_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "getCustomerUnitModePreview", "summary": "Preview installation billing-mode incompatibilities", "description": "Platform administration required. One current database statement reports incompatible customer balances, credit facilities, pending checkouts, unposted charges, unresolved customer requests and reservations, unapplied monetary grant intents and remaining unexpired Credits. Enabling Credits additionally requires a unit definition and matching platform-currency purchase rule. Each category includes complete counts and at most 100 affected company accounts, with explicit truncation. Original tariffs and monetary limits are retained and summarized, never converted. Existing monetary limits still require explicit compatible Credits configuration before those workspaces or keys can spend Credits. This is advisory only: blockers_empty does not activate billing mode, prove route readiness or authorize a later switch. Any mode publication must revalidate current state atomically. Reads never modify accounts or history. Same-mode previews still report current incompatibilities. No procurement amounts or credentials are included. Internal account identifiers are routing references, not display labels.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "currency", "credits" ] } } ], "responses": { "200": { "description": "Current advisory compatibility snapshot", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "billing_mode", "target_mode", "change_required", "blockers_empty", "observed_at", "blockers", "preserved_configuration" ], "properties": { "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "billing_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "target_mode": { "type": "string", "enum": [ "currency", "credits" ] }, "change_required": { "type": "boolean" }, "blockers_empty": { "type": "boolean" }, "observed_at": { "type": "string", "format": "date-time" }, "blockers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "category", "record_count", "organization_count", "accounts_truncated", "accounts" ], "properties": { "category": { "type": "string" }, "record_count": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "organization_count": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "accounts_truncated": { "type": "boolean" }, "accounts": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "name", "record_count" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "record_count": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } } }, "preserved_configuration": { "type": "object", "additionalProperties": false, "required": [ "monetary_workspace_limits", "monetary_key_limits", "monetary_text_tariffs", "credits_text_tariffs", "monetary_retail_prices", "monetary_media_rate_history" ], "properties": { "monetary_workspace_limits": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_key_limits": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_text_tariffs": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "credits_text_tariffs": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_retail_prices": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_media_rate_history": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } } } } } }, "400": { "description": "Invalid target or query" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/platform/units": { "get": { "operationId": "getCustomerUnitConfiguration", "summary": "Read branded-unit configuration", "description": "Requires platform administration. Configuration publication alone does not activate Credits billing, convert monetary balances, issue units or change consumption tariffs. Revisions and conversion components use exact decimal strings. Writes serialize on the installation configuration revision. Identical idempotent retries return the original publication even after later changes; different input with the same key conflicts. Purchase rules are reduced exact positive ratios and must reference the latest unit definition. Publishing a new definition requires explicit purchase-rule publication for new purchases; historical rules are retained. No procurement data is returned.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Saved configuration or original idempotent publication", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "definition", "purchase_rules", "text_tariffs", "billing_mode" ], "properties": { "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "definition": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } }, { "type": "null" } ] }, "purchase_rules": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "revision", "definition_revision", "payment_currency", "numerator", "denominator" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "numerator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." } } } }, "text_tariffs": { "type": "array", "items": { "type": "object" } }, "billing_mode": { "type": "string", "enum": [ "currency", "credits" ] } } } } } } } }, "400": { "description": "Invalid exact integer or configuration" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Stale revision or conflicting idempotency input" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/platform/units/definitions": { "post": { "operationId": "publishCustomerUnitDefinition", "summary": "Publish an immutable consumption-unit definition", "description": "Requires platform administration. Configuration publication alone does not activate Credits billing, convert monetary balances, issue units or change consumption tariffs. Revisions and conversion components use exact decimal strings. Writes serialize on the installation configuration revision. Identical idempotent retries return the original publication even after later changes; different input with the same key conflicts. Purchase rules are reduced exact positive ratios and must reference the latest unit definition. Publishing a new definition requires explicit purchase-rule publication for new purchases; historical rules are retained. No procurement data is returned.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Saved configuration or original idempotent publication", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } } } } } } }, "400": { "description": "Invalid exact integer or configuration" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Stale revision or conflicting idempotency input" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "display_precision", "expected_revision", "idempotency_key" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/platform/units/rules": { "post": { "operationId": "publishCustomerUnitPurchaseRule", "summary": "Publish an immutable Credits purchase rule", "description": "Requires platform administration. Configuration publication alone does not activate Credits billing, convert monetary balances, issue units or change consumption tariffs. Revisions and conversion components use exact decimal strings. Writes serialize on the installation configuration revision. Identical idempotent retries return the original publication even after later changes; different input with the same key conflicts. Purchase rules are reduced exact positive ratios and must reference the latest unit definition. Publishing a new definition requires explicit purchase-rule publication for new purchases; historical rules are retained. No procurement data is returned.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Saved configuration or original idempotent publication", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "definition_revision", "payment_currency", "numerator", "denominator" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "numerator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." } } } } } } } }, "400": { "description": "Invalid exact integer or configuration" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Stale revision or conflicting idempotency input" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "definition_revision", "payment_currency", "numerator", "denominator", "expected_revision", "idempotency_key" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "payment_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "numerator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Canonical nonnegative decimal integer, at most 9223372036854775807." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/providers/{provider}/integration": { "get": { "operationId": "getProviderIntegration", "summary": "Read provider integration identity", "description": "Platform administration required. Integration identity is independent of the inference adapter, endpoint, credential and prices. An unspecified default resolves to custom without claiming detection. A connection can override its Provider default; null restores inheritance. Writes require the current local revision (zero before the first save) and never overwrite a concurrent edit. This operation does not discover models, grant upstream management rights, publish rates or dispatch inference.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current integration selection and effective source", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "integration_type", "effective_type", "source", "revision" ], "properties": { "integration_type": { "type": [ "string", "null" ], "enum": [ "openrouter", "newapi", "litellm", "custom", null ] }, "effective_type": { "type": "string", "enum": [ "openrouter", "newapi", "litellm", "custom" ] }, "source": { "type": "string", "enum": [ "connection", "provider", "unspecified" ] }, "revision": { "type": "integer", "format": "int64", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid integration or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Resource not found" }, "409": { "description": "Configuration changed concurrently" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } }, "put": { "operationId": "setProviderIntegration", "summary": "Set provider integration identity", "description": "Platform administration required. Integration identity is independent of the inference adapter, endpoint, credential and prices. An unspecified default resolves to custom without claiming detection. A connection can override its Provider default; null restores inheritance. Writes require the current local revision (zero before the first save) and never overwrite a concurrent edit. This operation does not discover models, grant upstream management rights, publish rates or dispatch inference.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current integration selection and effective source", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "integration_type", "effective_type", "source", "revision" ], "properties": { "integration_type": { "type": [ "string", "null" ], "enum": [ "openrouter", "newapi", "litellm", "custom", null ] }, "effective_type": { "type": "string", "enum": [ "openrouter", "newapi", "litellm", "custom" ] }, "source": { "type": "string", "enum": [ "connection", "provider", "unspecified" ] }, "revision": { "type": "integer", "format": "int64", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid integration or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Resource not found" }, "409": { "description": "Configuration changed concurrently" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "integration_type", "expected_revision" ], "properties": { "integration_type": { "type": "string", "enum": [ "openrouter", "newapi", "litellm", "custom" ] }, "expected_revision": { "type": "integer", "format": "int64", "minimum": 0 } } } } } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/vendors/{id}/integration": { "get": { "operationId": "getVendorIntegration", "summary": "Read vendor integration identity", "description": "Platform administration required. Integration identity is independent of the inference adapter, endpoint, credential and prices. An unspecified default resolves to custom without claiming detection. A connection can override its Provider default; null restores inheritance. Writes require the current local revision (zero before the first save) and never overwrite a concurrent edit. This operation does not discover models, grant upstream management rights, publish rates or dispatch inference.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current integration selection and effective source", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "integration_type", "effective_type", "source", "revision" ], "properties": { "integration_type": { "type": [ "string", "null" ], "enum": [ "openrouter", "newapi", "litellm", "custom", null ] }, "effective_type": { "type": "string", "enum": [ "openrouter", "newapi", "litellm", "custom" ] }, "source": { "type": "string", "enum": [ "connection", "provider", "unspecified" ] }, "revision": { "type": "integer", "format": "int64", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid integration or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Resource not found" }, "409": { "description": "Configuration changed concurrently" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "put": { "operationId": "setVendorIntegration", "summary": "Set vendor integration identity", "description": "Platform administration required. Integration identity is independent of the inference adapter, endpoint, credential and prices. An unspecified default resolves to custom without claiming detection. A connection can override its Provider default; null restores inheritance. Writes require the current local revision (zero before the first save) and never overwrite a concurrent edit. This operation does not discover models, grant upstream management rights, publish rates or dispatch inference.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current integration selection and effective source", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "integration_type", "effective_type", "source", "revision" ], "properties": { "integration_type": { "type": [ "string", "null" ], "enum": [ "openrouter", "newapi", "litellm", "custom", null ] }, "effective_type": { "type": "string", "enum": [ "openrouter", "newapi", "litellm", "custom" ] }, "source": { "type": "string", "enum": [ "connection", "provider", "unspecified" ] }, "revision": { "type": "integer", "format": "int64", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid integration or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Resource not found" }, "409": { "description": "Configuration changed concurrently" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "integration_type", "expected_revision" ], "properties": { "integration_type": { "type": [ "string", "null" ], "enum": [ "openrouter", "newapi", "litellm", "custom", null ] }, "expected_revision": { "type": "integer", "format": "int64", "minimum": 0 } } } } } }, "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/platform/currency": { "put": { "operationId": "configurePlatformCurrency", "summary": "Configure the installation currency once", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "description": "Platform administration required. Repeating the same currency is safe; changing a configured currency returns 409. Historical records are not converted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency" ], "additionalProperties": false, "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } } } } } }, "responses": { "200": { "description": "Configured currency." }, "409": { "description": "Currency already configured with a different value." } }, "tags": [ "Branding and settings" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/v1/currency": { "get": { "operationId": "getPlatformCurrency", "summary": "Read the configured platform currency", "x-niu-implementation": "implemented", "description": "Returns the durable installation currency, or null until platform setup is completed. No credentials or financial balances are exposed.", "security": [], "responses": { "200": { "description": "data.currency is an ISO currency code, or null before setup." } }, "tags": [ "Branding and settings" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/api/v1/pools/{reference}": { "get": { "operationId": "getPool", "security": [ { "bearerAuth": [] } ], "summary": "Read an installation-managed model candidate pool", "parameters": [ { "in": "path", "name": "reference", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 267, "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Unpadded base64url encoding of the exact ASCII pool alias. This avoids encoded slashes and double decoding by proxies. The decoded alias must be 1–200 visible ASCII bytes." } ], "responses": { "200": { "description": "Current pool configuration", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_ModelRoutePool" } } } } } }, "400": { "description": "Invalid query or revision cursor; framework query errors may use plain text." }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Pool not found" } }, "x-niu-implementation": "implemented", "description": "Platform administration required: installation credentials or an explicitly authorized platform administrator. Ordinary company/workspace ownership does not grant this access. Reference is the canonical unpadded base64url encoding of the exact alias, not a percent-encoded alias; noncanonical or invalid references return 400.", "tags": [ "Model routing" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pools/{reference}/history": { "get": { "operationId": "listPoolHistory", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "reference", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 267, "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Unpadded base64url encoding of the exact ASCII pool alias. This avoids encoded slashes and double decoding by proxies. The decoded alias must be 1–200 visible ASCII bytes." }, { "in": "query", "name": "before_revision", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "At most 100 immutable revisions in descending order", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "allOf": [ { "$ref": "#/components/schemas/handler_operations_json_ModelRoutePool" }, { "type": "object", "required": [ "recorded_at" ], "properties": { "recorded_at": { "type": "string", "format": "date-time" } } } ] } } } } } } }, "400": { "description": "Invalid query or revision cursor; framework query errors may use plain text." }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Pool not found" } }, "x-niu-implementation": "implemented", "summary": "Read immutable model candidate pool revisions", "description": "Platform administration required: installation credentials or an explicitly authorized platform administrator. Ordinary company/workspace ownership does not grant this access. Reference is the canonical unpadded base64url encoding of the exact alias, not a percent-encoded alias; noncanonical or invalid references return 400.", "tags": [ "Model routing" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pools/{reference}/preview": { "post": { "operationId": "previewPool", "security": [ { "bearerAuth": [] } ], "summary": "Dry-run routing preview for a model route pool", "description": "Evaluates a pool's ordered routing rules, candidate eligibility, priority tiers, and normalized traffic weights for a simulated request without dispatching upstream traffic.", "parameters": [ { "in": "path", "name": "reference", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 267, "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Unpadded base64url encoding of the exact ASCII pool alias." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "protocol": { "type": "string", "enum": [ "chat", "responses", "messages" ] }, "streaming": { "type": "boolean" }, "vision": { "type": "boolean" }, "tools": { "type": "boolean" }, "structured_output": { "type": "boolean" }, "reasoning": { "type": "boolean" }, "input_tokens": { "type": [ "integer", "null" ], "minimum": 1 }, "output_tokens": { "type": [ "integer", "null" ], "minimum": 1 }, "candidates": { "type": "array", "items": { "type": "object" } }, "rules": { "type": "array", "items": { "type": "object" } }, "default_action": { "type": "string", "enum": [ "candidates", "reject" ] } } } } } }, "responses": { "200": { "description": "Dry-run routing preview result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid reference or preview parameters" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Pool not found" } }, "x-niu-implementation": "implemented", "tags": [ "Model routing" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/pools/{reference}/audit": { "get": { "operationId": "auditPool", "security": [ { "bearerAuth": [] } ], "summary": "Audit routing and billing strategy for a model route pool", "description": "Returns pricing readiness, margin safety, configured weight shares vs. observed traffic shares, completion rate, latency, customer revenue, upstream cost, and strategy findings for a model route pool.", "parameters": [ { "in": "path", "name": "reference", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 267, "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Unpadded base64url encoding of the exact ASCII pool alias." }, { "in": "query", "name": "days", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 } } ], "responses": { "200": { "description": "Pool routing and billing audit report", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid reference or window days" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Pool not found" } }, "x-niu-implementation": "implemented", "tags": [ "Model routing" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/workspaces/{workspace}/assets": { "get": { "operationId": "listWorkspaceAssetsByWorkspace", "summary": "List saved workspace materials", "description": "Member Read permission required. Scope is the selected workspace, not the creating actor. Lists active objects with metadata only, ordered by creation time then identity. limit defaults to 50 and must be 1–100. after must be an active asset in the same workspace and kind filter or conflicts. Follow next_cursor; separate pages are not a frozen snapshot. No ciphertext, actor identifier, Provider URI, procurement or dispatch approval is returned. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "image", "video", "audio" ] } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Scoped asset metadata; no private ciphertext or actor identifier.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "media_kind", "content_type", "content_sha256", "byte_length", "revision", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal routing reference; never display as a user label." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "media_kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "video/mp4", "video/webm", "audio/wav", "audio/mpeg", "audio/ogg" ] }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the immutable original bytes." }, "byte_length": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "source": { "type": [ "object", "null" ], "description": "Authorized original generation context. Null when absent or not visible to this actor; sharing a retained copy does not grant source access.", "additionalProperties": false, "required": [ "reference", "kind", "output", "model", "created_at" ], "properties": { "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" }, "kind": { "const": "video" }, "output": { "enum": [ "video", "last_frame" ] }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/assets", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "post": { "operationId": "uploadWorkspaceAssetByWorkspace", "summary": "Save a workspace material", "description": "Member Write permission required. Raw binary body with exact supported Content-Type and required name query; no multipart or base64 envelope. Authentication and a bounded upload slot precede body collection. Original bytes are immutable, encrypted with workspace/asset identity binding, limited to 8 MiB each and 256 MiB/256 active objects per workspace. Images undergo bounded pixel decoding; audio/video undergo local frame/container structural validation. This is not content-inspection approval, Provider upload, licensing evidence or inference authorization. Repeated uploads create distinct objects; uncertain clients should reconcile the library before repeating. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Trimmed nonblank name; at most 200 UTF-8 bytes after trimming; no control characters." } ], "responses": { "201": { "description": "Scoped asset metadata; no private ciphertext or actor identifier.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "media_kind", "content_type", "content_sha256", "byte_length", "revision", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal routing reference; never display as a user label." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "media_kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "video/mp4", "video/webm", "audio/wav", "audio/mpeg", "audio/ogg" ] }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the immutable original bytes." }, "byte_length": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "source": { "type": [ "object", "null" ], "description": "Authorized original generation context. Null when absent or not visible to this actor; sharing a retained copy does not grant source access.", "additionalProperties": false, "required": [ "reference", "kind", "output", "model", "created_at" ], "properties": { "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" }, "kind": { "const": "video" }, "output": { "enum": [ "video", "last_frame" ] }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "413": { "description": "Raw body exceeds 8 MiB." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "image/jpeg": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "image/webp": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "video/mp4": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "video/webm": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "audio/wav": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "audio/ogg": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/assets", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/assets/{asset}": { "get": { "operationId": "getWorkspaceAssetByWorkspace", "summary": "Read workspace material metadata", "description": "Member Read permission required. Returns one active scoped asset without ciphertext or internal actor information. Unknown, deleted or foreign-workspace asset is 404. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scoped asset metadata; no private ciphertext or actor identifier.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "media_kind", "content_type", "content_sha256", "byte_length", "revision", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal routing reference; never display as a user label." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "media_kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "video/mp4", "video/webm", "audio/wav", "audio/mpeg", "audio/ogg" ] }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the immutable original bytes." }, "byte_length": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "source": { "type": [ "object", "null" ], "description": "Authorized original generation context. Null when absent or not visible to this actor; sharing a retained copy does not grant source access.", "additionalProperties": false, "required": [ "reference", "kind", "output", "model", "created_at" ], "properties": { "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" }, "kind": { "const": "video" }, "output": { "enum": [ "video", "last_frame" ] }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/assets/{asset}", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "patch": { "operationId": "renameWorkspaceAssetByWorkspace", "summary": "Rename a saved workspace material", "description": "Member Write permission required. Requires the exact current revision as a canonical positive decimal string. Renaming changes display metadata and increments revision, never bytes, content hash or Provider authorization. Stale revision returns 409. A missing scoped asset is 404; a concurrent deletion may conflict. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scoped asset metadata; no private ciphertext or actor identifier.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "media_kind", "content_type", "content_sha256", "byte_length", "revision", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal routing reference; never display as a user label." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "media_kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "video/mp4", "video/webm", "audio/wav", "audio/mpeg", "audio/ogg" ] }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the immutable original bytes." }, "byte_length": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "source": { "type": [ "object", "null" ], "description": "Authorized original generation context. Null when absent or not visible to this actor; sharing a retained copy does not grant source access.", "additionalProperties": false, "required": [ "reference", "kind", "output", "model", "created_at" ], "properties": { "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" }, "kind": { "const": "video" }, "output": { "enum": [ "video", "last_frame" ] }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "expected_revision" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." } } } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/assets/{asset}", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "delete": { "operationId": "deleteWorkspaceAssetByWorkspace", "summary": "Delete a saved workspace material", "description": "Member Write permission required. Optional expected_revision protects against deleting a newly renamed active object. Deletion marks metadata inactive, erases ciphertext and releases quota atomically. Repeat deletion of the same scoped deleted asset is idempotent 204. Unknown or foreign asset is 404. No upstream asset or existing inference job is deleted. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_revision", "in": "query", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "description": "Optional canonical positive i64 revision of the active asset." } ], "responses": { "204": { "description": "Scoped deletion committed or already deleted; no response body." }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/assets/{asset}", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/assets/{asset}/content": { "get": { "operationId": "downloadWorkspaceAssetByWorkspace", "summary": "Download saved workspace material bytes", "description": "Member Read permission required. Authenticates encrypted identity binding and checks byte length and SHA-256 before returning the original bytes. Safe fixed attachment filename, exact supported Content-Type, Cache-Control:no-store and X-Content-Type-Options:nosniff. Unknown/deleted/foreign asset is 404; decryption/integrity failure is a safe unavailable response. Does not make content approved for Provider processing. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Exact retained bytes with no-store/nosniff and safe attachment disposition.", "content": { "image/png": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "image/jpeg": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "image/webp": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "video/mp4": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "video/webm": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "audio/wav": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "audio/ogg": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/assets/{asset}/content", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/video/intents": { "get": { "operationId": "listVideoSubmissionIntentsByWorkspace", "summary": "List the current actor video intent index", "description": "Actor-owned workspace records: installation authority shares one installation actor, while operator actors are isolated even within the same workspace. Current workspace permission applies. Request content is retained for 30 days from creation or until deletion; expiry is unreadable immediately and background maintenance clears retained content. Identity tombstones remain. Deletion does not cancel an already accepted concurrent submission, erase its job or refund charges. Newest-first creation order with UUID tie-breaker. The index contains only intent identity, revision, expiry and retention state; it intentionally exposes no request, model or key content. Index access remains available for deleting retained content after key revocation. Read each intent separately under current key authorization. A cursor must belong to this actor and workspace. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "List the current actor video intent index", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_before" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/handler_operations_json_VideoIntentIndexItem" } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential or no authorized current key in the original lineage." }, "403": { "description": "Workspace permission or current source policy denied." }, "404": { "description": "Intent is not owned by this actor and workspace, or selected model is inaccessible." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/video/intents", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/video/intents/{intent}": { "put": { "operationId": "saveVideoSubmissionIntentByWorkspace", "summary": "Save an immutable video submission intent with typed Niu references", "description": "Actor-owned workspace records: installation authority shares one installation actor, while operator actors are isolated even within the same workspace. Current workspace permission applies. Request content is retained for 30 days from creation or until deletion; expiry is unreadable immediately and background maintenance clears retained content. Identity tombstones remain. Deletion does not cancel an already accepted concurrent submission, erase its job or refund charges. Requires workspace write permission and an active selected key with model access and allowed source. A fresh client-generated intent UUID binds the exact request, original key and funding mode. Identical retries return the same record; changed input or key under that UUID conflicts. No attempt, upstream call or reservation is created. The internal idempotency identity is server-generated and is never exposed; use the submit operation rather than legacy job creation. Saving reference drafts reads only scoped material metadata and schema constraints. It never resolves private Provider URIs, reads upload bytes, queries upstream, reserves funds, inspects media or grants Active readiness. Original Niu references and explicit consent remain in the canonical request digest; all runtime bindings are revalidated at submit. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Save an immutable video submission intent with typed Niu references", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_VideoSubmissionIntent" } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential or no authorized current key in the original lineage." }, "403": { "description": "Workspace permission or current source policy denied." }, "404": { "description": "Intent is not owned by this actor and workspace, or selected model is inaccessible." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "413": { "description": "Request envelope exceeds 64 KiB." }, "501": { "description": "Unsupported video capability or saved-reference form." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "key_id", "request" ], "properties": { "key_id": { "type": "string", "format": "uuid" }, "request": { "$ref": "#/components/schemas/handler_operations_json_VideoIntentRequest" } } } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/video/intents/{intent}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "get": { "operationId": "getVideoSubmissionIntentByWorkspace", "summary": "Restore a saved video intent and its historical job", "description": "Accepts an internal UUID alias or permanent input reference. Both preserve existing workspace and actor authorization; mutation endpoints still require internal UUIDs. Current workspace Read permission and the original actor-owned intent are required. Restores saved request and job evidence independently of current inference key lifetime, model grants, source policy or Provider configuration. Original and available rotation-lineage key IDs are context only, never authority to submit, estimate or query upstream. Revoked/expired keys and lost model grants do not hide retained private input; deletion and original/bound-turn expiry still hide content immediately. Unknown submission evidence never grants permission to dispatch again. No upstream request, inference, reservation, settlement or write occurs. Storage failures remain errors. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "description": "Internal UUID alias or permanent input reference" } } ], "responses": { "200": { "description": "Restore a video intent and resolve its original job", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_VideoSubmissionIntent" } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential." }, "403": { "description": "Current workspace Read permission denied." }, "404": { "description": "Intent is not owned by this actor and workspace." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/video/intents/{intent}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "delete": { "operationId": "deleteVideoSubmissionIntentByWorkspace", "summary": "Erase saved intent content without cancelling its job", "description": "Actor-owned workspace records: installation authority shares one installation actor, while operator actors are isolated even within the same workspace. Current workspace permission applies. Request content is retained for 30 days from creation or until deletion; expiry is unreadable immediately and background maintenance clears retained content. Identity tombstones remain. Deletion does not cancel an already accepted concurrent submission, erase its job or refund charges. Requires write permission and the expected revision. Replaying the same successful deletion is idempotent. Does not require an active selected key. Deleted identities cannot be saved or submitted again. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erase saved intent content without cancelling its job", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "deleted" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "deleted": { "const": true } } } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential or no authorized current key in the original lineage." }, "403": { "description": "Workspace permission or current source policy denied." }, "404": { "description": "Intent is not owned by this actor and workspace, or selected model is inaccessible." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/video/intents/{intent}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/video/intents/{intent}/submit": { "post": { "operationId": "submitVideoSubmissionIntentByWorkspace", "summary": "Explicitly submit or replay an immutable saved video intent", "description": "Actor-owned workspace records: installation authority shares one installation actor, while operator actors are isolated even within the same workspace. Current workspace permission applies. Request content is retained for 30 days from creation or until deletion; expiry is unreadable immediately and background maintenance clears retained content. Identity tombstones remain. Deletion does not cancel an already accepted concurrent submission, erase its job or refund charges. Requires write permission, matching retained revision and current key/model/source authorization. Uses only the saved request and original rotation lineage. Rechecks configured video admission and rejects a changed owner-funded/customer funding mode before a new dispatch. Concurrent and restarted calls use one original submission identity. Interrupted original preparation is read back, never assumed safe to dispatch again. HTTP 202 can represent unresolved submission and is not a completed generation or settled charge. Fresh submissions use the same 24-hour inspected-request and Niu creation-response Logs capture as direct creation, with x-niu-log-payloads: false opt-out. Capture uses the saved inspected video request, not this revision-only submit body. Replay does not create or restore capture. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-niu-log-payloads", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" }, "description": "Capture the inspected Niu request and Niu creation response in bounded 24-hour Logs storage. False opts out; repeated or invalid values are rejected. Replay never creates a new capture." } ], "responses": { "202": { "description": "Explicitly submit or replay an immutable saved video intent", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "x-niu-attempt-id": { "description": "Present on fresh creation; identifies the attempt for scoped Logs. Replay does not generate a new capture.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "model", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "video.job" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "submission_unknown", "queued", "running", "succeeded", "failed", "unknown", "reconciliation_required" ] } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential or no authorized current key in the original lineage." }, "402": { "description": "Insufficient funds or spending allowance before dispatch." }, "403": { "description": "Workspace permission or current source policy denied." }, "404": { "description": "Intent is not owned by this actor and workspace, or selected model is inaccessible." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "429": { "description": "Current rate or concurrency policy denied admission." }, "501": { "description": "Unsupported video capability or saved-reference form." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/video/intents/{intent}/submit", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/video/draft": { "get": { "operationId": "getVideoComposerDraftByWorkspace", "x-niu-implementation": "implemented", "summary": "Read a mutable personal Video composer", "description": "One mutable actor-private Video composer per workspace. Operators are isolated; installation credentials share the installation actor. Read requires workspace Read permission. Absent state returns null payload and revision zero. Retention is 30 days after the last confirmed edit; expired content is hidden immediately and background maintenance erases it. Reads expose the expiry tombstone revision before maintenance. Saved key/model/reference identities are context only, including unavailable historical resources; they confer no current access or readiness. No inference, Provider calls, reservation, media reads or inspection occur. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Actor-private composer state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VideoComposerDraftResponse" } } } }, "401": { "description": "Missing or invalid administration/member authentication." }, "403": { "description": "Insufficient workspace permission or scope." }, "404": { "description": "Resource missing or outside authorized workspace/owner scope." }, "500": { "description": "Internal storage failure." }, "503": { "description": "Storage unavailable." } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/video/draft", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "saveVideoComposerDraftByWorkspace", "x-niu-implementation": "implemented", "summary": "Save or clear a mutable personal Video composer", "description": "One mutable actor-private Video composer per workspace. Operators are isolated; installation credentials share the installation actor. Read requires workspace Read permission. Absent state returns null payload and revision zero. Retention is 30 days after the last confirmed edit; expired content is hidden immediately and background maintenance erases it. Reads expose the expiry tombstone revision before maintenance. Saved key/model/reference identities are context only, including unavailable historical resources; they confer no current access or readiness. No inference, Provider calls, reservation, media reads or inspection occur. Write requires workspace Write permission and allowed browser Origin. Typed bounded partial composition may omit model/key/session and required model controls. Only the nine existing non-URL VideoSchema scalar control names are accepted; integer edits may remain strings. References use exact provider_asset/workspace_asset shapes, canonical nonnil Niu IDs and explicit workspace processing consent. No raw URL, inline media, short-lived ingestion, credential or billing fields are accepted. Key/reference metadata must belong to the workspace; session context must belong to the actor. Saving does not require an active historical key or grant action access. Full current schema, key/model eligibility, reference binding, consent and inspection remain explicit estimate/submission requirements. Null or omitted payload clears content while retaining the CAS revision. Stale revisions, including revisions predating expiry or clear, return 409. Workspace deletion refuses retained drafts; cleared/expired tombstones alone do not prevent empty-workspace deletion. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Actor-private composer state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VideoComposerDraftResponse" } } } }, "400": { "description": "Malformed or unknown fields, invalid bounds, control type, reference role, consent or canonical ID." }, "401": { "description": "Missing or invalid administration/member authentication." }, "403": { "description": "Insufficient permission, cross-workspace key/reference, unavailable actor session, or missing/disallowed browser Origin." }, "404": { "description": "Resource missing or outside authorized workspace/owner scope." }, "409": { "description": "Invalid or stale revision; no overwrite." }, "413": { "description": "Body exceeds 64 KiB." }, "500": { "description": "Internal storage failure." }, "503": { "description": "Storage unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VideoComposerDraftUpdate" } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/video/draft", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/chats/draft": { "get": { "operationId": "getChatDraftByWorkspace", "x-niu-implementation": "implemented", "summary": "Read the persistent personal Chat draft", "description": "The draft is isolated by authenticated personal owner and workspace. Operators have distinct drafts; installation credentials share the installation owner. Read authorization and workspace scope are required. An absent draft returns null payload and revision zero. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved personal draft state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ChatDraftResponse" } } } }, "401": { "description": "Missing or invalid administration/member authentication." }, "403": { "description": "Insufficient permission or workspace scope." }, "404": { "description": "Resource missing or outside authorized workspace/owner scope." }, "500": { "description": "Internal storage failure." }, "503": { "description": "Storage unavailable." } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/chats/draft", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "saveChatDraftByWorkspace", "x-niu-implementation": "implemented", "summary": "Save or clear the personal Chat draft with an expected revision", "description": "Write authorization and workspace scope are required. Browser-member requests require an allowed Origin when password authentication is configured; other requests also undergo Origin validation. Strict typed JSON rejects unknown fields. A referenced conversation must belong to the same owner and workspace. Saving does not call a model. The 24 MiB route body bound applies. Compare-and-swap prevents stale tabs from overwriting a newer draft; clearing retains and advances the revision. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved personal draft state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ChatDraftResponse" } } } }, "400": { "description": "Malformed or unknown JSON fields, invalid payload limits, or unavailable owner-scoped conversation." }, "401": { "description": "Missing or invalid administration/member authentication." }, "403": { "description": "Insufficient permission or workspace scope. Missing or disallowed browser Origin also refuses the write." }, "404": { "description": "Resource missing or outside authorized workspace/owner scope." }, "409": { "description": "Negative, stale or unavailable expected revision; no draft overwrite." }, "500": { "description": "Internal storage failure." }, "503": { "description": "Storage unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ChatDraftUpdate" } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/chats/draft", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/chats": { "get": { "operationId": "listChatSessionsByWorkspace", "x-niu-implementation": "implemented", "summary": "List personal saved Chat history or one continuation page", "description": "Without limit or after, retain the latest-100 compatibility response. Either paging parameter selects a bounded page, default 50, ordered by updated time and ID descending within the authenticated owner, workspace and archive state. Session payload and customer-charge hydration share a read-only snapshot with 250 ms lock and 2 s statement limits. A changed, deleted, foreign-owner or different-archive cursor returns 409; pages are live views, not a frozen cross-request snapshot. Before loading saved bodies, paging also limits the sum of saved JSON text bytes to 32 MiB and may return fewer rows than limit; follow next_cursor. Customer-charge hydration can increase wire size. Legacy latest-100 calls over that saved-payload budget return 413 rather than truncated success. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "archived", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "description": "Opaque next_cursor from the previous page; do not interpret or display it.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}:[0-9a-fA-F]{64}$" } } ], "responses": { "200": { "description": "Compatibility data array or paged data array with nullable next_cursor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed cursor or invalid page size." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." }, "404": { "description": "Resource missing or outside authorized workspace/owner scope." }, "409": { "description": "Cursor no longer matches an accessible session in this archive." }, "413": { "description": "Saved Chat history exceeds one-response capacity; use paging or individual conversation export." }, "503": { "description": "Storage unavailable or read wait exceeded; no empty-success fallback." } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/chats", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/chats/{id}/archive": { "put": { "operationId": "setChatSessionArchivedByWorkspace", "summary": "Archive or restore the authenticated owner's Chat session", "description": "Updates backend-owned archive state without changing content or conversation ordering. Autosaves preserve archive state. Repeating the same value is idempotent. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "archived" ], "properties": { "archived": { "type": "boolean" } } } } } }, "responses": { "204": { "description": "Archive state saved." }, "400": { "description": "Invalid input." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace write access required." }, "404": { "description": "No session in the caller's owner and workspace scope." } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/chats/{id}/archive", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/chats/{id}/export": { "get": { "operationId": "exportChatSessionByWorkspace", "summary": "Export one owned saved conversation", "description": "Requires workspace read access and the authenticated conversation owner. Reads durable content directly, including sessions outside the latest-100 list. Excludes internal identifiers, settings, diagnostic errors and accounting. Conversation and attachment content is deliberately included and may contain user-supplied sensitive text. Legacy single-turn sessions become one turn. Does not export request Logs or billing evidence. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Portable conversation JSON", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "format", "version", "turns" ], "properties": { "format": { "const": "niu-chat" }, "version": { "const": 1 }, "title": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "turns": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "prompt", "results" ], "properties": { "prompt": { "type": "string" }, "results": { "type": "array", "maxItems": 4, "items": { "type": "object", "additionalProperties": false, "required": [ "model", "content", "phase" ], "properties": { "model": { "type": "string" }, "content": { "type": "string" }, "finishReason": { "type": [ "string", "null" ], "maxLength": 128, "description": "Model completion reason, when supplied. Transport completion alone does not establish a complete answer." }, "phase": { "type": "string", "enum": [ "connecting", "streaming", "complete", "failed", "cancelled" ] } } } }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "type", "content" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" } } } } } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace read access required" }, "404": { "description": "No saved conversation for this workspace and owner" }, "503": { "description": "Durable storage unavailable" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/chats/{id}/export", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/chats/{id}": { "get": { "operationId": "getChatSessionByWorkspace", "x-niu-implementation": "implemented", "summary": "Read one complete owned saved Chat conversation", "description": "Requires workspace read permission and the authenticated personal owner. Returns the full saved conversation and archive state without scanning history pages, including sessions beyond the recent-100 list. Selection and authoritative customer-charge hydration share a bounded read-only snapshot (250 ms lock and 2 s statement limits); preceding authorization and pool acquisition are separate. Saved browser accounting is ignored. Saved JSON above 32 MiB returns 413; no content is truncated. Archived sessions remain directly readable. Accepts an internal UUID alias or permanent chat reference; both require the same workspace and personal-owner authorization. The returned data includes its server-assigned reference. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Internal UUID alias or permanent chat reference" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Complete owned conversation and separate archive state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "archived", "revision", "guardedWrites" ], "properties": { "data": { "type": "object" }, "archived": { "type": "boolean" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Opaque positive decimal write revision. Pass as expectedRevision for guarded saves." }, "guardedWrites": { "type": "boolean", "description": "True after guarded content save. Version-free saves are then rejected; this mode cannot be disabled by a content save." } } } } }, "headers": { "Cache-Control": { "description": "Complete personal conversation responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read permission required." }, "404": { "description": "No conversation for this personal owner and workspace." }, "413": { "description": "Saved JSON exceeds one-response capacity; use individual content export." }, "503": { "description": "Durable storage unavailable or read wait exceeded." } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/chats/{id}", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "delete": { "operationId": "deleteChatSessionByWorkspace", "summary": "Delete an owned Chat session in a workspace", "description": "Requires write access to the workspace. Deletion is scoped to the authenticated owner and workspace. Missing or already deleted sessions return the same result without disclosing another owner's history. Does not delete request accounting or billing records. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Session deleted or absent." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace write access required." }, "404": { "description": "Resource missing or outside authorized workspace/owner scope." } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/chats/{id}", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "put": { "operationId": "saveChatSessionByWorkspace", "summary": "Save an owned Chat session in a workspace", "description": "Requires workspace write access. Stores conversation content separately from accounting. Only supported top-level and nested fields are retained. Client-supplied accounting fields are discarded. Numeric timestamps, durations and token counts must be nonnegative JavaScript-safe integers; token counts may be null. Settings and attachment shapes are validated. This endpoint does not establish authoritative request charges or detect secrets embedded in conversation text. Omit expectedRevision for a compatibility write only while the owned record has not enabled guarded writes. Explicit null creates only if no owned row exists; a canonical positive decimal revision updates only that exact owned version. Stale, missing or duplicate-create guarded writes return 409 without replacing content. Revisions are global sequence values, not timestamps, and are never reused by API delete/recreate. Guarded success includes a decimal revision; direct GET provides it. A successful guarded creation/update permanently enables guarded writes on that owned row. Compatibility saves thereafter return 409; there is no content-write downgrade. A content-free guard identity survives deletion, so legacy autosaves cannot resurrect a protected reference; explicit null guarded creation may recreate it. Untouched legacy rows retain compatibility behavior until guarded save. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt", "results", "createdAt" ], "properties": { "prompt": { "type": "string" }, "title": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "turns": { "type": "array", "maxItems": 100, "description": "Ordered conversation turns. Each retains its prompt and up to four model responses, validated with the same result fields as the current turn. Unknown turn/result fields are stripped. Optional for legacy single-turn sessions.", "items": { "type": "object", "required": [ "prompt", "results" ], "properties": { "prompt": { "type": "string" }, "results": { "type": "array", "maxItems": 4, "items": { "type": "object" } }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "name", "type", "content" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" } } } } } } }, "results": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "model", "content", "elapsedMs", "phase" ], "properties": { "model": { "type": "string" }, "content": { "type": "string" }, "elapsedMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "finishReason": { "type": [ "string", "null" ], "maxLength": 128, "description": "Model completion reason, when supplied. Transport completion alone does not establish a complete answer." }, "phase": { "type": "string", "enum": [ "connecting", "streaming", "complete", "failed", "cancelled" ] }, "promptTokens": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "completionTokens": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "totalTokens": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 } } } }, "settings": { "type": "object", "properties": { "systemPrompt": { "type": "string" }, "maxTokens": { "type": "integer", "minimum": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "logPayloads": { "type": "boolean" } } }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "name", "type", "content" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" } } } }, "expectedRevision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$", "description": "Omitted: compatibility write. Null: create-only. Positive decimal string: exact current revision from GET." } } } } } }, "responses": { "200": { "description": "Compatibility saved flag, or confirmed guarded saved flag, revision and guardedWrites=true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "saved" ], "properties": { "saved": { "const": true }, "reference": { "type": [ "string", "null" ], "description": "Permanent server-assigned Chat reference for product links." }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "guardedWrites": { "const": true, "description": "Present with revision only for confirmed guarded saves; older compatibility servers do not confirm this mode." } } } } } }, "400": { "description": "Invalid content or expected revision." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace write access required." }, "404": { "description": "Resource missing or outside authorized workspace/owner scope." }, "409": { "description": "Guarded creation/update does not match current owned state." }, "413": { "description": "Request exceeds the 24 MiB transport limit." }, "503": { "description": "Storage unavailable or bounded write wait exceeded." } }, "x-niu-implementation": "implemented", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/chats/{id}", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/tasks/{task}/refresh": { "post": { "operationId": "refreshGenerationsTaskByWorkspace", "x-niu-implementation": "implemented", "summary": "Explicitly refresh the original Video task", "description": "Explicit workspace Write action. Derives the original inference key and immutable Provider/account/model/channel binding from the actor-visible saved task; clients cannot choose replacements. Current original key grants and source policy remain required; revoked or expired keys never regain action authority through history. No generation, automatic retry or composer configuration is used. Rechecks actor visibility and grants after upstream work. Saved GET, cached artifact content, upstream refresh and fresh delivery remain distinct. Queries saved task status through the existing guarded recovery/settlement path; query receipts can be appended, but no task is created. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved Video state after explicit query", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "model", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "video.job" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "submission_unknown", "queued", "running", "succeeded", "failed", "unknown", "reconciliation_required" ] } } } } } }, "400": { "description": "Invalid kind or request" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace Write or original-key permission denied" }, "404": { "description": "Task missing, actor-private, or original key no longer available" }, "409": { "description": "Original Provider binding changed or query already claimed" }, "502": { "description": "Upstream query or result delivery failed" }, "503": { "description": "Storage or bounded delivery unavailable" }, "504": { "description": "Upstream query or delivery timed out" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/tasks/{task}/refresh", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/tasks/{task}/results/{kind}/refresh": { "post": { "operationId": "retrieveFreshGenerationsTaskResultByWorkspace", "x-niu-implementation": "implemented", "summary": "Retrieve fresh output from the original Video task", "description": "Explicit workspace Write action. Derives the original inference key and immutable Provider/account/model/channel binding from the actor-visible saved task; clients cannot choose replacements. Current original key grants and source policy remain required; revoked or expired keys never regain action authority through history. No generation, automatic retry or composer configuration is used. Rechecks actor visibility and grants after upstream work. Saved GET, cached artifact content, upstream refresh and fresh delivery remain distinct. Queries the original task once, then performs bounded authorized binary retrieval. Does not rewrite expired/deleted cached references. A fresh URL does not prove durable media availability; missing result404, Provider gone/unavailable502 and timeout504 remain explicit. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Bounded media bytes", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/webm": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid kind or request" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace Write or original-key permission denied" }, "404": { "description": "Task missing, actor-private, or original key no longer available" }, "409": { "description": "Original Provider binding changed or query already claimed" }, "502": { "description": "Upstream query or result delivery failed" }, "503": { "description": "Storage or bounded delivery unavailable" }, "504": { "description": "Upstream query or delivery timed out" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/tasks/{task}/results/{kind}/refresh", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/artifacts/{task}/{kind}/capture": { "get": { "operationId": "retrieveGenerationsArtifactCaptureByWorkspace", "summary": "Read saved artifact capture status", "description": "Current dashboard workspace Read permission and actor-visible original task required. Task/output identity is scoped; no Provider URLs, private references, credentials or costs are returned. Saved claim metadata only; no download, refresh, retry, generation or ledger mutation. Source lookup returns the stored/active outcome or newest failed request; missing/private task or missing capture404. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Saved capture metadata; retained means actual encrypted library bytes were committed, independent of Provider URL expiry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "task_id", "kind", "status", "asset_id", "availability", "failure_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "video", "last_frame" ] }, "status": { "enum": [ "preparing", "stored", "failed" ] }, "asset_id": { "type": [ "string", "null" ], "format": "uuid" }, "availability": { "enum": [ "retained", "deleted", "not_stored" ] }, "failure_code": { "enum": [ null, "delivery_failed", "authorization_changed", "invalid_media", "capacity_exceeded", "storage_unavailable", "encryption_unavailable" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid capture request or media bytes" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace or current key authority denied" }, "404": { "description": "Missing/private task, capture, or unavailable source" }, "409": { "description": "Active lease, changed replay, quota exceeded or binding/visibility conflict" }, "413": { "description": "Source bytes exceed8MiB" }, "502": { "description": "Upstream query or delivery failed" }, "503": { "description": "Capture capacity, configuration or storage unavailable" }, "504": { "description": "Upstream query or delivery timeout" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/artifacts/{task}/{kind}/capture", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "post": { "operationId": "captureGenerationsArtifactByWorkspace", "summary": "Explicitly save a generated output into workspace materials", "description": "Current dashboard workspace Write permission and actor-visible original task required. Task/output identity is scoped; no Provider URLs, private references, credentials or costs are returned. Explicit bounded copy into the existing encrypted workspace material library, not Provider registration or generation. Cached mode uses unexpired saved references under historical access; fresh mode explicitly queries the original task then retrieves output, using optional selected current workspace key or original-key fallback. The selected key cannot replace the immutable Provider/account/model/channel. Original expired keys without explicit current authority refuse fresh actions. Upstream operations never retry automatically. Two process capture slots; transport and format validation limited to8MiB; existing256asset/256MiB workspace quotas remain. A durable2minute preparing lease is committed before retrieval. Only an explicit repeated POST recovers failed/expired claims. Same requestid with changed fields409; a NEW requestid may change mode after failure; source identity prevents duplicate active/stored captures. Stored source replay returns canonical retained/deleted outcome without network; deleted retained bytes are never resurrected. Asset bytes, source provenance, quota and audit commit atomically after rechecking visibility under the source task lock. Failed delivery returns its error and retains a safe failed claim when storage is available; ambiguous failure-record writes leave preparing, not false availability. Cached expiry/deletion and original task/pricing identity are not rewritten. Fresh status queries may append diagnosis and settle an original pending liability through existing recovery, never create a new generation or reprice it. Saving shares copied bytes with authorized workspace members through the existing library; Provider readiness and verified identity remain separate. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Saved capture metadata; retained means actual encrypted library bytes were committed, independent of Provider URL expiry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "task_id", "kind", "status", "asset_id", "availability", "failure_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "video", "last_frame" ] }, "status": { "enum": [ "preparing", "stored", "failed" ] }, "asset_id": { "type": [ "string", "null" ], "format": "uuid" }, "availability": { "enum": [ "retained", "deleted", "not_stored" ] }, "failure_code": { "enum": [ null, "delivery_failed", "authorization_changed", "invalid_media", "capacity_exceeded", "storage_unavailable", "encryption_unavailable" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid capture request or media bytes" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace or current key authority denied" }, "404": { "description": "Missing/private task, capture, or unavailable source" }, "409": { "description": "Active lease, changed replay, quota exceeded or binding/visibility conflict" }, "413": { "description": "Source bytes exceed8MiB" }, "502": { "description": "Upstream query or delivery failed" }, "503": { "description": "Capture capacity, configuration or storage unavailable" }, "504": { "description": "Upstream query or delivery timeout" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "mode" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Canonical nonnil request identity retained before sending." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Exact trimmed UTF8 name, at most200 bytes, no control characters." }, "mode": { "enum": [ "cached", "fresh" ] }, "key_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Only fresh: explicit current workspace key authority; original Provider binding never changes." } } } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/artifacts/{task}/{kind}/capture", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/tasks": { "get": { "operationId": "generationsInventoryTasksByWorkspace", "summary": "List saved Video tasks across workspace keys", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "enum": [ "video" ] } }, { "name": "state", "in": "query", "schema": { "enum": [ "queued", "running", "succeeded", "failed", "unknown", "submission_unknown", "reconciliation_required" ] } }, { "name": "session_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "const": "video" }, "model": { "type": "string" }, "model_display_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "unknown", "submission_unknown", "reconciliation_required" ] }, "source": { "enum": [ "api", "generations", "unknown" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "turn_id": { "type": [ "string", "null" ], "format": "uuid" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "enum": [ "video", "last_frame" ] }, "availability": { "enum": [ "available", "deleted", "expired", "unavailable" ] }, "capture": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationArtifactCapture" }, { "type": "null" } ] } }, "required": [ "kind", "availability", "capture" ] } }, "execution_context": { "type": "object", "additionalProperties": false, "required": [ "submitted_model", "dispatched_model", "provider", "channel", "dispatched_at", "source", "parameters_source", "references_state", "parameters" ], "properties": { "submitted_model": { "type": "string" }, "dispatched_model": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "description": "Adapter recorded at dispatch; not a Provider account name." }, "channel": { "type": [ "string", "null" ] }, "dispatched_at": { "type": "string", "format": "date-time" }, "source": { "const": "saved_execution" }, "parameters_source": { "enum": [ "saved_validated_snapshot", "unknown" ] }, "references_state": { "const": "not_in_execution_snapshot" }, "parameters": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "duration": { "type": "number" }, "seed": { "type": "number" }, "frames_per_second": { "type": "number" }, "watermark": { "type": "boolean" }, "camera_fixed": { "type": "boolean" }, "return_last_frame": { "type": "boolean" }, "resolution": { "type": "string" }, "ratio": { "type": "string" }, "omni_reference_task_type": { "type": "string" } } } } }, "model_display_name_source": { "enum": [ "current_catalog", "unknown" ] }, "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$", "description": "Permanent public run reference, independent of the internal identifier." } }, "required": [ "id", "kind", "model", "model_display_name", "created_at", "updated_at", "state", "source", "session_id", "turn_id", "artifacts", "execution_context", "model_display_name_source" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "supported_kinds": { "type": "array", "items": { "const": "video" } }, "complete": { "const": true } }, "required": [ "data", "has_more", "next_cursor", "supported_kinds", "complete" ] } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/tasks", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/tasks/{task}": { "get": { "operationId": "generationsInventoryTaskByWorkspace", "summary": "Read a saved Video task", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" } ] }, "description": "Internal task UUID or permanent public run reference. Both require the same current workspace and actor authorization." } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "const": "video" }, "model": { "type": "string" }, "model_display_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "unknown", "submission_unknown", "reconciliation_required" ] }, "source": { "enum": [ "api", "generations", "unknown" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "turn_id": { "type": [ "string", "null" ], "format": "uuid" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "enum": [ "video", "last_frame" ] }, "availability": { "enum": [ "available", "deleted", "expired", "unavailable" ] }, "capture": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationArtifactCapture" }, { "type": "null" } ] } }, "required": [ "kind", "availability", "capture" ] } }, "execution_context": { "type": "object", "additionalProperties": false, "required": [ "submitted_model", "dispatched_model", "provider", "channel", "dispatched_at", "source", "parameters_source", "references_state", "parameters" ], "properties": { "submitted_model": { "type": "string" }, "dispatched_model": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "description": "Adapter recorded at dispatch; not a Provider account name." }, "channel": { "type": [ "string", "null" ] }, "dispatched_at": { "type": "string", "format": "date-time" }, "source": { "const": "saved_execution" }, "parameters_source": { "enum": [ "saved_validated_snapshot", "unknown" ] }, "references_state": { "const": "not_in_execution_snapshot" }, "parameters": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "duration": { "type": "number" }, "seed": { "type": "number" }, "frames_per_second": { "type": "number" }, "watermark": { "type": "boolean" }, "camera_fixed": { "type": "boolean" }, "return_last_frame": { "type": "boolean" }, "resolution": { "type": "string" }, "ratio": { "type": "string" }, "omni_reference_task_type": { "type": "string" } } } } }, "model_display_name_source": { "enum": [ "current_catalog", "unknown" ] }, "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$", "description": "Permanent public run reference, independent of the internal identifier." } }, "required": [ "id", "kind", "model", "model_display_name", "created_at", "updated_at", "state", "source", "session_id", "turn_id", "artifacts", "execution_context", "model_display_name_source" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/tasks/{task}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/tasks/{task}/diagnostics": { "get": { "operationId": "generationsTaskDiagnosticsByWorkspace", "x-niu-implementation": "implemented", "summary": "Read saved customer billing and transport diagnostics", "description": "Current dashboard workspace Read authorizes persisted diagnostics independently of the original inference key expiry, revocation or model grants. Actor-private tasks belonging to another actor are 404. Billing is customer-only; owner-funded jobs retain null customer charges and never expose procurement costs. Billing and measured transport/lifecycle observations share one bounded read-only snapshot. This GET never contacts a Provider, polls, refreshes, retries, submits or settles a task. Errors are explicit; no successful empty result hides a storage failure. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Persisted customer diagnostics", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "billing", "timings" ], "properties": { "billing": { "$ref": "#/components/schemas/handler_operations_json_VideoJobBilling" }, "timings": { "$ref": "#/components/schemas/handler_operations_json_VideoTransportTimings" } } } } } }, "401": { "description": "Invalid dashboard session" }, "403": { "description": "Workspace Read denied" }, "404": { "description": "Saved Video task missing or actor-private" }, "503": { "description": "Saved diagnostics unavailable" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/tasks/{task}/diagnostics", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/artifacts": { "get": { "operationId": "generationsInventoryArtifactsByWorkspace", "summary": "List actual saved output references", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "enum": [ "video" ] } }, { "name": "state", "in": "query", "schema": { "enum": [ "queued", "running", "succeeded", "failed", "unknown", "submission_unknown", "reconciliation_required" ] } }, { "name": "session_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "video", "last_frame" ] }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "content_type": { "type": [ "string", "null" ], "description": "Inspected captured-library content type when known; otherwise null." }, "availability": { "enum": [ "available", "deleted", "expired", "unavailable" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "turn_id": { "type": [ "string", "null" ], "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "capture": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationArtifactCapture" }, { "type": "null" } ] } }, "required": [ "task_id", "kind", "name", "created_at", "content_type", "availability", "session_id", "turn_id", "workspace_id", "capture" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "supported_kinds": { "type": "array", "items": { "const": "video" } }, "complete": { "const": true } }, "required": [ "data", "has_more", "next_cursor", "supported_kinds", "complete" ] } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/artifacts", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/artifacts/{task}/{kind}": { "get": { "operationId": "generationsInventoryArtifactByWorkspace", "summary": "Read an output availability record", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "video", "last_frame" ] }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "content_type": { "type": [ "string", "null" ], "description": "Inspected captured-library content type when known; otherwise null." }, "availability": { "enum": [ "available", "deleted", "expired", "unavailable" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "turn_id": { "type": [ "string", "null" ], "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "capture": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationArtifactCapture" }, { "type": "null" } ] } }, "required": [ "task_id", "kind", "name", "created_at", "content_type", "availability", "session_id", "turn_id", "workspace_id", "capture" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/artifacts/{task}/{kind}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/artifacts/{task}/{kind}/content": { "get": { "operationId": "generationsInventoryContentByWorkspace", "summary": "Download an authorized retained output", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/artifacts/{task}/{kind}/content", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/sessions": { "get": { "operationId": "generationsSessionListByWorkspace", "summary": "List private generations sessions", "description": "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. Read categories are video (default) and chat; legacy Chat write APIs remain unchanged. Revisions and sequences are decimal strings. Video instructions follow existing Chat/intents JSON storage (not application-encrypted at rest); Video 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. Stable descending creation time then UUID pagination; before refers to an actor-visible record independently of its current archive state; archiving a prior page cursor does not invalidate traversal. Invalid cursor returns 400, never an empty page. Limit 1..100; next_before is null when exhausted. Set category=chat for a read-only bridge over the existing actor-private Chat record. The same route defaults to video; IDs are scoped independently by category. Chat metadata uses database clocks and current guarded-write revision. Missing Chat title is null, never replaced by an internal ID. Chat turns preserve comparison branches, not one running conversation task. Per-turn creation/expiry clocks are unknown and null; missing retained prompt yields missing state and null instruction. Turn references are read-only scoped identity/sequence/instruction digests and cannot be used with Video writes. Branch phase/output are exact saved conversation content; actual execution references require a current workspace attempt and matching model. Customer charges are hydrated from the existing ledger projection; no saved procurement fields are returned. Chat retention and writes stay under the legacy Chat contract; Video 30-day instruction retention does not apply to this bridge. This canonical route requires category explicitly: session identity is (workspace, authenticated owner, category, UUID). Chat projection reads remain read-only; guarded Chat mutations use the workspace chats routes. A Chat identifier never authorizes a Video mutation. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "archived", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video", "chat" ] }, "required": true } ], "responses": { "200": { "description": "List private video generations sessions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSessionSummary" }, { "$ref": "#/components/schemas/handler_operations_json_GenerationsChatSessionSummary" } ] } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "data", "has_more", "next_before" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/sessions/{session}": { "put": { "operationId": "generationsSessionCreateByWorkspace", "summary": "Create a private video generations session", "description": "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. Client chooses stable UUID; expected_revision must be zero. Identical initial retry returns same session; changed title or an already advanced session conflicts. This canonical route requires category explicitly: session identity is (workspace, authenticated owner, category, UUID). Chat projection reads remain read-only; guarded Chat mutations use the workspace chats routes. A Chat identifier never authorizes a Video mutation. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video" ] }, "required": true } ], "responses": { "200": { "description": "Create a private video generations session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "const": "0" }, "title": { "type": "string", "minLength": 1, "maxLength": 800 } }, "required": [ "expected_revision", "title" ] } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/{session}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "get": { "operationId": "generationsSessionGetByWorkspace", "summary": "Read a private saved generations timeline", "description": "Reads accept a category-specific permanent public reference or legacy UUID. Both preserve the same private workspace/owner authorization. Mutation routes continue to require internal UUIDs. 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. Read categories are video (default) and chat; legacy Chat write APIs remain unchanged. Revisions and sequences are decimal strings. Video instructions follow existing Chat/intents JSON storage (not application-encrypted at rest); Video 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. Set category=chat for a read-only bridge over the existing actor-private Chat record. The same route defaults to video; IDs are scoped independently by category. Chat metadata uses database clocks and current guarded-write revision. Missing Chat title is null, never replaced by an internal ID. Chat turns preserve comparison branches, not one running conversation task. Per-turn creation/expiry clocks are unknown and null; missing retained prompt yields missing state and null instruction. Turn references are read-only scoped identity/sequence/instruction digests and cannot be used with Video writes. Branch phase/output are exact saved conversation content; actual execution references require a current workspace attempt and matching model. Customer charges are hydrated from the existing ledger projection; no saved procurement fields are returned. Chat retention and writes stay under the legacy Chat contract; Video 30-day instruction retention does not apply to this bridge. This canonical route requires category explicitly: session identity is (workspace, authenticated owner, category, UUID). Chat projection reads remain read-only; guarded Chat mutations use the workspace chats routes. A Chat identifier never authorizes a Video mutation. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video", "chat" ] }, "required": true } ], "responses": { "200": { "description": "Read a private saved video timeline", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" }, { "$ref": "#/components/schemas/handler_operations_json_GenerationsChatSession" } ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" }, "413": { "description": "Saved Chat payload exceeds the bounded 32 MiB materialization budget." } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/{session}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "patch": { "operationId": "generationsSessionUpdateByWorkspace", "summary": "Rename or archive a private video session", "description": "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. This canonical route requires category explicitly: session identity is (workspace, authenticated owner, category, UUID). Chat projection reads remain read-only; guarded Chat mutations use the workspace chats routes. A Chat identifier never authorizes a Video mutation. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video" ] }, "required": true } ], "responses": { "200": { "description": "Rename or archive a private video session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "title": { "type": "string" }, "archived": { "type": "boolean" } }, "required": [ "expected_revision", "title", "archived" ] } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/{session}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/sessions/{session}/turns/{turn}": { "put": { "operationId": "generationsSessionAppendByWorkspace", "summary": "Append one retained video instruction", "description": "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. This canonical route requires category explicitly: session identity is (workspace, authenticated owner, category, UUID). Chat projection reads remain read-only; guarded Chat mutations use the workspace chats routes. A Chat identifier never authorizes a Video mutation. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "turn", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video" ] }, "required": true } ], "responses": { "200": { "description": "Append one retained video instruction", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "instruction": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoInstruction" } }, "required": [ "expected_revision", "instruction" ] } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/{session}/turns/{turn}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "delete": { "operationId": "generationsSessionDeleteInstructionByWorkspace", "summary": "Delete retained instruction content", "description": "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. Expected session revision is required; deletes only instruction content, retaining turn identity and immutable task association. This canonical route requires category explicitly: session identity is (workspace, authenticated owner, category, UUID). Chat projection reads remain read-only; guarded Chat mutations use the workspace chats routes. A Chat identifier never authorizes a Video mutation. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "turn", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video" ] }, "required": true } ], "responses": { "200": { "description": "Delete retained instruction content", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, "required": [ "expected_revision" ] } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/{session}/turns/{turn}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/sessions/{session}/turns/{turn}/task": { "put": { "operationId": "generationsSessionAttachByWorkspace", "summary": "Attach an existing authorized video task", "description": "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. API-created dispatched video tasks with an original recovery route in the same workspace may be attached by a current workspace writer without an active key secret. An original actor-owned submission intent belonging to another actor is forbidden. One task belongs to one turn and one turn has one task. Existing association retries are idempotent; a different association conflicts. Current revision is required for fresh association. Revoked keys gain no dispatch or refresh authority. This canonical route requires category explicitly: session identity is (workspace, authenticated owner, category, UUID). Chat projection reads remain read-only; guarded Chat mutations use the workspace chats routes. A Chat identifier never authorizes a Video mutation. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "turn", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video" ] }, "required": true } ], "responses": { "200": { "description": "Attach an existing authorized video task", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "task_id": { "type": "string", "format": "uuid" } }, "required": [ "expected_revision", "task_id" ] } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/{session}/turns/{turn}/task", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/sessions/{session}/turns/{turn}/intent": { "put": { "operationId": "generationsSessionBindIntentByWorkspace", "summary": "Bind a saved Video intent to a private turn", "description": "Current workspace Write and actor-owned video session/turn/intent required. This only binds saved restoration identity and never dispatches, refreshes or automatically submits inference. One turn and one intent form an immutable association within the same owner/workspace. A fresh association requires expected session revision, an unarchived session and retained turn/intent content. Identical binding retries are side-effect-free even after revision advances, archive, deletion or expiry; changed binding conflicts. If the turn already references a task, it must equal the actual attempt from the original intent submission identity. Session reads resolve any saved original attempt directly from that identity after a lost submission/association response without another inference call. Pending/not-dispatched/unknown outcomes are never assumed free or safe to resend. Safe intent projection includes id, revision, model, content state and submission state, not raw request, key secret or private upstream references. Turn content deletion/expiry clears the bound retained intent copy under turn-to-intent locking while preserving submission tombstones, task evidence, billing and diagnostics. Intent and turn keep their original 30-day retention deadlines; neither is extended. Legacy Video intent APIs remain compatible and explicit submission continues through their submit endpoint. The bound intent is canonical for the actual restored Video draft/request, including model, controls and material inputs. The separately saved turn instruction may be a review note and is not represented as proof of the dispatched prompt; reads never substitute it for missing retained intent content. This canonical route requires category explicitly: session identity is (workspace, authenticated owner, category, UUID). Chat projection reads remain read-only; guarded Chat mutations use the workspace chats routes. A Chat identifier never authorizes a Video mutation. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "turn", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video" ] }, "required": true } ], "responses": { "200": { "description": "Attach an existing authorized video task", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "intent_id": { "type": "string", "format": "uuid" } }, "required": [ "expected_revision", "intent_id" ] } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/generations/{session}/turns/{turn}/intent", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/billing": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getCustomerBillingByWorkspace", "summary": "Read workspace customer charges, tariffs and latest 100 invoices", "description": "Requires workspace read access. Balances cover the full ledger per currency. Tariffs are current effective customer selling prices using the same workspace/standard enrollment and customer/global promotion selection as model discovery, within the billing read snapshot. Enabled personally funded routes are excluded. Rates are informational and do not establish route availability or spending authorization. All monetary amounts and aggregate counts are decimal integer strings. Upstream costs are separate. Cache-Control is no-store. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "responses": { "200": { "description": "Billing overview", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "balances", "unresolved", "unpriced", "tariffs", "invoices" ], "properties": { "balances": { "type": "array", "items": { "type": "object", "required": [ "currency", "charged_nanos", "unbilled_nanos", "due_nanos", "paid_nanos" ], "properties": { "currency": { "type": "string" }, "charged_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "unbilled_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "due_nanos": { "allOf": [ { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Invoiced charges without an invoice receipt or matching balance debit." }, "paid_nanos": { "allOf": [ { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Charges settled by a balance debit or invoice receipt, counted once, including balance debits before invoicing." } } } }, "unresolved": { "allOf": [ { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Dispatched non-personal requests with a text or media price binding but no corresponding charge; excludes confirmed nonexecution." }, "unpriced": { "allOf": [ { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Dispatched non-personal requests without either a text or media price binding; excludes confirmed nonexecution." }, "tariffs": { "type": "array", "items": { "type": "object", "required": [ "model_alias", "revision", "currency", "prompt_rate", "completion_rate" ], "properties": { "model_alias": { "type": "string" }, "revision": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "minimum_charge_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Minimum customer charge in currency nanounits (0 to 9223372036854775807), not a token rate. Defaults to zero for new tariffs. Replacing a nonzero minimum requires an explicit value; zero disables it. Known completed usage is charged the greater of the rounded token amount plus request_fee_nanos and this minimum. Unknown usage remains unresolved." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "request_fee_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Customer-only fixed fee in currency nanounits (0 to 9223372036854775807). Charge = max(rounded token charge + request fee, minimum charge) for known completed usage. Unknown execution/usage and confirmed rejection do not create a fee. Defaults to zero on new tariffs; replacement of a nonzero fee requires an explicit value; zero disables it." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." }, "discount_baseline_revision": { "type": [ "string", "null" ], "format": "uuid", "description": "Original selling-price revision for an explicit discount. API reference only; never a UI label. Resulting rates, currency, category presence and context thresholds are checked against the original. Existing requests retain their pinned revision." }, "pricing_source": { "type": "string", "enum": [ "workspace", "platform" ] }, "promotion_scope": { "type": [ "string", "null" ], "enum": [ "customer", "global", null ] }, "price_version": { "type": "string", "pattern": "^[0-9]+$" }, "selected_at": { "type": "string", "pattern": "^[0-9]+$", "description": "Selection cutoff as Unix seconds; informational, not a pinned request quote." } } } }, "invoices": { "type": "array", "items": { "type": "object", "required": [ "id", "from_ms", "to_ms", "currency", "amount_nanos", "created_at", "status", "payment_reference" ], "properties": { "id": { "type": "string", "format": "uuid" }, "from_ms": { "type": "integer", "format": "int64" }, "to_ms": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "issued", "paid" ], "description": "Paid when an invoice receipt exists or every included charge is settled by a matching balance debit or has zero value. Credit-backed account debt remains separate." }, "payment_reference": { "type": [ "string", "null" ] } } } } } } } } } } }, "401": { "description": "Invalid or expired credential" }, "404": { "description": "Workspace outside authorized scope" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/billing", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/spending-limit": { "get": { "operationId": "listWorkspaceSpendingLimitsByWorkspace", "summary": "List workspace spending currencies", "description": "Workspace readers may discover company account currencies and this workspace commitment without company-balance access. Absent limits and revisions are null. No state is changed. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "workspace", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current scoped state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceSpendingSummary" } } } } } } }, "400": { "description": "Invalid currency, decimal value or history query" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient role permissions" }, "404": { "description": "Workspace unavailable in the authorized scope" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/spending-limit", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/spending-limit/{currency}": { "get": { "operationId": "getWorkspaceSpendingLimitByWorkspace", "summary": "Read a workspace spending limit", "description": "Workspace read permission required. Returns data: null when no explicit limit exists. Does not expose company funds or other workspace usage. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "workspace", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "responses": { "200": { "description": "Current scoped state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_WorkspaceSpendingSummary" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid currency, decimal value or history query" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient role permissions" }, "404": { "description": "Workspace unavailable in the authorized scope" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/spending-limit/{currency}", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "setWorkspaceSpendingLimitByWorkspace", "summary": "Set a workspace spending limit", "description": "Scoped owner or installation administrator required. Both input fields are nonnegative decimal strings, not null. expected_revision 0 creates the first limit; later writes require the saved revision. Zero denies new paid liability; there is no null reset on this endpoint. A limit below existing commitment is rejected. Writes append actor history and never change company funds. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "workspace", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "responses": { "200": { "description": "Current scoped state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." } } } } } } } }, "400": { "description": "Invalid currency, decimal value or history query" }, "401": { "description": "Authentication required" }, "402": { "description": "Limit is below existing workspace commitment" }, "403": { "description": "Insufficient role permissions" }, "404": { "description": "Workspace unavailable in the authorized scope" }, "409": { "description": "Revision conflict or unavailable currency account" }, "422": { "description": "JSON input shape is invalid" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceSpendingInput" } } } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/spending-limit/{currency}", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/spending-limit/{currency}/history": { "get": { "operationId": "listWorkspaceSpendingLimitHistoryByWorkspace", "summary": "List workspace spending revisions", "description": "Workspace read permission required. Descending immutable history. before_revision is exclusive. next_before_revision is a decimal string or null; an exactly full final page can yield an empty following page. Baseline timestamps and actor data may be null. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "workspace", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "in": "query", "name": "before_revision", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Current scoped state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_before_revision" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceSpendingHistory" } }, "next_before_revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." } } } } } }, "400": { "description": "Invalid currency, decimal value or history query" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient role permissions" }, "404": { "description": "Workspace unavailable in the authorized scope" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/spending-limit/{currency}/history", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/units/limit": { "get": { "operationId": "getWorkspaceCustomerUnitSpendingLimitByWorkspace", "summary": "Read the workspace Credits spending limit and commitment", "description": "Workspace read permission required. Returns the workspace's explicit Credits atom limit, policy revision, committed atoms (settled charges minus original-range restorations plus unresolved holds and known overrun liabilities), remaining allowance, and whether an existing monetary workspace limit is preserved. A preserved monetary limit blocks Credits admission until an explicit Credits workspace limit revision (integer atoms or null for unlimited) is published. Never exposes company balance or procurement costs. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current workspace Credits spending limit state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "unit", "limit_atoms", "revision", "definition_revision", "committed_atoms", "remaining_atoms", "monetary_limit_preserved", "credits_admission_blocked_by_monetary_limit" ], "properties": { "unit": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "definition_revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "definition_revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "committed_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "remaining_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_limit_preserved": { "type": "boolean" }, "credits_admission_blocked_by_monetary_limit": { "type": "boolean" } } } } } } } }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace not found in the authorized scope" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/units/limit", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "setWorkspaceCustomerUnitSpendingLimitByWorkspace", "summary": "Set the workspace Credits spending limit", "description": "Workspace/company owner or installation administrator required and rechecked under lock. Sets an exact Credits atom cap or explicit null for unlimited, using optimistic revision checking and durable idempotency. Lowering below committed workspace liability (charges minus restorations plus unresolved holds and known overrun liabilities) returns 402. Preserves existing monetary workspace limits for currency mode while replacing their blocking effect in Credits admission. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "limit_atoms", "expected_revision", "idempotency_key" ], "properties": { "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$", "description": "Canonical nonnegative signed-64-bit integer string or explicit null for unlimited." }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Zero for initial configuration; maximum 9223372036854775806." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Immutable policy revision receipt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "expected_revision", "definition_revision", "limit_atoms", "recorded_at", "actor_kind", "actor_name" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } }, "400": { "description": "Invalid integer string" }, "401": { "description": "Authentication required or revoked" }, "402": { "description": "Proposed limit is below committed workspace liability" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace not found in the authorized scope" }, "409": { "description": "Stale revision, conflicting idempotency key or missing published unit definition" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/units/limit", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/units/limit/history": { "get": { "operationId": "listWorkspaceCustomerUnitSpendingLimitHistoryByWorkspace", "summary": "List workspace Credits spending limit history", "description": "Workspace read permission required. Returns descending immutable revisions with exclusive before_revision pagination. Never exposes internal actor identifiers. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Descending immutable policy revisions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_before_revision" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "revision", "expected_revision", "definition_revision", "limit_atoms", "recorded_at", "actor_kind", "actor_name" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } }, "next_before_revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } } } } }, "400": { "description": "Invalid history cursor or page size" }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace not found in the authorized scope" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/units/limit/history", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/units/limit": { "get": { "operationId": "getKeyCustomerUnitSpendingLimitByWorkspace", "summary": "Read an API key's Credits spending limit and commitment", "description": "Workspace read permission required. Rotated keys share their original spending root identity. Returns the key lineage's explicit Credits atom limit, policy revision, committed atoms (settled charges minus restorations plus unresolved holds and known overrun liabilities), remaining allowance, and whether an existing monetary key limit is preserved. A preserved monetary key limit blocks Credits admission until an explicit Credits key limit revision is published. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current API key Credits spending limit state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "unit", "limit_atoms", "revision", "definition_revision", "committed_atoms", "remaining_atoms", "monetary_limit_preserved", "credits_admission_blocked_by_monetary_limit" ], "properties": { "unit": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "definition_revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "definition_revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "committed_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "remaining_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_limit_preserved": { "type": "boolean" }, "credits_admission_blocked_by_monetary_limit": { "type": "boolean" } } } } } } } }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Key does not exist in the authorized workspace" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/units/limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "setKeyCustomerUnitSpendingLimitByWorkspace", "summary": "Set an API key's Credits spending limit", "description": "Workspace/company owner or installation administrator required and rechecked under lock. Updates the shared spending root identity across secret rotations using optimistic revision checking and durable idempotency. Lowering below committed key liability returns 402. Preserves existing monetary key limits for currency mode while replacing their blocking effect in Credits admission. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "limit_atoms", "expected_revision", "idempotency_key" ], "properties": { "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$", "description": "Canonical nonnegative signed-64-bit integer string or explicit null for unlimited." }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Zero for initial configuration; maximum 9223372036854775806." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Immutable policy revision receipt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "expected_revision", "definition_revision", "limit_atoms", "recorded_at", "actor_kind", "actor_name" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } }, "400": { "description": "Invalid integer string" }, "401": { "description": "Authentication required or revoked" }, "402": { "description": "Proposed limit is below committed key liability" }, "403": { "description": "Owner permission required" }, "404": { "description": "Key does not exist in the authorized workspace" }, "409": { "description": "Stale revision, conflicting idempotency key, unattributed active liability or missing unit definition" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/units/limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/units/limit/history": { "get": { "operationId": "listKeyCustomerUnitSpendingLimitHistoryByWorkspace", "summary": "List API key Credits spending limit history", "description": "Workspace read permission required. Returns descending immutable revisions shared across key rotations, with exclusive before_revision pagination. Never exposes internal actor identifiers. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Descending immutable policy revisions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_before_revision" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "revision", "expected_revision", "definition_revision", "limit_atoms", "recorded_at", "actor_kind", "actor_name" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } }, "next_before_revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } } } } }, "400": { "description": "Invalid history cursor or page size" }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Key does not exist in the authorized workspace" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/units/limit/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/requests": { "get": { "operationId": "listProjectGatewayActivityByWorkspace", "summary": "Read automatically retained gateway request activity", "description": "Returns metadata for model attempts admitted by Niu, newest first by default, with the requested sort applied to the whole range. Request and response bodies, prompts and completions are not included. Pages are bounded to at most 100 entries. Pass the previous response's next_cursor as after to read older matching entries; traversal is a live view, not a cross-page snapshot. Optional filters apply to the whole workspace scope. summary totals cover the selected filters independent of page. Rows and summary in one response share a database snapshot. Reporting reads use a one-second database lock timeout and a five-second timeout per SQL statement. Timeout returns a sanitized 503 error, never partial results; these are not whole-request deadlines. An absent task_id means the caller did not supply X-Niu-Task-ID. Missing usage remains unknown. All workspace responses exclude Provider expenses and platform margins, including for installation administrators. Customer-facing charges and nullable observed request phase timing are included. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "http_status", "in": "query", "description": "Recorded delivery HTTP status, or unknown when absent; independent of Provider execution.", "schema": { "type": "string", "pattern": "^(unknown|[1-5][0-9]{2})$" } }, { "name": "sort", "in": "query", "description": "Full-range order. Known latency/token values precede unknown values; time and ID break ties. Live traversal is not a cross-page snapshot.", "schema": { "type": "string", "enum": [ "time_desc", "time_asc", "latency_desc", "input_desc", "output_desc" ], "default": "time_desc" } }, { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "description": "Exclusive cursor from the previous page's next_cursor; continue strictly after this attempt in the same sort order; preserve sort and filters across pages.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "from_ms", "in": "query", "description": "Inclusive creation-time lower bound as Unix epoch milliseconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "to_ms", "in": "query", "description": "Exclusive creation-time upper bound as Unix epoch milliseconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "model_alias", "in": "query", "description": "Exact public model alias filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "operation_id", "in": "query", "description": "Restrict attempts and summaries to one operation within the authorized workspace. Unknown or foreign operations yield an empty result; this does not authorize cross-workspace reads.", "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "query", "description": "Workspace API key ID filter. Matches the dispatched key or a captured requested key in saved admission-denial evidence while the attempt remains unsent. Does not change billing attribution. Key names and IDs are visible only within the authorized workspace.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Exact gateway execution state, or output_withheld for recorded blocked/indeterminate output inspection. delivery_failed selects recorded HTTP errors (400–599). recorded_failure selects persisted upstream failure observations, including errors delivered inside HTTP 200 streams, and saved Gateway admission denials while the attempt remains unsent. Missing failure observations are not inferred from execution uncertainty. Completion at the Provider does not establish successful response delivery.", "schema": { "type": "string", "enum": [ "not_sent", "may_have_executed", "confirmed_completed", "confirmed_not_executed", "output_withheld", "delivery_failed", "recorded_failure" ] } } ], "responses": { "200": { "description": "Gateway activity wrapped in data, nullable next_cursor, and summary. Each entry includes attempt_id, operation_id, optional workspace api_key_id/key_name and task_id, an optional summary of the latest supplemental execution record for that task, public model alias and nullable provider-reported model, creation/dispatch/completion times, duration_ms, execution status, usage confidence, nullable prompt/completion token counts, and nullable customer charge currency/amount/status and request phase timing. Integer quantities and amounts are decimal strings. Pages follow the requested sort; next_cursor is the last attempt_id when further matching entries remain. summary covers all rows matching the filters, not only the current page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor", "summary" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_GatewayActivity" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "summary": { "type": "object", "required": [ "request_count", "usage_count", "prompt_tokens", "completion_tokens", "timing_count", "average_duration_ms" ], "properties": { "request_count": { "type": "integer", "format": "int64" }, "usage_count": { "type": "integer", "format": "int64" }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "timing_count": { "type": "integer", "format": "int64" }, "average_duration_ms": { "type": [ "integer", "null" ], "minimum": 0, "description": "Rounded mean of completed gateway request totals over all matching requests. Interrupted phase measurements are excluded. Historical rows without phase timing are excluded because their dispatch interval uses a different boundary. No eligible samples returns null." }, "unresolved_customer_charge_count": { "type": "integer", "minimum": 0 }, "unpriced_request_count": { "type": "integer", "minimum": 0 }, "owner_funded_request_count": { "type": "integer", "minimum": 0, "description": "Dispatched requests using the account owner’s API credential without a Niu customer debit." }, "delivery_statuses": { "type": "array", "description": "Counts by recorded delivery HTTP status across all matching requests in the summary snapshot. Null means unknown, not successful or failed.", "items": { "type": "object", "required": [ "http_status", "request_count" ], "properties": { "http_status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "request_count": { "type": "integer", "minimum": 0 } } } }, "customer_charges": { "type": "array", "items": { "type": "object", "required": [ "currency", "amount_nanos", "charged_requests" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "charged_requests": { "type": "integer", "minimum": 0 } } } }, "customer_unit_charges": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "definition_revision", "name", "display_precision", "atoms_per_unit", "charged_atoms", "restored_atoms", "net_atoms", "charged_requests" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "charged_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "restored_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "net_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "charged_requests": { "type": "integer", "minimum": 0 } } } }, "unit_charges_by_model": { "type": "array", "items": { "type": "object" } }, "unit_charges_by_key": { "type": "array", "items": { "type": "object" } }, "usage_by_model": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "model_alias", "request_count", "usage_count", "prompt_tokens", "completion_tokens", "unknown_usage_count" ], "properties": { "model_alias": { "type": "string" }, "request_count": { "type": "integer", "minimum": 0 }, "usage_count": { "type": "integer", "minimum": 0 }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "unknown_usage_count": { "type": "integer", "minimum": 0 } } } }, "charges_by_model": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Full-range customer ledger totals grouped separately by currency; missing amounts stay null. Coverage counts partition each row's requests. Provider expenses are excluded.", "required": [ "currency", "amount_nanos", "request_count", "charged_requests", "unresolved_requests", "unpriced_requests", "not_charged_requests" ], "properties": { "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "request_count": { "type": "integer", "minimum": 0 }, "charged_requests": { "type": "integer", "minimum": 0 }, "unresolved_requests": { "type": "integer", "minimum": 0 }, "unpriced_requests": { "type": "integer", "minimum": 0 }, "not_charged_requests": { "type": "integer", "minimum": 0 } } }, { "type": "object", "required": [ "model_alias" ], "properties": { "model_alias": { "type": "string" } } } ] } }, "charges_by_key": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Full-range customer ledger totals grouped separately by currency; missing amounts stay null. Coverage counts partition each row's requests. Provider expenses are excluded.", "required": [ "currency", "amount_nanos", "request_count", "charged_requests", "unresolved_requests", "unpriced_requests", "not_charged_requests" ], "properties": { "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "request_count": { "type": "integer", "minimum": 0 }, "charged_requests": { "type": "integer", "minimum": 0 }, "unresolved_requests": { "type": "integer", "minimum": 0 }, "unpriced_requests": { "type": "integer", "minimum": 0 }, "not_charged_requests": { "type": "integer", "minimum": 0 } } }, { "type": "object", "required": [ "api_key_id", "key_name" ], "properties": { "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "key_name": { "type": [ "string", "null" ] } } } ] } }, "usage_by_key": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "api_key_id", "key_name", "request_count", "usage_count", "prompt_tokens", "completion_tokens", "unknown_usage_count" ], "properties": { "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "key_name": { "type": [ "string", "null" ] }, "request_count": { "type": "integer", "minimum": 0 }, "usage_count": { "type": "integer", "minimum": 0 }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "unknown_usage_count": { "type": "integer", "minimum": 0 } } } }, "latency_percentiles": { "type": "object", "description": "Discrete percentiles of completed gateway body-consumption durations across the filtered range, independent of pagination. Incomplete or missing measurements are excluded. This is not client receipt time or upstream-only generation time.", "required": [ "boundary", "sample_count", "p50_ms", "p95_ms", "p99_ms" ], "properties": { "boundary": { "type": "string", "const": "gateway_body_ms" }, "sample_count": { "type": "integer", "minimum": 0 }, "p50_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "p95_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "p99_ms": { "type": [ "integer", "null" ], "minimum": 0 } } }, "token_categories": { "type": "object", "description": "Explicitly reported token subsets over the full filtered snapshot. Sums cover reported requests only; null means no observations. Missing category data is never inferred as zero, and no category-specific billing rate is implied.", "required": [ "cache_write_input_tokens", "cached_input_tokens", "cache_write_input_requests", "cached_input_requests", "cache_write_input_unknown_requests", "cached_input_unknown_requests", "reasoning_output_tokens", "reasoning_output_requests", "reasoning_output_unknown_requests" ], "properties": { "cache_write_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cached_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_input_requests": { "type": "integer", "minimum": 0 }, "cached_input_requests": { "type": "integer", "minimum": 0 }, "cache_write_input_unknown_requests": { "type": "integer", "minimum": 0 }, "cached_input_unknown_requests": { "type": "integer", "minimum": 0 }, "reasoning_output_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_output_requests": { "type": "integer", "minimum": 0 }, "reasoning_output_unknown_requests": { "type": "integer", "minimum": 0 } } }, "request_histogram": { "type": "array", "maxItems": 24, "description": "Nonempty time buckets over all filtered requests, independent of pagination. Buckets and other summary aggregates share one database snapshot. Empty ranges return an empty array.", "items": { "type": "object", "required": [ "start_ms", "end_ms", "request_count" ], "properties": { "start_ms": { "type": "integer" }, "end_ms": { "type": "integer" }, "request_count": { "type": "integer", "minimum": 0 } } } } } } } } } }, "headers": { "Cache-Control": { "description": "Request diagnostics must not be cached.", "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid path or query parameter." }, "401": { "description": "Administrator authentication required." }, "404": { "description": "Resource missing or outside authorized workspace/owner scope." } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/requests", "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/requests/{attempt}": { "get": { "operationId": "getGatewayRequestByWorkspace", "summary": "Read a recorded gateway request", "description": "Scoped workspace read access required. Accepts a durable run reference or a legacy attempt UUID. Returns persisted metadata, usage, timing, safe failure classification and customer charges without prompts, response bodies or Provider procurement costs. Missing or foreign attempts return 404. Unknown values remain null. Legacy correlation fields are opaque metadata. Does not contact the upstream service or change billing. Reporting reads use a one-second database lock timeout and a five-second timeout per SQL statement. Timeout returns a sanitized 503 error, never partial results; these are not whole-request deadlines. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "workspace", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "attempt", "required": true, "schema": { "type": "string", "description": "Durable run reference or legacy attempt UUID" } } ], "responses": { "200": { "description": "Saved request metadata. Cache-Control: no-store.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GatewayRequestMetadata" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace read permission denied" }, "404": { "description": "Workspace or request unavailable in this scope" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/requests/{attempt}", "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/requests/{attempt}/usage-reconciliation": { "post": { "operationId": "reconcileRequestUsageByWorkspace", "summary": "Supplement missing native request usage from captured OpenRouter evidence", "description": "Installation write access only. Empty object input; no client-supplied generation identifier, quantities or costs. Uses the stored server response reference and original managed credential only while its vendor revision remains current and enabled. New captured references pin the dispatched upstream model independently of later mapping edits; legacy references without that binding still require the unchanged enabled model revision. Exact upstream model match required; aliases are not inferred equivalent. Bounded metadata lookup can return 502 while metadata is unavailable. Eligible requests have unknown aggregate usage, or confirmed provider-reported totals with missing cache-read/reasoning quantities and no recorded monetary or Credits customer charge. For known totals, metadata must match both totals and every reported known category, and add at least one previously missing category. Cache-write quantities are not supplied by this lookup; existing quantities are preserved. Canonical metadata must confirm not-cancelled execution with stop/length/tool_calls and an exact model/reference match. Cancelled or nonterminal metadata remains unresolved. Atomically retains the original execution/usage/category state and immutable supplemental terminal evidence, then marks execution confirmed-completed. Existing completion timestamps are preserved; absent timestamps record the time confirmation is stored. Original failure and delivery timing remain unchanged. Recorded does not mean settled: existing financial recovery applies the request-bound tariffs; missing required categories keep liability unresolved. Never resubmits inference. Identical replay returns the saved receipt without upstream access. Cache-Control no-store. New v2 receipts retain terminal finish/cancellation evidence. Legacy v1 receipts retain null terminal fields without invented backfill. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attempt", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Supplemental usage recorded; settlement may remain pending.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "source_version", "recorded_at", "prompt_tokens", "completion_tokens", "cached_input_tokens", "reasoning_output_tokens", "cache_write_input_tokens", "original_execution", "upstream_finish_reason", "upstream_cancelled" ], "properties": { "status": { "type": "string", "enum": [ "recorded" ] }, "source_version": { "type": "string", "enum": [ "openrouter-native-generation-v1", "openrouter-native-generation-v2" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "cached_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_output_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_input_tokens": { "type": "null" }, "original_execution": { "type": "string", "enum": [ "confirmed_completed", "may_have_executed" ] }, "upstream_finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", null ], "description": "Null for legacy v1 receipts; never backfilled." }, "upstream_cancelled": { "type": [ "boolean", "null" ], "enum": [ false, null ], "description": "Explicit false for v2 terminal evidence; null for legacy v1 receipts." } } } } } }, "400": { "description": "Malformed JSON input." }, "401": { "description": "Authentication required." }, "403": { "description": "Installation write access required." }, "404": { "description": "Scope unavailable." }, "409": { "description": "Ineligible completion, changed route or conflicting evidence. usage_reconciliation_identity_mismatch means upstream model/reference identity differs from captured request evidence; identities are not exposed. usage_reconciliation_incomplete means matching provider metadata does not confirm a non-cancelled terminal generation. Usage and charges remain unresolved in both cases." }, "422": { "description": "Input must be an empty JSON object; unknown fields are rejected." }, "502": { "description": "Upstream metadata unavailable, refused, malformed, oversized or timed out." }, "503": { "description": "Storage or credential decryption unavailable, including a bounded record-lock or statement timeout. A failed recording transaction preserves prior usage and leaves no partial receipt; retry does not resubmit inference." } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/requests/{attempt}/usage-reconciliation", "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "getRequestUsageReconciliationByWorkspace", "summary": "Read recorded supplemental request usage", "description": "Workspace read access required. Returns the same customer-safe immutable receipt as reconciliation, without querying upstream or modifying usage or accounting. Absence, unknown attempt and out-of-scope attempt return 404. Quantities are decimal strings; missing categories remain null. Recorded does not guarantee settlement. No original raw upstream metadata, generation reference, credential, Provider price or endpoint is exposed. Cache-Control no-store. New v2 receipts retain terminal finish/cancellation evidence. Legacy v1 receipts retain null terminal fields without invented backfill. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attempt", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Supplemental usage recorded; settlement may remain pending.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "source_version", "recorded_at", "prompt_tokens", "completion_tokens", "cached_input_tokens", "reasoning_output_tokens", "cache_write_input_tokens", "original_execution", "upstream_finish_reason", "upstream_cancelled" ], "properties": { "status": { "type": "string", "enum": [ "recorded" ] }, "source_version": { "type": "string", "enum": [ "openrouter-native-generation-v1", "openrouter-native-generation-v2" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "cached_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_output_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_input_tokens": { "type": "null" }, "original_execution": { "type": "string", "enum": [ "confirmed_completed", "may_have_executed" ] }, "upstream_finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", null ], "description": "Null for legacy v1 receipts; never backfilled." }, "upstream_cancelled": { "type": [ "boolean", "null" ], "enum": [ false, null ], "description": "Explicit false for v2 terminal evidence; null for legacy v1 receipts." } } } } } }, "401": { "description": "Authentication required." }, "404": { "description": "No recorded receipt in the authorized workspace." }, "503": { "description": "Storage or credential decryption unavailable." } }, "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/requests/{attempt}/usage-reconciliation", "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/spending-limit": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeySpendingLimitsByWorkspace", "description": "Scoped readers may inspect customer commitments. Rotated keys share the original spending identity. Personal upstream routes do not consume customer funds. No Provider costs or company balance are exposed. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "responses": { "200": { "description": "Account currencies and lifetime key commitments; null limit means unlimited and null revision means never configured.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "currency", "limit_nanos", "revision", "committed_nanos", "remaining_nanos" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "limit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "committed_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "remaining_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Maximum of cap minus committed customer amount and zero; null for unlimited. This is key allowance only, not company balance or guaranteed admission." } } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Key does not exist in the authorized workspace" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "summary": "List API key spending limits", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/spending-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/spending-limit/{currency}": { "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeySpendingLimitByWorkspace", "description": "Workspace/company owner or installation administrator. Cap includes settled customer charges minus refunds plus unreleased reservations, across secret rotations. Lowering below committed liability is rejected. Account and workspace limits still apply. Writes do not add funds. Null explicitly restores unlimited; omission is rejected. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "limit_nanos", "expected_revision" ], "properties": { "limit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Nonnegative signed-64-bit nanounits or explicit null." }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New immutable policy revision recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid amount or currency" }, "401": { "description": "Authentication required" }, "402": { "description": "Proposed limit is below committed key liability" }, "403": { "description": "Owner permission required" }, "404": { "description": "Key does not exist in the authorized workspace" }, "409": { "description": "Stale revision, missing account, or unresolved attribution" }, "422": { "description": "Missing or invalid body fields" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "x-niu-implementation": "implemented", "summary": "Set API key spending limit", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/spending-limit/{currency}", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/spending-limit/{currency}/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeySpendingLimitHistoryByWorkspace", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "description": "Descending immutable revision history shared across rotations. Use the last returned revision as before_revision for the next page. Returns currency, nullable limit_nanos, revision, recorded_at, actor_kind and actor_name; never an internal actor identifier. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "responses": { "200": { "description": "Data array of policy revisions", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "currency", "limit_nanos", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "limit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid currency or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Key does not exist in the authorized workspace" } }, "x-niu-implementation": "implemented", "summary": "List API key spending history", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/spending-limit/{currency}/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/ip-policy": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyIpPolicyByWorkspace", "description": "Scoped readers may inspect the policy shared across secret rotations. Storage reads use a read-only snapshot with transaction-local 250 ms lock and 2 s statement limits. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "responses": { "200": { "description": "Null revision means never configured. Null networks permit all sources; an empty array denies all sources.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "allowed_cidrs", "revision" ], "properties": { "allowed_cidrs": { "type": [ "array", "null" ], "maxItems": 64, "items": { "type": "string", "maxLength": 64 }, "description": "IPv4/IPv6 addresses or CIDRs, normalized to network CIDRs. Null permits all; empty denies all." }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "503": { "description": "Storage read unavailable, including a bounded lock or statement timeout. Preserve known policy/history; this does not permit bypassing source restrictions." } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "summary": "Read API key source policy", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/ip-policy", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeyIpPolicyByWorkspace", "description": "Owner or installation administrator only. Rotation preserves this policy. Does not cancel already admitted requests. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "allowed_cidrs", "expected_revision" ], "properties": { "allowed_cidrs": { "type": [ "array", "null" ], "maxItems": 64, "items": { "type": "string", "maxLength": 64 }, "description": "IPv4/IPv6 addresses or CIDRs, normalized to network CIDRs. Null permits all; empty denies all." }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New policy and immutable history committed atomically.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid network or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "409": { "description": "Stale policy revision" }, "422": { "description": "Missing or invalid JSON fields" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "summary": "Set API key source policy", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/ip-policy", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/ip-policy/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeyIpPolicyHistoryByWorkspace", "description": "Scoped readers receive descending revisions shared across rotations. Use the last revision as the next page cursor. Storage reads use a read-only snapshot with transaction-local 250 ms lock and 2 s statement limits. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Immutable policy history; no internal actor identifiers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "allowed_cidrs", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "allowed_cidrs": { "type": [ "array", "null" ], "maxItems": 64, "items": { "type": "string", "maxLength": 64 }, "description": "IPv4/IPv6 addresses or CIDRs, normalized to network CIDRs. Null permits all; empty denies all." }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "503": { "description": "Storage read unavailable, including a bounded lock or statement timeout. Preserve known policy/history; this does not permit bypassing source restrictions." } }, "x-niu-implementation": "implemented", "summary": "List API key source policy history", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/ip-policy/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/request-rate-limit": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyRequestRateLimitByWorkspace", "description": "Scoped readers may inspect the policy shared across secret rotations. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "responses": { "200": { "description": "Null revision means never configured. Null removes the limit; zero denies dispatch.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_KeyRequestRatePolicy" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Read API key request rate policy", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/request-rate-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeyRequestRateLimitByWorkspace", "description": "Owner or installation administrator only. Rotation preserves this policy. Does not cancel already admitted requests. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "requests_per_minute", "expected_revision" ], "properties": { "requests_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyRequestRateRequestLimit" }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New policy and immutable history committed atomically. Rolling windows persist across revisions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid limit or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "409": { "description": "Stale policy revision" }, "422": { "description": "Missing or invalid JSON fields" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Set API key request rate policy", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/request-rate-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/request-rate-limit/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeyRequestRateLimitHistoryByWorkspace", "description": "Scoped readers receive descending revisions shared across rotations. Use the last revision as the next page cursor. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Immutable policy history; no internal actor identifiers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "requests_per_minute", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "requests_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyRequestRateRequestLimit" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "summary": "List API key request rate policy history", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/request-rate-limit/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/token-usage-window": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyTokenUsageWindowByWorkspace", "description": "Scoped reader access. Dispatches in the rolling 60 seconds ending at window_end, across secret rotations. Known subtotals exclude unknown requests; zero known tokens does not mean zero actual usage. This endpoint does not enforce TPM and exposes no Provider cost. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "responses": { "200": { "description": "One consistent database snapshot, including an empty window for an unused key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "window_seconds", "window_end", "requests", "known_usage_requests", "unknown_usage_requests", "known_prompt_tokens", "known_completion_tokens" ], "properties": { "window_seconds": { "type": "integer", "const": 60 }, "window_end": { "type": "string", "format": "date-time" }, "requests": { "type": "integer", "minimum": 0 }, "known_usage_requests": { "type": "integer", "minimum": 0 }, "unknown_usage_requests": { "type": "integer", "minimum": 0 }, "known_prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "known_completion_tokens": { "type": "string", "pattern": "^[0-9]+$" } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Read permission required" }, "404": { "description": "Workspace outside operator scope or key absent from workspace" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Read API key token usage window", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/token-usage-window", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/concurrency-limit": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyConcurrencyLimitByWorkspace", "description": "Scoped readers may inspect the policy shared across secret rotations. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "responses": { "200": { "description": "Null revision means never configured. Null removes the limit; zero denies dispatch.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_KeyConcurrencyPolicy" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient management permission" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Read API key concurrency policy", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/concurrency-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeyConcurrencyLimitByWorkspace", "description": "Owner or installation administrator only. Rotation preserves this policy. Does not cancel already admitted requests. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "max_concurrent_requests", "expected_revision" ], "properties": { "max_concurrent_requests": { "$ref": "#/components/schemas/handler_operations_json_KeyConcurrencyConcurrencyLimit" }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New policy and immutable history committed atomically. Existing unresolved work remains counted across revisions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid limit or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "409": { "description": "Stale policy revision" }, "422": { "description": "Missing or invalid JSON fields" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Set API key concurrency policy", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/concurrency-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/concurrency-limit/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeyConcurrencyLimitHistoryByWorkspace", "description": "Scoped readers receive descending revisions shared across rotations. Use the last revision as the next page cursor. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Immutable policy history; no internal actor identifiers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "max_concurrent_requests", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "max_concurrent_requests": { "$ref": "#/components/schemas/handler_operations_json_KeyConcurrencyConcurrencyLimit" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient management permission" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "summary": "List API key concurrency policy history", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/concurrency-limit/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/capacity": { "get": { "operationId": "listKeyCapacityRequestsByWorkspace", "summary": "Inspect requests contributing unresolved key capacity", "description": "Workspace read authority required. Includes the full secret-rotation lineage. Concurrency uses unresolved dispatched requests. Tokens uses reservations and unbounded usage from unresolved dispatches plus completed unknown-usage requests in the rolling 60-second window, matching the token-budget calculation; known recent usage is not returned here. Each page has a fresh statement snapshot. UUID keyset cursor is internal; rows may resolve between pages. Refresh to restart investigation. This read does not contact Providers, reconcile usage, release reservations or retry requests. No credentials, prompt content or procurement data. Cache-Control no-store. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "concurrency", "tokens" ], "default": "concurrency" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Matching current contributors and snapshot count", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "total", "snapshot_at", "next_after" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "attempt_id", "model_alias", "key_name", "created_at", "dispatched_at", "completed_at", "execution", "reserved_tokens" ], "properties": { "attempt_id": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "key_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "dispatched_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "execution": { "type": "string", "enum": [ "may_have_executed", "confirmed_completed" ] }, "reserved_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } } } }, "total": { "type": "integer", "minimum": 0 }, "snapshot_at": { "type": "string", "format": "date-time" }, "next_after": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid query" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient management permission" }, "404": { "description": "Key or workspace outside the authorized scope" }, "409": { "description": "Cursor unavailable; restart pagination" } }, "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/capacity", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/token-rate-limit": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyTokenRateLimitByWorkspace", "description": "Scoped readers may inspect the policy shared across secret rotations. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "responses": { "200": { "description": "Null revision means never configured. Null removes the limit; zero denies dispatch.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_KeyTokenRatePolicy" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Read API key token rate policy", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/token-rate-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeyTokenRateLimitByWorkspace", "description": "Owner or installation administrator only. Rotation preserves this policy. Does not cancel already admitted requests. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "tokens_per_minute", "expected_revision" ], "properties": { "tokens_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyTokenRateTokenRateLimit" }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New policy and immutable history committed atomically. Existing unresolved work remains counted across revisions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid limit or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "409": { "description": "Stale policy revision" }, "422": { "description": "Missing or invalid JSON fields" } }, "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Set API key token rate policy", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/token-rate-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/token-rate-limit/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeyTokenRateLimitHistoryByWorkspace", "description": "Scoped readers receive descending revisions shared across rotations. Use the last revision as the next page cursor. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Immutable policy history; no internal actor identifiers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "tokens_per_minute", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "tokens_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyTokenRateTokenRateLimit" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "summary": "List API key token rate policy history", "x-niu-implementation": "implemented", "x-niu-compatibility-route": "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/token-rate-limit/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/billing/media-retail-price-enrollment": { "post": { "operationId": "setRetailMediaEnrollment", "summary": "Set workspace media selling-price enrollment", "description": "Exact workspace/media dimensions/meter identity; currency follows the enrolled price. Platform administration is required for changes. Reads require this workspace authority or platform administration and reveal only its own effective selling price. No procurement or other customer promotions are returned. price_id must be explicitly present: null restores legacy media-card selection for future operations. The published media price must exactly match dimensions and meter and have an existing customer currency account. No balance, credit, route, qualification or operation is created. expected_version is zero initially; exact idempotent retries preserve their original outcome, changed reuse and stale versions conflict. Read effective_price is advisory, not a pinned task price or dispatch qualification. UTC epoch times and amounts are exact strings. Cache-Control: no-store for reads. Video admission reselects at a shared database time and atomically pins customer/Provider prices, independently qualified quantity, provenance and funds. Enrolling a price alone does not enable generation; exact current qualified supply and a supported route remain required. Existing task prices are not reselected after admission.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Committed configuration or own advisory read", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "string", "format": "uuid" }, "version": { "type": "string", "pattern": "^[0-9]+$" }, "dimensions": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string" }, "channel": { "type": "string" }, "resolution": { "type": "string" }, "reference_video": { "type": "boolean" } }, "required": [ "model", "channel", "resolution", "reference_video" ] }, "meter": { "type": "string" }, "price_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "revision", "version", "dimensions", "meter", "price_id" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid exact identity, reason or version" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required for changes" }, "404": { "description": "Workspace outside authority" }, "409": { "description": "Stale version, conflicting key, mismatched price or absent existing currency account" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "dimensions": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string" }, "channel": { "type": "string" }, "resolution": { "type": "string" }, "reference_video": { "type": "boolean" } }, "required": [ "model", "channel", "resolution", "reference_video" ] }, "meter": { "type": "string" }, "price_id": { "type": [ "string", "null" ], "format": "uuid" }, "expected_version": { "type": "string", "pattern": "^[0-9]+$" }, "idempotency_key": { "type": "string", "format": "uuid" }, "reason": { "type": "string" } }, "required": [ "dimensions", "meter", "price_id", "expected_version", "idempotency_key", "reason" ] } } } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "getRetailMediaEnrollment", "summary": "Read workspace media selling-price enrollment", "description": "Exact workspace/media dimensions/meter identity; currency follows the enrolled price. Platform administration is required for changes. Reads require this workspace authority or platform administration and reveal only its own effective selling price. No procurement or other customer promotions are returned. price_id must be explicitly present: null restores legacy media-card selection for future operations. The published media price must exactly match dimensions and meter and have an existing customer currency account. No balance, credit, route, qualification or operation is created. expected_version is zero initially; exact idempotent retries preserve their original outcome, changed reuse and stale versions conflict. Read effective_price is advisory, not a pinned task price or dispatch qualification. UTC epoch times and amounts are exact strings. Cache-Control: no-store for reads. Video admission reselects at a shared database time and atomically pins customer/Provider prices, independently qualified quantity, provenance and funds. Enrolling a price alone does not enable generation; exact current qualified supply and a supported route remain required. Existing task prices are not reselected after admission.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "reference_video", "in": "query", "required": true, "schema": { "type": "boolean" } }, { "name": "meter", "in": "query", "required": true, "schema": { "type": "string" } } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Committed configuration or own advisory read", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "dimensions": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string" }, "channel": { "type": "string" }, "resolution": { "type": "string" }, "reference_video": { "type": "boolean" } }, "required": [ "model", "channel", "resolution", "reference_video" ] }, "meter": { "type": "string" }, "price_id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": "string", "pattern": "^[0-9]+$" }, "pricing_source": { "type": "string", "enum": [ "workspace", "platform" ] }, "effective_price": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_RetailSelection" }, { "type": "null" } ] } }, "required": [ "dimensions", "meter", "price_id", "version", "pricing_source", "effective_price" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid exact identity, reason or version" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required for changes" }, "404": { "description": "Workspace outside authority" }, "409": { "description": "Stale version, conflicting key, mismatched price or absent existing currency account" } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/providers/{supplier}/offers/{offer}/media-liability-bounds": { "post": { "operationId": "publishMediaLiabilityQualification", "summary": "Publish an evidenced route media liability bound", "description": "Explicit platform administration only. Ordinary customer and Provider memberships do not grant access. Liability qualifications are finite, immutable maximum billed quantities tied to exact currently approved Provider offer, credential/model/schema revisions, dimensions and meter; they contain no purchase or selling price and must be supported by explicit evidence. Video output estimates are not liability evidence. Publication alone does not authorize dispatch. UUIDs are API references, never display labels. Exact epoch times and versions are decimal integer strings. Identical idempotent retries preserve the original result; changed intent or stale versions conflict. Revocation affects future admission, never rewrites already pinned jobs. Reads use no-store.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "supplier", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Committed qualification change or paginated immutable history", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "qualification_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "format": "uuid" }, "version": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "qualification_id", "revision", "version" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid identity, exact quantity, finite interval, evidence or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting idempotency/interval or unavailable current qualified offer" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "identity": { "type": "object", "additionalProperties": false, "properties": { "supplier_id": { "type": "string", "format": "uuid" }, "offer_id": { "type": "string", "format": "uuid" }, "offer_revision": { "type": "string", "format": "uuid" }, "vendor_id": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "string", "pattern": "^[0-9]+$" }, "model_alias": { "type": "string" }, "model_revision": { "type": "string", "pattern": "^[0-9]+$" }, "schema_revision": { "type": "string" }, "dimensions": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string" }, "channel": { "type": "string" }, "resolution": { "type": "string" }, "reference_video": { "type": "boolean" } }, "required": [ "model", "channel", "resolution", "reference_video" ] }, "meter": { "type": "string" } }, "required": [ "supplier_id", "offer_id", "offer_revision", "vendor_id", "vendor_revision", "model_alias", "model_revision", "schema_revision", "dimensions", "meter" ] }, "maximum_quantity": { "type": "object", "additionalProperties": false, "properties": { "numerator": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "numerator", "denominator" ] }, "evidence_revision": { "type": "string" }, "evidence_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "effective_from": { "type": "string", "pattern": "^[0-9]+$" }, "effective_until": { "type": "string", "pattern": "^[0-9]+$" }, "expected_version": { "type": "string", "pattern": "^[0-9]+$" }, "idempotency_key": { "type": "string", "format": "uuid" }, "reason": { "type": "string" } }, "required": [ "identity", "maximum_quantity", "evidence_revision", "evidence_sha256", "effective_from", "effective_until", "expected_version", "idempotency_key", "reason" ] } } } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } }, "get": { "operationId": "listMediaLiabilityQualifications", "summary": "List immutable route media liability qualifications", "description": "Explicit platform administration only. Ordinary customer and Provider memberships do not grant access. Liability qualifications are finite, immutable maximum billed quantities tied to exact currently approved Provider offer, credential/model/schema revisions, dimensions and meter; they contain no purchase or selling price and must be supported by explicit evidence. Video output estimates are not liability evidence. Publication alone does not authorize dispatch. UUIDs are API references, never display labels. Exact epoch times and versions are decimal integer strings. Identical idempotent retries preserve the original result; changed intent or stale versions conflict. Revocation affects future admission, never rewrites already pinned jobs. Reads use no-store.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "supplier", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Committed qualification change or paginated immutable history", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "qualification_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "format": "uuid" }, "version": { "type": "string", "pattern": "^[0-9]+$" }, "current_version": { "type": "string", "pattern": "^[0-9]+$" }, "identity": { "type": "object", "additionalProperties": false, "properties": { "supplier_id": { "type": "string", "format": "uuid" }, "offer_id": { "type": "string", "format": "uuid" }, "offer_revision": { "type": "string", "format": "uuid" }, "vendor_id": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "string", "pattern": "^[0-9]+$" }, "model_alias": { "type": "string" }, "model_revision": { "type": "string", "pattern": "^[0-9]+$" }, "schema_revision": { "type": "string" }, "dimensions": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string" }, "channel": { "type": "string" }, "resolution": { "type": "string" }, "reference_video": { "type": "boolean" } }, "required": [ "model", "channel", "resolution", "reference_video" ] }, "meter": { "type": "string" } }, "required": [ "supplier_id", "offer_id", "offer_revision", "vendor_id", "vendor_revision", "model_alias", "model_revision", "schema_revision", "dimensions", "meter" ] }, "maximum_quantity": { "type": "object", "additionalProperties": false, "properties": { "numerator": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "numerator", "denominator" ] }, "evidence_revision": { "type": "string" }, "evidence_sha256": { "type": "string" }, "effective_from": { "type": "string", "pattern": "^[0-9]+$" }, "effective_until": { "type": "string", "pattern": "^[0-9]+$" }, "revocation_effective_until": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "actor_kind": { "type": "string", "enum": [ "installation", "operator" ] }, "actor_operator_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "revocation_revision": { "type": [ "string", "null" ], "format": "uuid" }, "revocation_reason": { "type": [ "string", "null" ] }, "revocation_actor_kind": { "type": [ "string", "null" ], "enum": [ "installation", "operator", null ] }, "revocation_actor_operator_id": { "type": [ "string", "null" ], "format": "uuid" }, "revocation_created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "qualification_id", "revision", "version", "current_version", "identity", "maximum_quantity", "evidence_revision", "evidence_sha256", "effective_from", "effective_until", "revocation_effective_until", "reason", "actor_kind", "actor_operator_id", "created_at", "revocation_revision", "revocation_reason", "revocation_actor_kind", "revocation_actor_operator_id", "revocation_created_at" ] } }, "next_after": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "data", "next_after" ] } } } }, "400": { "description": "Invalid identity, exact quantity, finite interval, evidence or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting idempotency/interval or unavailable current qualified offer" } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/providers/{supplier}/offers/{offer}/media-liability-bounds/{revision}/retire": { "post": { "operationId": "retireMediaLiabilityQualification", "summary": "Retire a route media liability bound", "description": "Explicit platform administration only. Ordinary customer and Provider memberships do not grant access. Liability qualifications are finite, immutable maximum billed quantities tied to exact currently approved Provider offer, credential/model/schema revisions, dimensions and meter; they contain no purchase or selling price and must be supported by explicit evidence. Video output estimates are not liability evidence. Publication alone does not authorize dispatch. UUIDs are API references, never display labels. Exact epoch times and versions are decimal integer strings. Identical idempotent retries preserve the original result; changed intent or stale versions conflict. Revocation affects future admission, never rewrites already pinned jobs. Reads use no-store.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "supplier", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Committed qualification change or paginated immutable history", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "qualification_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "format": "uuid" }, "version": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "qualification_id", "revision", "version" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid identity, exact quantity, finite interval, evidence or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting idempotency/interval or unavailable current qualified offer" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "effective_until": { "type": "string", "pattern": "^[0-9]+$" }, "expected_version": { "type": "string", "pattern": "^[0-9]+$" }, "idempotency_key": { "type": "string", "format": "uuid" }, "reason": { "type": "string" } }, "required": [ "effective_until", "expected_version", "idempotency_key", "reason" ] } } } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/organizations/{organization}/projects/{project}/billing/retail-price-enrollment": { "post": { "operationId": "setRetailTextEnrollment", "summary": "Enroll a workspace model in a platform selling price", "description": "Explicit platform administration required. price_id chooses a published text identity with the same model and an existing company/currency balance account; no account, credit, funds, Provider qualification or selling permission is created. Explicit null restores legacy workspace tariff selection for future operations. expected_version zero creates the configuration; updates use immutable version history and an exact company/workspace-scoped idempotency key. Existing operation prices, charges and legacy current tariff pointers are unchanged. Missing price_id is rejected rather than silently disabling enrollment. No automatic retry.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model_alias", "price_id", "expected_version", "idempotency_key", "reason" ], "properties": { "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "price_id": { "type": [ "string", "null" ], "format": "uuid" }, "expected_version": { "type": "string", "pattern": "^[0-9]+$" }, "idempotency_key": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Current configuration or exact committed outcome", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision", "version", "model_alias", "price_id" ], "properties": { "revision": { "type": "string", "format": "uuid" }, "version": { "type": "string", "pattern": "^[0-9]+$" }, "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "price_id": { "type": [ "string", "null" ], "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Invalid model, reason or exact version" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting key, unknown workspace, missing balance account or incompatible price identity" }, "422": { "description": "Malformed body or missing explicit price_id" } }, "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "getRetailTextEnrollment", "summary": "Read own workspace retail pricing mode", "description": "Requires workspace read authority or platform administration. Current configuration only, no other-customer rules, procurement or usage. Absent saved enrollment means workspace pricing, version zero and null price_id. This does not establish an available route or spending permission. Internal references are API values, never display names. Cache-Control: no-store. Effective price is an advisory own-customer selection at server time under the workspace and price locks; null in workspace pricing mode. No other-customer rules are returned.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model_alias", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Current configuration or exact committed outcome", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "model_alias", "price_id", "version", "pricing_source", "effective_price" ], "properties": { "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "price_id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": "string", "pattern": "^[0-9]+$" }, "pricing_source": { "type": "string", "enum": [ "platform", "workspace" ] }, "effective_price": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_RetailSelection" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Invalid model alias" }, "401": { "description": "Authentication required" }, "404": { "description": "Workspace outside authority" }, "409": { "description": "Unknown authorized workspace" } }, "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/customers": { "get": { "operationId": "listRetailCustomerTargets", "summary": "List named companies for customer-specific promotions", "description": "Explicit platform administration only, independent of ordinary company membership. Includes companies without workspaces or currency accounts. Names, company creation timestamps for distinguishing repeated names, and routing-only company references; no balances, payment details, request content, Provider costs or credentials. UUID keyset order; default 50, maximum 100 companies. Pass next_after unchanged; missing cursor returns 409. Each page shares one bounded read snapshot; separate pages do not, so refresh for concurrent inserts before the cursor. No organization, workspace, account or policy is created. Discovery is not selling or spending authorization. Cache-Control no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Named company page without financial data", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_after" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "organization_id", "organization_name", "created_at" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Company creation time; not a billing or eligibility event." } } } }, "next_after": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid query or page size" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Missing company cursor" } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/standard-prices/models": { "get": { "operationId": "listRegisteredRetailModels", "summary": "List registered shared models for standard-price preparation", "description": "Explicit platform administration required. Includes registered nonpersonal vendor aliases and route-pool aliases even when disabled. Matches standard-price registration eligibility, not legacy workspace tariff availability. Personal vendor aliases are excluded. Validated video output configuration adds media choices (channel, resolutions, reference-video support and meter); absent, invalid or stale configuration returns media null. Registration is not qualified supply, customer selling eligibility or dispatch readiness. No credentials, upstream mappings or procurement prices. Sorted alias keyset; default 50, maximum 100. Pass next_after unchanged; unavailable cursor returns 409. Cursor and page share one database snapshot. Cache-Control no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Registered alias page, including disabled configuration", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_after" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "model_alias" ], "properties": { "model_alias": { "type": "string" }, "media": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "channel", "resolutions", "reference_video", "meter" ], "properties": { "channel": { "type": "string" }, "resolutions": { "type": "array", "items": { "type": "string" } }, "reference_video": { "type": "boolean" }, "meter": { "type": "string" } } } } } }, "next_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid page size or alias cursor" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Cursor no longer registered; restart pagination" } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/standard-prices": { "post": { "operationId": "publishRetailStandard", "summary": "Publish a platform standard selling-price revision", "description": "Explicit platform administration required; ordinary customer/Provider membership does not grant access. Independent model/currency/text-or-media identity; standard prices are independent of Provider purchase offers. expected_version is zero for a new identity and the last management version for replacement. All changes are versioned and attributed. Global UUID idempotency keys preserve canonical intent; exact retries return the original publication version, which may be older than current configuration. New standards take effect at commit and do not revoke still-eligible finite promotions. Existing request prices remain pinned; balances, supply qualification and routes are unchanged. Rates are decimal integer strings; token rates are nanounits per million tokens, fixed charges are nanounits, media quantities are exact rationals. Published standards supply default customer prices; publication alone does not establish supply qualification or model access.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current configuration or exact prior committed publication", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_RetailPublicationResult" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid exact amount, schedule, period or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting key/period, unknown identity/customer or unsupported publication" }, "422": { "description": "Malformed JSON or unsupported schedule shape" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_RetailStandardPublication" } } } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "listRetailStandards", "summary": "List current platform standard prices", "description": "Explicit platform administration required; ordinary customer/Provider membership does not grant access. Current selling revisions use one database snapshot, UUID keyset order. Advisory pricing_health compares those schedules with a subsequent current Provider quote snapshot; refresh after edits. Pass next_after unchanged; null means complete. Prices do not establish qualified inventory. No customer usage, credentials or numeric Provider costs; confidential relative cost diagnostics are platform-only. Internal references are API identifiers, never display names. Cache-Control: no-store.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current configuration or exact prior committed publication", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_RetailPriceRecord" } }, "next_after": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "data", "next_after" ] } } } }, "400": { "description": "Invalid exact amount, schedule, period or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting key/period, unknown identity/customer or unsupported publication" } }, "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/standard-prices/{price}/promotions": { "post": { "operationId": "publishRetailPromotion", "summary": "Publish one finite global or customer price", "description": "Explicit platform administration required; ordinary customer/Provider membership does not grant access. The explicit result references an exact immutable undiscounted standard revision of this price identity. Null customer_organization_id means global; a company reference means customer-specific. Inclusive start/exclusive end are exact UTC epoch-second strings, with finite end greater than start. Same-scope overlap is rejected; at selection an eligible customer rule overrides the global rule, never stacks. Every text category/fixed charge/context tier must preserve meaning and not increase; media retains dimensions, meter, unit, decimal scale, rounding and minimum and only discounts amount_units. Retained original baselines survive later standard updates. No existing request or job is repriced.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current configuration or exact prior committed publication", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_RetailPublicationResult" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid exact amount, schedule, period or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting key/period, unknown identity/customer or unsupported publication" }, "422": { "description": "Malformed JSON or unsupported schedule shape" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_RetailPromotionPublication" } } } }, "parameters": [ { "name": "price", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "listRetailPromotions", "summary": "Read promotion periods with complete retirement coverage", "description": "Explicit platform administration only. Each bounded page joins every returned promotion to its committed cutoff and original standard, regardless of history pagination. as_of is database UTC epoch seconds; state is scheduled, within_period or ended based on original start and the lesser of original end/cutoff. Within-period is temporal eligibility only: a global rule can be overridden by a customer rule, and this is not supply, enrollment, spending permission or a request snapshot. Current head version, original/results and names are from one statement snapshot. Other pages have separate snapshots/times. Newest publication version first; pass next_before unchanged. A cursor must name a promotion of this price; unavailable price/cursor returns 409. No procurement, credentials or financial mutations. Cache-Control no-store. The current standard and management version share this page snapshot; use them together for a new publication, then rely on server version comparison.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "price", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Promotion state at the returned observation time", "content": { "application/json": { "schema": { "type": "object", "required": [ "price_id", "model_alias", "currency", "current_version", "as_of", "next_before", "data", "standard" ], "properties": { "price_id": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "currency": { "type": "string" }, "current_version": { "type": "string" }, "as_of": { "type": "string" }, "next_before": { "type": [ "string", "null" ] }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "version", "baseline_version", "reason", "effective_from", "effective_until", "eligibility_until", "revision", "baseline_revision", "created_at", "baseline_published_at", "original_schedule", "schedule", "scope", "customer_organization_id", "customer_name", "customer_created_at", "retirement_effective_until", "state" ], "properties": { "version": { "type": "string" }, "baseline_version": { "type": "string" }, "reason": { "type": "string" }, "effective_from": { "type": "string" }, "effective_until": { "type": "string" }, "eligibility_until": { "type": "string" }, "revision": { "type": "string", "format": "uuid" }, "baseline_revision": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "baseline_published_at": { "type": "string", "format": "date-time" }, "original_schedule": { "$ref": "#/components/schemas/handler_operations_json_RetailSchedule" }, "schedule": { "$ref": "#/components/schemas/handler_operations_json_RetailSchedule" }, "scope": { "type": "string", "enum": [ "global", "customer" ] }, "customer_organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_name": { "type": [ "string", "null" ] }, "customer_created_at": { "type": [ "string", "null" ], "format": "date-time" }, "retirement_effective_until": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "scheduled", "within_period", "ended" ] }, "pricing_health": { "$ref": "#/components/schemas/handler_operations_json_PlatformPricingHealth" } } } }, "standard": { "$ref": "#/components/schemas/handler_operations_json_RetailPriceRecord" } } } } } }, "400": { "description": "Invalid limit or positive version cursor" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Price or promotion cursor unavailable; restart pagination" } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/standard-prices/{price}/promotions/{promotion}/retire": { "post": { "operationId": "retireRetailPromotion", "summary": "Append a promotion eligibility cutoff", "description": "Explicit platform administration required; ordinary customer/Provider membership does not grant access. Append-only explicit retirement, at most one cutoff for this promotion. Cutoff cannot extend its published end; a cutoff before its start cancels a future rule. Exact epoch-second strings and configuration version are required. Published schedules and already pinned operations/jobs stay immutable. This does not trigger a customer refund or change routing.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current configuration or exact prior committed publication", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_RetailPublicationResult" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid exact amount, schedule, period or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting key/period, unknown identity/customer or unsupported publication" }, "422": { "description": "Malformed JSON or unsupported schedule shape" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_RetailPromotionRetirement" } } } }, "parameters": [ { "name": "price", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promotion", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/pricing/standard-prices/{price}/history": { "get": { "operationId": "getRetailPriceHistory", "summary": "Read immutable standard and promotion history", "description": "Explicit platform administration required; ordinary customer/Provider membership does not grant access. Platform configuration history can include different customer-specific rules; never expose this projection to customers. Version keyset descending, pass next_before unchanged. Each page is one snapshot. Names are customer-company display values; UUIDs are routing references. No procurement or customer usage. Cache-Control: no-store.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current configuration or exact prior committed publication", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "price_id": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "currency": { "type": "string" }, "current_version": { "type": "string", "pattern": "^[0-9]+$" }, "current_revision": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_RetailHistoryEntry" } }, "next_before": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } }, "required": [ "price_id", "model_alias", "currency", "current_version", "current_revision", "data", "next_before" ] } } } }, "400": { "description": "Invalid exact amount, schedule, period or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting key/period, unknown identity/customer or unsupported publication" } }, "parameters": [ { "name": "price", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/standard-prices/{price}/preview": { "get": { "operationId": "previewRetailPrice", "summary": "Preview a customer applicable price", "description": "Explicit platform administration required; ordinary customer/Provider membership does not grant access. Advice only: does not enroll a workspace, reserve, dispatch or bind a request. Resolve at server time after the price identity lock, customer promotion then global then current standard. Exposes only this customer selection, not other customer rules. current_standard_revision may differ from the retained promotion baseline. Actual admission must select and pin in its transaction; never use preview as settlement evidence. Exact selected_at is UTC epoch seconds. Cache-Control: no-store.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current configuration or exact prior committed publication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_RetailSelection" } } } }, "400": { "description": "Invalid exact amount, schedule, period or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Stale version, conflicting key/period, unknown identity/customer or unsupported publication" } }, "parameters": [ { "name": "price", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/grants/issued": { "get": { "operationId": "listIssuedCustomerBalanceGrants", "summary": "List issued noncash gifts and corrections", "description": "Platform-only immutable gift history, including gifts predating durable preparation. Original issuance remains unchanged; correction is separate. Ordered by immutable creation time and reference. Follow next_before; no mutation or automatic retry. Reasons and actor labels remain platform-only. Internal references are routing metadata, never product labels.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Issued gifts and their correction, if any", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_before" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "amount_nanos", "reason", "created_at", "currency", "correction" ], "properties": { "id": { "type": "string", "format": "uuid" }, "amount_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "correction": { "type": [ "object", "null" ], "required": [ "id", "amount_nanos", "reason", "created_at", "actor_kind", "actor_label" ], "properties": { "id": { "type": "string", "format": "uuid" }, "amount_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "operator" ] }, "actor_label": { "type": "string" } } } } } }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid currency or page size" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Cursor is unavailable or out of scope" } }, "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/grants/{grant}": { "get": { "operationId": "getIssuedCustomerBalanceGrant", "summary": "Read one original noncash gift and its correction", "description": "Platform-only current snapshot of one original gift and its immutable correction. Use to recover a lost correction response. An absent correction in this read does not prove an in-flight request failed; retry only the exact original correction input and key. No mutation.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "grant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Issued gifts and their correction, if any", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "amount_nanos", "reason", "created_at", "currency", "correction" ], "properties": { "id": { "type": "string", "format": "uuid" }, "amount_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "correction": { "type": [ "object", "null" ], "required": [ "id", "amount_nanos", "reason", "created_at", "actor_kind", "actor_label" ], "properties": { "id": { "type": "string", "format": "uuid" }, "amount_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "operator" ] }, "actor_label": { "type": "string" } } } } } } } } } }, "400": { "description": "Invalid currency or page size" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "No issued gift in this company and currency" }, "409": { "description": "Cursor is unavailable or out of scope" } }, "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/grants/{grant}/correction": { "post": { "operationId": "correctUnusedCustomerBalanceGrant", "summary": "Correct a wholly unused noncash gift", "description": "Explicit platform administration only. Corrects the full original gift on an account with no paid request history, consumption, refunds, open reservations or unknown financial sources. Atomically appends a negative balance adjustment and an immutable noncash correction with original grant, reason and authenticated actor. Does not change credit, create a merchant refund, cash receipt, consumption allowance or revenue. Partial, consumed, uncertain, duplicate or changed idempotency intent is refused. Exact same company/currency/grant/amount/reason/key retry returns the original correction. On uncertain response inspect issued gifts and retry only the exact original input, never replace the key. No automatic retry.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "grant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "amount_nanos", "reason", "idempotency_key" ], "properties": { "amount_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Correction committed or identical original returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "description": "Invalid exact amount, currency or reason" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Gift is unavailable, not wholly unused, has uncertain sources or open liabilities, or intent conflicts" } }, "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/grants/prepare": { "post": { "operationId": "prepareCustomerBalanceGrant", "summary": "Prepare a durable noncash gift intent", "description": "Explicit platform administration only. Saves immutable amount, reason, currency, policy, authenticated actor and company-scoped idempotency key. Preparation posts no funds, revenue, receipt, debt application or reservation. Exact retries return the same intent; changed reuse conflicts. Existing matching grants can be recovered as issued. Publish through grantCustomerBalance with this saved input and original key. Prepared is not proof that an in-flight publication failed. Never invent another key because a response was lost. No automatic issuance. Internal references are not product labels.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "responses": { "200": { "description": "Durable intent state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "idempotency_key", "currency", "amount_nanos", "reason", "created_at", "application_policy", "status", "result" ], "properties": { "id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "amount_nanos": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "application_policy": { "type": "string", "enum": [ "future_only", "unpaid_credit_first" ] }, "status": { "type": "string", "enum": [ "prepared", "issued" ] }, "result": { "type": [ "object", "null" ], "required": [ "id", "application_policy", "applied_to_credit_nanos", "retained_for_future_consumption_nanos" ], "properties": { "application_policy": { "type": "string", "enum": [ "future_only", "unpaid_credit_first" ] }, "applied_to_credit_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "retained_for_future_consumption_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Original grant amount retained for future consumption at issuance, not current spendable balance." }, "id": { "type": "string", "format": "uuid" } } } } } } } } } }, "400": { "description": "Invalid amount, currency or page" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Intent conflict, unknown company or invalid cursor" }, "422": { "description": "Malformed body or unsupported application policy" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "amount_nanos", "reason", "idempotency_key" ], "properties": { "application_policy": { "type": "string", "enum": [ "future_only", "unpaid_credit_first" ], "default": "future_only" }, "amount_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive exact currency nanounits, maximum 9223372036854775807." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Trimmed justification without control characters." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/grants/prepared": { "get": { "operationId": "listPreparedCustomerBalanceGrants", "summary": "Recover saved noncash grant publication intents", "description": "Explicit platform administration only. Currency-scoped immutable intents newest first by creation time and UUID. Follow next_before as before; limit defaults to 50, maximum 100. A cursor outside this company/currency conflicts. Each page uses a bounded read snapshot; pages are live, not a cross-page snapshot. Issued derives from the committed matching grant; result is original issuance allocation, not current spendable balance. Prepared never proves an in-flight publication failed and never adds capacity. Reasons are platform-only. No cash references, customer content or credentials. Cache-Control no-store. Saved intent survives browser changes.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Durable intent state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_before" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "idempotency_key", "currency", "amount_nanos", "reason", "created_at", "application_policy", "status", "result" ], "properties": { "id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "amount_nanos": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "application_policy": { "type": "string", "enum": [ "future_only", "unpaid_credit_first" ] }, "status": { "type": "string", "enum": [ "prepared", "issued" ] }, "result": { "type": [ "object", "null" ], "required": [ "id", "application_policy", "applied_to_credit_nanos", "retained_for_future_consumption_nanos" ], "properties": { "application_policy": { "type": "string", "enum": [ "future_only", "unpaid_credit_first" ] }, "applied_to_credit_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "retained_for_future_consumption_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Original grant amount retained for future consumption at issuance, not current spendable balance." }, "id": { "type": "string", "format": "uuid" } } } } } }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid amount, currency or page" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Intent conflict, unknown company or invalid cursor" } }, "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/grants/prepared/{key}": { "get": { "operationId": "getPreparedCustomerBalanceGrant", "summary": "Read original noncash gift intent by idempotency key", "description": "Explicit platform administration only. Exact company/currency/key read of saved intent and committed grant. Missing intent returns 404. Issued result contains original allocation; prepared means no matching grant in this snapshot, not proof an in-flight publication failed. Retry saved exact input with original key. Read creates no funds. Cache-Control no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Durable intent state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "idempotency_key", "currency", "amount_nanos", "reason", "created_at", "application_policy", "status", "result" ], "properties": { "id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "amount_nanos": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "application_policy": { "type": "string", "enum": [ "future_only", "unpaid_credit_first" ] }, "status": { "type": "string", "enum": [ "prepared", "issued" ] }, "result": { "type": [ "object", "null" ], "required": [ "id", "application_policy", "applied_to_credit_nanos", "retained_for_future_consumption_nanos" ], "properties": { "application_policy": { "type": "string", "enum": [ "future_only", "unpaid_credit_first" ] }, "applied_to_credit_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "retained_for_future_consumption_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Original grant amount retained for future consumption at issuance, not current spendable balance." }, "id": { "type": "string", "format": "uuid" } } } } } } } } } }, "400": { "description": "Invalid amount, currency or page" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "No saved intent for this company/currency/key" }, "409": { "description": "Intent conflict, unknown company or invalid cursor" } }, "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/platform/customer-accounts": { "get": { "operationId": "listPlatformCustomerAccounts", "summary": "Discover named customer accounts for platform financial administration", "description": "Explicit platform administration only, independent of ordinary company membership. Named companies and their current currency balance summaries; companies without accounts have an empty accounts array. No payment references, transactions, customer request content, Provider costs or credentials. Shares customer balance arithmetic: available equals posted balance plus approved credit minus outstanding request liability. Approval is not a cash receipt. UUID references are routing-only, never display labels. Company UUID keyset order; limit defaults to 50, maximum 100 companies. Pass next_after unchanged as after; missing cursor returns 409. Each page has one bounded read snapshot, separate pages do not share it; concurrent inserts before the cursor require refreshing. No funds, accounts or policies are created. Cache-Control no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Named company account page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_after" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "organization_id", "organization_name", "accounts" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "required": [ "currency", "balance_nanos", "reserved_nanos", "outstanding_nanos", "available_nanos", "credit_limit_nanos", "policy_revision", "warning_threshold_nanos", "low_balance", "posted_credit_exhausted" ], "properties": { "currency": { "type": "string" }, "balance_nanos": { "type": "string" }, "reserved_nanos": { "type": "string" }, "outstanding_nanos": { "type": "string" }, "available_nanos": { "type": "string" }, "credit_limit_nanos": { "type": "string" }, "policy_revision": { "type": "string" }, "warning_threshold_nanos": { "type": [ "string", "null" ] }, "low_balance": { "type": "boolean" }, "posted_credit_exhausted": { "type": "boolean" } } } } } } }, "next_after": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid query or page size" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Missing company cursor" } }, "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/financial-summary": { "get": { "operationId": "getCustomerFinancialSummary", "summary": "Read platform customer revenue and cash receipt summary", "description": "Explicit platform administrator only; no customer or Provider access. One database snapshot, configured currency and UTC rolling posting interval [from, until), 7/30/90 days or explicit calendar bounds. Confirmed text/media charges use their immutable charge posting time; customer refunds, grants and cash receipts use their own posting times. This differs from the commercial dispatch cohort. Personal-funded operations, durable personal attempt bindings and current personal-owned Provider offer credentials are excluded from consumption and related refunds. Revenue is nominal consumption minus consumed gift allowance and non-gift refunds; explicit late-grant applications post sales allowance at application time, while their refund restoration is already part of refund gift allocation and is not posted twice; non-gift can be prepaid or credit-backed. Issuing a gift or collecting a credit repayment never creates consumption revenue. Missing or legacy-unknown consumption allocation leaves revenue and total allowance null; known subtotals are partial. Uncovered nominal includes both charge and refund amounts as positive coverage exposure. A zero-charge record is known zero. Net allowance/revenue may be negative when refunds relate to an earlier interval. Verified cash receipt records remain independent; potentially overlapping legacy invoice and funding references leave the combined receipt total null. Funding reversal records do not attest an external cash refund transfer. No procurement prices, customer identifiers, credentials or content. The balance_credit_sources object is a point-in-time company wallet cash/credit provenance view at as_of, independent of the selected posting interval and external invoice receivables. Verified cash repayments reduce outstanding credit without creating revenue. Missing historical sources, unclassified adjustments or funding reversal ambiguity withhold complete prepaid cash and outstanding credit; known subtotals include only wholly covered accounts. Aggregate read only; does not initiate merchant operations. Cache-Control: no-store. This operational reconciliation report is not a closed general ledger or tax statement.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "currency", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Current posting summary, unknown totals explicitly null", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "days", "from", "until", "nominal_consumption_nanos", "customer_refunds_nanos", "known_revenue_subtotal_nanos", "known_gift_allowance_subtotal_nanos", "uncovered_entries", "uncovered_nominal_nanos", "balance_funding_receipts_nanos", "simulated_funding_receipts_nanos", "external_invoice_receipts_nanos", "cash_receipt_reference_conflicts", "recorded_funding_reversals_nanos", "issued_gifts_nanos", "corrected_unused_gifts_nanos", "recognized_revenue_nanos", "consumed_gift_allowance_nanos", "balance_credit_sources", "verified_cash_receipts_nanos" ], "properties": { "balance_credit_sources": { "type": "object", "required": [ "as_of", "uncovered_accounts", "simulated_funding_accounts", "prepaid_cash_nanos", "outstanding_credit_nanos", "known_prepaid_cash_subtotal_nanos", "known_outstanding_credit_subtotal_nanos" ], "properties": { "simulated_funding_accounts": { "type": "string", "pattern": "^[0-9]+$", "description": "Wallets with immutable simulated receipts. Historical mixed funding allocations remain unknown rather than being reported as cash." }, "as_of": { "type": "string", "format": "date-time" }, "uncovered_accounts": { "type": "string", "pattern": "^[0-9]+$" }, "prepaid_cash_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "outstanding_credit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "known_prepaid_cash_subtotal_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "known_outstanding_credit_subtotal_nanos": { "type": "string", "pattern": "^[0-9]+$" } } }, "currency": { "type": "string" }, "days": { "type": "integer" }, "from": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "nominal_consumption_nanos": { "type": "string", "pattern": "^-?[0-9]+$" }, "customer_refunds_nanos": { "type": "string", "pattern": "^-?[0-9]+$" }, "known_revenue_subtotal_nanos": { "type": "string", "pattern": "^-?[0-9]+$" }, "known_gift_allowance_subtotal_nanos": { "type": "string", "pattern": "^-?[0-9]+$" }, "uncovered_entries": { "type": "string", "pattern": "^-?[0-9]+$" }, "uncovered_nominal_nanos": { "type": "string", "pattern": "^-?[0-9]+$" }, "balance_funding_receipts_nanos": { "type": "string", "pattern": "^-?[0-9]+$" }, "simulated_funding_receipts_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Simulated checkout funding in this posting interval, excluded from verified cash regardless of current plugin settings." }, "external_invoice_receipts_nanos": { "type": "string", "pattern": "^-?[0-9]+$" }, "cash_receipt_reference_conflicts": { "type": "string", "pattern": "^-?[0-9]+$" }, "recorded_funding_reversals_nanos": { "type": "string", "pattern": "^-?[0-9]+$", "description": "Ledger reversals of verified funding; not proof of an external refund transfer." }, "corrected_unused_gifts_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Corrections of wholly unused noncash gifts in this interval; separate from gross issuance, cash refunds and revenue." }, "issued_gifts_nanos": { "type": "string", "pattern": "^-?[0-9]+$", "description": "Noncash grants issued in this interval. No income or promotional expense is recognized by issuance." }, "recognized_revenue_nanos": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+$", "description": "Confirmed consumption less consumed gifts and non-gift refunds. Null if any source allocation is missing or unknown." }, "consumed_gift_allowance_nanos": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+$" }, "verified_cash_receipts_nanos": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+$", "description": "Verified real balance funding plus recorded full external invoice payments; excludes simulated checkout receipts. Null for ambiguous duplicate references. Separate from consumption and revenue." } } } } } }, "400": { "description": "Invalid period or unknown currency" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" } }, "x-niu-implementation": "implemented", "tags": [ "Financial reports" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/grants": { "post": { "operationId": "grantCustomerBalance", "summary": "Issue administrator noncash customer credit", "description": "Explicit platform administration required. Atomically records a positive gift and its immutable noncash memorandum, reason and authenticated actor. Issuance is not a payment receipt or revenue. application_policy defaults to future_only for compatibility. Explicit unpaid_credit_first applies the new gift against exact known unpaid credit charges as sales allowance, reducing revenue and receivable without repricing the charge or changing Provider payable. Remaining gift funds future consumption. Unknown debt provenance rejects the complete publication. Refunds restore the corresponding gift before credit or cash, without evidence of an external cash transfer. Credit policy is unchanged. Exact retries using the same company-scoped idempotency key, currency, amount, reason and application policy return the original grant; differing reuse conflicts. Historical financial entries are never reclassified. No automatic retry.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "amount_nanos", "reason", "idempotency_key" ], "properties": { "application_policy": { "type": "string", "enum": [ "future_only", "unpaid_credit_first" ], "default": "future_only" }, "amount_nanos": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive exact currency nanounits, maximum 9223372036854775807." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Trimmed justification without control characters." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Gift issued, or identical previously committed gift returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "application_policy", "applied_to_credit_nanos", "retained_for_future_consumption_nanos" ], "properties": { "application_policy": { "type": "string", "enum": [ "future_only", "unpaid_credit_first" ] }, "applied_to_credit_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "retained_for_future_consumption_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Original grant amount retained for future consumption at issuance, not current spendable balance." }, "id": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "description": "Invalid exact amount, currency or reason" }, "401": { "description": "Authentication required" }, "403": { "description": "Explicit platform administration required" }, "409": { "description": "Unknown company, conflicting idempotency intent or uncovered debt sources for unpaid_credit_first" }, "422": { "description": "Malformed request body or unsupported application policy" } }, "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/commercial-position": { "get": { "operationId": "getCommercialPosition", "summary": "Compare installation commercial Provider positions", "description": "Explicit late-grant applications against a cohort charge reduce net revenue and increase sales allowance without repricing nominal charges or Provider payable. Their refund restoration is included in recorded refund gift allocation once. Explicit platform administrator only. One current database snapshot for a UTC rolling dispatch interval [from, until), 7/30/90 days or explicit calendar bounds, and a configured currency. Personal owner-funded supply is excluded. Each row is a Provider, customer-facing model alias and currency; route-pool candidates appear as distinct offers. Customer charges are confirmed retail charges, not external cash receipts. Provider settlement links record confirmed external payments, not automatic transfers. Null monetary values mean unavailable, never zero. Margin is customer charge minus Provider earning over matched attempts only, withheld when any potentially executed attempt is unresolved. Cost is separately reported over matched attempts and withheld if any matching cost entry is missing; cost coverage counts are explicit. Empty offers means no quote in the selected currency. No customer identity, request identity, body or credential is returned. Read-only; never changes routing or model. Identifiers are API references and must not become product labels. Cache-Control: no-store. Net customer revenue excludes consumed gifts and recorded customer refunds for this dispatch cohort; it is not cash receipts or posting-period income. Missing charge/source coverage leaves the full net revenue unavailable. Gift allowance is a sales allowance, not an operating expense. net_contribution_nanos subtracts matched Provider earnings from net customer revenue, never known upstream expense again. Legacy margin_nanos remains nominal charge minus Provider earnings and must not be labeled income or net profit. Personal funding is excluded independently of current vendor ownership. customer_refunds_nanos records associated balance-credit restorations for the dispatch cohort, not external cash refund transfers. When fully covered, nominal charge minus recorded refunds minus net consumed-gift allowance equals net customer revenue. Each known customer/Provider/cost ledger currency is represented independently, without conversion. known_upstream_cost_subtotal_nanos sums only actual recorded costs in the selected currency, independently of same-currency customer/Provider matching. It is a known partial subtotal, not proof of complete expense coverage; absent records remain null. upstream_cost_recorded_attempts counts these recorded cost entries. Legacy cost_nanos and cost_known_attempts retain their matched-attempt coverage semantics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "currency", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Commercial positions", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "days", "from", "until", "data" ], "properties": { "currency": { "type": "string" }, "days": { "type": "integer" }, "from": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "type": "object", "properties": { "supplier_id": { "type": "string", "format": "uuid" }, "supplier_name": { "type": "string" }, "model_alias": { "type": "string" }, "currency": { "type": "string" }, "offers": { "type": "array", "items": { "type": "object", "properties": { "offer_id": { "type": "string", "format": "uuid" }, "route_alias": { "type": "string" }, "revision": { "type": "string", "format": "uuid" }, "rate_kind": { "type": "string", "enum": [ "text", "media" ] }, "prompt_rate": { "type": [ "string", "null" ] }, "completion_rate": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "paused", "unqualified", "qualified" ] }, "media_rates": { "type": "array", "items": { "type": "object" } } } } }, "customer_cash_applied_nanos": { "type": [ "string", "null" ], "description": "Verified wallet cash attributed to cohort charges plus repayments minus cash balance restorations. Not posting-period receipts or proof of an external refund transfer. Gifts are excluded." }, "customer_outstanding_credit_nanos": { "type": [ "string", "null" ], "description": "Remaining wallet credit attributed to cohort charges after repayment, gift applications and credit refunds. Not external invoice receivables." }, "cash_source_uncovered_attempts": { "type": "string", "description": "Charged attempts lacking complete current wallet provenance. Full cash and outstanding credit are withheld for uncovered or unresolved traffic." }, "customer_charge_nanos": { "type": [ "string", "null" ] }, "earning_nanos": { "type": [ "string", "null" ] }, "settled_earning_nanos": { "type": [ "string", "null" ] }, "unsettled_earning_nanos": { "type": [ "string", "null" ] }, "cost_nanos": { "type": [ "string", "null" ] }, "margin_nanos": { "type": [ "string", "null" ] }, "unresolved_attempts": { "type": "string", "pattern": "^[0-9]+$" }, "matched_attempts": { "type": "string", "pattern": "^[0-9]+$" }, "cost_known_attempts": { "type": "string", "pattern": "^[0-9]+$" }, "net_customer_revenue_nanos": { "type": [ "string", "null" ] }, "consumed_gift_allowance_nanos": { "type": [ "string", "null" ] }, "net_contribution_nanos": { "type": [ "string", "null" ] }, "revenue_uncovered_attempts": { "type": "string" }, "customer_refunds_nanos": { "type": [ "string", "null" ] }, "known_upstream_cost_subtotal_nanos": { "type": [ "string", "null" ] }, "upstream_cost_recorded_attempts": { "type": "string" } }, "required": [ "supplier_id", "supplier_name", "model_alias", "currency", "offers", "customer_charge_nanos", "earning_nanos", "settled_earning_nanos", "unsettled_earning_nanos", "cost_nanos", "margin_nanos", "unresolved_attempts", "matched_attempts", "cost_known_attempts", "net_customer_revenue_nanos", "consumed_gift_allowance_nanos", "net_contribution_nanos", "revenue_uncovered_attempts", "customer_refunds_nanos", "known_upstream_cost_subtotal_nanos", "upstream_cost_recorded_attempts" ] } } } } } } }, "400": { "description": "Invalid period or unknown currency" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Platform administration required" } }, "tags": [ "Financial reports" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/projects/{project}/media/operations": { "get": { "operationId": "listHistoricalWorkspaceProviderAssetOperations", "summary": "List historical native material operations", "description": "Current authenticated workspace Read permission required. Native operation history is workspace-shared. Reads only immutable saved scope, original key, model and optional group/account context; does not authenticate or reenable an expired or revoked inference key, consult current model grants or catalog, select a default account, create a Provider client, call the Provider or retry a mutation. Safe Niu references and saved diagnostic metadata only; private Provider identifiers, source URLs, credentials and procurement prices are excluded. Prepared is not dispatch permission; unknown remains uncertain. A missing record does not prove an original request was never sent. Deleted resources retain operation history. Without context_group_id, includes all saved account bindings for this original key and model, without claiming they share an account. Newest-first creation time and UUID tie-breaker with exclusive cursor pagination. Validation and page share one bounded database snapshot; keep all filters fixed. This is a live history, not a fixed export snapshot.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Original saved workspace key reference; expiration or revocation does not restore or remove historical read permission." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Exact recorded Niu model alias. Never resolves a default Provider account." }, { "name": "context_group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Existing scoped Niu group recorded under this original key/model; pins its immutable account, credential revision, model revision and upstream mapping without exposing those fields." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Cursor from these exact original-key/model/account filters. Unknown or foreign cursors are refused." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Saved workspace operation metadata", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid query, UUID or limit" }, "401": { "description": "Invalid or expired member session" }, "403": { "description": "Current workspace Read denied" }, "404": { "description": "Operation absent from this exact binding" }, "409": { "description": "Foreign original key, account context or pagination cursor" }, "503": { "description": "Bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/media/operations/{id}": { "get": { "operationId": "getHistoricalWorkspaceProviderAssetOperation", "summary": "Read historical native material operations", "description": "Current authenticated workspace Read permission required. Native operation history is workspace-shared. Reads only immutable saved scope, original key, model and optional group/account context; does not authenticate or reenable an expired or revoked inference key, consult current model grants or catalog, select a default account, create a Provider client, call the Provider or retry a mutation. Safe Niu references and saved diagnostic metadata only; private Provider identifiers, source URLs, credentials and procurement prices are excluded. Prepared is not dispatch permission; unknown remains uncertain. A missing record does not prove an original request was never sent. Deleted resources retain operation history. Without context_group_id, includes all saved account bindings for this original key and model, without claiming they share an account.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Original saved workspace key reference; expiration or revocation does not restore or remove historical read permission." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Exact recorded Niu model alias. Never resolves a default Provider account." }, { "name": "context_group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Existing scoped Niu group recorded under this original key/model; pins its immutable account, credential revision, model revision and upstream mapping without exposing those fields." } ], "responses": { "200": { "description": "Saved workspace operation metadata", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" } } } } } }, "400": { "description": "Invalid query, UUID or limit" }, "401": { "description": "Invalid or expired member session" }, "403": { "description": "Current workspace Read denied" }, "404": { "description": "Operation absent from this exact binding" }, "409": { "description": "Foreign original key, account context or pagination cursor" }, "503": { "description": "Bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/media/operations/by-idempotency/{id}": { "get": { "operationId": "getHistoricalWorkspaceProviderAssetOperationByIdempotency", "summary": "Read historical native material operations", "description": "Current authenticated workspace Read permission required. Native operation history is workspace-shared. Reads only immutable saved scope, original key, model and optional group/account context; does not authenticate or reenable an expired or revoked inference key, consult current model grants or catalog, select a default account, create a Provider client, call the Provider or retry a mutation. Safe Niu references and saved diagnostic metadata only; private Provider identifiers, source URLs, credentials and procurement prices are excluded. Prepared is not dispatch permission; unknown remains uncertain. A missing record does not prove an original request was never sent. Deleted resources retain operation history. Without context_group_id, includes all saved account bindings for this original key and model, without claiming they share an account. The path id is the original canonical nonnil request idempotency UUID, not an operation reference.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Original saved workspace key reference; expiration or revocation does not restore or remove historical read permission." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Exact recorded Niu model alias. Never resolves a default Provider account." }, { "name": "context_group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Existing scoped Niu group recorded under this original key/model; pins its immutable account, credential revision, model revision and upstream mapping without exposing those fields." } ], "responses": { "200": { "description": "Saved workspace operation metadata", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" } } } } } }, "400": { "description": "Invalid query, UUID or limit" }, "401": { "description": "Invalid or expired member session" }, "403": { "description": "Current workspace Read denied" }, "404": { "description": "Operation absent from this exact binding" }, "409": { "description": "Foreign original key, account context or pagination cursor" }, "503": { "description": "Bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/operations/prepare": { "post": { "operationId": "prepareProviderAssetOperation", "summary": "Prepare a native material operation without dispatch", "description": "Current selected key, exact model/account/channel and workspace Write authority required. Safe Niu references only; no Provider identifiers, source URLs, credentials or procurement prices returned. Commits the existing immutable request hash and resource binding without a Provider call. Same UUID and changed payload returns409. Full original payload is required for later dispatch; source URLs are not retained. Preparation is not Provider readiness.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Original canonical nonnil request UUID." } ], "responses": { "200": { "description": "Saved operation metadata", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "group", "asset" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" }, "group": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroup" }, { "type": "null" } ] }, "asset": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaAsset" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid input or missing idempotency UUID" }, "401": { "description": "Missing expired or revoked key/session" }, "403": { "description": "Workspace Write or key policy refused" }, "404": { "description": "Owned preparation or model unavailable" }, "409": { "description": "Changed canonical input, stale revision, route or operation state conflict" }, "413": { "description": "Request exceeds16KiB" }, "501": { "description": "Channel unsupported" }, "503": { "description": "Storage or configuration unavailable" } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperationInput" } } } }, "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/media/operations/{id}/dispatch": { "post": { "operationId": "dispatchProviderAssetOperation", "summary": "Explicitly dispatch an existing native material preparation", "description": "Current selected key, exact model/account/channel and workspace Write authority required. Safe Niu references only; no Provider identifiers, source URLs, credentials or procurement prices returned. Requires an already saved operation matching the original idempotency UUID and full canonical input. Never creates a missing preparation. Atomic prepared-to-unknown claim precedes a single Provider call; unknown and terminal records never redispatch. No automatic retries.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Original canonical nonnil request UUID." } ], "responses": { "202": { "description": "Saved operation metadata", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "group", "asset" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" }, "group": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroup" }, { "type": "null" } ] }, "asset": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaAsset" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid input or missing idempotency UUID" }, "401": { "description": "Missing expired or revoked key/session" }, "403": { "description": "Workspace Write or key policy refused" }, "404": { "description": "Owned preparation or model unavailable" }, "409": { "description": "Changed canonical input, stale revision, route or operation state conflict" }, "413": { "description": "Request exceeds16KiB" }, "501": { "description": "Channel unsupported" }, "503": { "description": "Storage or configuration unavailable" } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperationInput" } } } }, "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/media/operations/{id}/cancel": { "post": { "operationId": "cancelPreparedProviderAssetOperation", "summary": "Cancel an unclaimed native material preparation", "description": "Current selected key, exact model/account/channel and workspace Write authority required. Safe Niu references only; no Provider identifiers, source URLs, credentials or procurement prices returned. Only prepared can transition to not_sent; a not_sent replay is unchanged. Unknown or acknowledged returns409 and cannot be canceled. No Provider call. This key-scoped endpoint requires current original-key authority; use the workspace historical cancellation endpoint after key expiry or revocation.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved operation metadata", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" } } } } } }, "400": { "description": "Invalid input or missing idempotency UUID" }, "401": { "description": "Missing expired or revoked key/session" }, "403": { "description": "Workspace Write or key policy refused" }, "404": { "description": "Owned preparation or model unavailable" }, "409": { "description": "Changed canonical input, stale revision, route or operation state conflict" }, "413": { "description": "Request exceeds16KiB" }, "501": { "description": "Channel unsupported" }, "503": { "description": "Storage or configuration unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/media/operations/{id}/cancel": { "post": { "operationId": "cancelPreparedWorkspaceProviderAssetOperation", "summary": "Abandon an unclaimed native operation after key expiry", "description": "Current member workspace Write permission required, independent of inference-key expiry or revocation. Native operation history is workspace-shared. Exact workspace, Niu operation and immutable group model binding are checked under group-first locks. Only prepared becomes not_sent; unknown is never resolved, resent or canceled. No Provider client, calls, route reenabling or inference authority restoration. Repeated not_sent cancellation is unchanged. Original key and private account binding remain immutable.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preparation abandoned before claim", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "const": "not_sent" } } } } } } } }, "400": { "description": "Invalid path or query" }, "401": { "description": "Invalid member session" }, "403": { "description": "Current workspace Write denied" }, "409": { "description": "Unknown, acknowledged, foreign or mismatched model preparation" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/v1/media/operations": { "get": { "operationId": "list_operationsProviderAsset", "summary": "List saved Provider mutation operations", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Reads locally saved metadata only; unknown operation states require explicit reconciliation. This read never calls the Provider or retries a mutation. Records are workspace-shared under current selected-key authority and exact model/account binding. Unknown remains uncertain; prepared is a persisted state, not permission to retry. A missing record is not proof that the original request was never sent. Newest-first immutable creation time and UUID tie-breaker ordering. Resource deletion does not remove operation history. limit defaults to 50.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Cursor from this exact authorized model/account; invalid or mismatched cursor is rejected." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Bounded saved operation page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid model, UUID, limit or cursor" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/operations/by-idempotency/{id}": { "get": { "operationId": "get_operation_by_idempotencyProviderAsset", "summary": "Read a saved Provider operation by request idempotency UUID", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Reads locally saved metadata only; unknown operation states require explicit reconciliation. This read never calls the Provider or retries a mutation. Records are workspace-shared under current selected-key authority and exact model/account binding. Unknown remains uncertain; prepared is a persisted state, not permission to retry. A missing record is not proof that the original request was never sent.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Original canonical nonnil Idempotency-Key UUID, not the operation ID." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owned metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" } } } } } }, "400": { "description": "Invalid model, UUID, limit or cursor" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/video/draft": { "get": { "operationId": "getVideoComposerDraft", "x-niu-implementation": "implemented", "summary": "Read a mutable personal Video composer", "description": "One mutable actor-private Video composer per workspace. Operators are isolated; installation credentials share the installation actor. Read requires workspace Read permission. Absent state returns null payload and revision zero. Retention is 30 days after the last confirmed edit; expired content is hidden immediately and background maintenance erases it. Reads expose the expiry tombstone revision before maintenance. Saved key/model/reference identities are context only, including unavailable historical resources; they confer no current access or readiness. No inference, Provider calls, reservation, media reads or inspection occur.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Actor-private composer state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VideoComposerDraftResponse" } } } }, "401": { "description": "Missing or invalid administration/member authentication." }, "403": { "description": "Insufficient workspace permission or scope." }, "500": { "description": "Internal storage failure." }, "503": { "description": "Storage unavailable." } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/video/draft", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "saveVideoComposerDraft", "x-niu-implementation": "implemented", "summary": "Save or clear a mutable personal Video composer", "description": "One mutable actor-private Video composer per workspace. Operators are isolated; installation credentials share the installation actor. Read requires workspace Read permission. Absent state returns null payload and revision zero. Retention is 30 days after the last confirmed edit; expired content is hidden immediately and background maintenance erases it. Reads expose the expiry tombstone revision before maintenance. Saved key/model/reference identities are context only, including unavailable historical resources; they confer no current access or readiness. No inference, Provider calls, reservation, media reads or inspection occur. Write requires workspace Write permission and allowed browser Origin. Typed bounded partial composition may omit model/key/session and required model controls. Only the nine existing non-URL VideoSchema scalar control names are accepted; integer edits may remain strings. References use exact provider_asset/workspace_asset shapes, canonical nonnil Niu IDs and explicit workspace processing consent. No raw URL, inline media, short-lived ingestion, credential or billing fields are accepted. Key/reference metadata must belong to the workspace; session context must belong to the actor. Saving does not require an active historical key or grant action access. Full current schema, key/model eligibility, reference binding, consent and inspection remain explicit estimate/submission requirements. Null or omitted payload clears content while retaining the CAS revision. Stale revisions, including revisions predating expiry or clear, return 409. Workspace deletion refuses retained drafts; cleared/expired tombstones alone do not prevent empty-workspace deletion.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Actor-private composer state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VideoComposerDraftResponse" } } } }, "400": { "description": "Malformed or unknown fields, invalid bounds, control type, reference role, consent or canonical ID." }, "401": { "description": "Missing or invalid administration/member authentication." }, "403": { "description": "Insufficient permission, cross-workspace key/reference, unavailable actor session, or missing/disallowed browser Origin." }, "409": { "description": "Invalid or stale revision; no overwrite." }, "413": { "description": "Body exceeds 64 KiB." }, "500": { "description": "Internal storage failure." }, "503": { "description": "Storage unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VideoComposerDraftUpdate" } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/video/draft", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/v1/media/verifications": { "post": { "operationId": "createMediaVerificationSession", "summary": "Create upstream human verification session", "description": "Current workspace API key, model grant, composed workspace/key model and Provider policy, eligible published route and selectable credential required. Original immutable account/model binding is revalidated; original key identity binds encryption only, not workspace access control. Only configured fastrouter-actions-v1 channels are supported. Forwards only caller-supplied optional subject_name and return_url to the upstream H5 service. Exactly one creation follows a durable claim. All after-send failures remain unknown without automatic retry. A created session is not human completion or a local liveness approval. Token and H5 URL are encrypted and absent from ordinary metadata and logs.", "x-niu-implementation": "implemented", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical nonnil UUID; unchanged replay reads saved session without repeating creation." } ], "responses": { "202": { "description": "Saved session accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaVerificationSession" } } } } } }, "400": { "description": "Invalid fields or query" }, "401": { "description": "Missing, revoked or expired API key" }, "403": { "description": "Workspace/key policy refusal" }, "404": { "description": "Owned session or model not found" }, "409": { "description": "Changed input, stale route, expiry, unavailable token or capacity conflict" }, "413": { "description": "Body exceeds bounded size" }, "501": { "description": "Selected channel does not configure verification management" }, "503": { "description": "Credential, encrypted content or bounded storage unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model" ], "properties": { "model": { "type": "string" }, "subject_name": { "type": "string", "minLength": 1, "maxLength": 32 }, "return_url": { "type": "string", "format": "uri", "maxLength": 8192 } } } } } }, "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } }, "get": { "operationId": "listMediaVerificationSessions", "summary": "List saved verification sessions", "description": "Current workspace API key, model grant, composed workspace/key model and Provider policy, eligible published route and selectable credential required. Original immutable account/model binding is revalidated; original key identity binds encryption only, not workspace access control. Only configured fastrouter-actions-v1 channels are supported. Local owned metadata only; no global upstream discovery, H5 URL, token or raw response.", "x-niu-implementation": "implemented", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Owned verification metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_MediaVerificationSession" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid fields or query" }, "401": { "description": "Missing, revoked or expired API key" }, "403": { "description": "Workspace/key policy refusal" }, "404": { "description": "Owned session or model not found" }, "409": { "description": "Changed input, stale route, expiry, unavailable token or capacity conflict" }, "413": { "description": "Body exceeds bounded size" }, "501": { "description": "Selected channel does not configure verification management" }, "503": { "description": "Credential, encrypted content or bounded storage unavailable" } }, "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/verifications/{id}": { "get": { "operationId": "getMediaVerificationSession", "summary": "Read saved verification session", "description": "Current workspace API key, model grant, composed workspace/key model and Provider policy, eligible published route and selectable credential required. Original immutable account/model binding is revalidated; original key identity binds encryption only, not workspace access control. Only configured fastrouter-actions-v1 channels are supported. Local saved status only, with known expiry reflected; no token, H5 URL or upstream request.", "x-niu-implementation": "implemented", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owned verification metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaVerificationSession" } } } } } }, "400": { "description": "Invalid fields or query" }, "401": { "description": "Missing, revoked or expired API key" }, "403": { "description": "Workspace/key policy refusal" }, "404": { "description": "Owned session or model not found" }, "409": { "description": "Changed input, stale route, expiry, unavailable token or capacity conflict" }, "413": { "description": "Body exceeds bounded size" }, "501": { "description": "Selected channel does not configure verification management" }, "503": { "description": "Credential, encrypted content or bounded storage unavailable" } }, "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/verifications/{id}/refresh": { "post": { "operationId": "refreshMediaVerificationSession", "summary": "Refresh upstream verification session", "description": "Current workspace API key, model grant, composed workspace/key model and Provider policy, eligible published route and selectable credential required. Original immutable account/model binding is revalidated; original key identity binds encryption only, not workspace access control. Only configured fastrouter-actions-v1 channels are supported. Empty body only. One explicit bounded query for an active genuine saved token. Upstream resolution can create a group, so a durable query claim prevents concurrent or uncertain replay. In-flight or after-send uncertain queries are exposed as unknown. Genuine waiting/processing results permit a later explicit query. Other states return unchanged without an upstream call. Only actual decoded verified GroupId binds a person group; no fake completion or local detector.", "x-niu-implementation": "implemented", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owned verification metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaVerificationSession" } } } } } }, "400": { "description": "Invalid fields or query" }, "401": { "description": "Missing, revoked or expired API key" }, "403": { "description": "Workspace/key policy refusal" }, "404": { "description": "Owned session or model not found" }, "409": { "description": "Changed input, stale route, expiry, unavailable token or capacity conflict" }, "413": { "description": "Body exceeds bounded size" }, "501": { "description": "Selected channel does not configure verification management" }, "503": { "description": "Credential, encrypted content or bounded storage unavailable" } }, "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/media/verifications/{id}/link": { "get": { "operationId": "getMediaVerificationLink", "summary": "Get authenticated upstream verification link", "description": "Current workspace API key, model grant, composed workspace/key model and Provider policy, eligible published route and selectable credential required. Original immutable account/model binding is revalidated; original key identity binds encryption only, not workspace access control. Only configured fastrouter-actions-v1 channels are supported. Explicit authenticated disclosure of the genuine external H5 URL to the current authorized workspace. Known expiry is checked before disclosure; absent upstream expiry is not replaced with invented entitlement. Only waiting/processing sessions expose a link. No raw BytedToken field, anonymous NIU link or local biometric processing. Cache-Control no-store and Referrer-Policy no-referrer.", "x-niu-implementation": "implemented", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authorized upstream H5 handoff", "content": { "application/json": { "schema": { "type": "object", "required": [ "verification_url", "expires_at" ], "properties": { "verification_url": { "type": "string", "format": "uri" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "schema": { "type": "string", "const": "no-referrer" } } } }, "400": { "description": "Invalid fields or query" }, "401": { "description": "Missing, revoked or expired API key" }, "403": { "description": "Workspace/key policy refusal" }, "404": { "description": "Owned session or model not found" }, "409": { "description": "Changed input, stale route, expiry, unavailable token or capacity conflict" }, "413": { "description": "Body exceeds bounded size" }, "501": { "description": "Selected channel does not configure verification management" }, "503": { "description": "Credential, encrypted content or bounded storage unavailable" } }, "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/groups": { "post": { "operationId": "create_groupProviderAsset", "summary": "Create a Provider asset group", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Claims one durable operation before one upstream mutation. After-send errors retain unknown and never authorize automatic replay; accepted operation does not imply Provider processing readiness.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical nonnil UUID. Same key and unchanged input returns the saved operation without replaying its mutation." } ], "responses": { "202": { "description": "Saved operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetMutation" } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "name" ], "properties": { "model": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "maxLength": 300 } } } } } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } }, "get": { "operationId": "list_groupsProviderAsset", "summary": "List saved workspace Provider groups", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Lists only locally saved owned rows; it never performs a global Provider list request.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Owned metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroupPage" } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/groups/{id}": { "patch": { "operationId": "update_groupProviderAsset", "summary": "Update Provider group metadata", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Claims one durable operation before one upstream mutation. After-send errors retain unknown and never authorize automatic replay; accepted operation does not imply Provider processing readiness.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical nonnil UUID. Same key and unchanged input returns the saved operation without replaying its mutation." } ], "responses": { "202": { "description": "Saved operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetMutation" } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model" ], "properties": { "model": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "maxLength": 300 }, "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } }, "delete": { "operationId": "delete_groupProviderAsset", "summary": "Delete a Provider asset group", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Claims one durable operation before one upstream mutation. After-send errors retain unknown and never authorize automatic replay; accepted operation does not imply Provider processing readiness. Group deletion is destructive and includes its Provider assets.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical nonnil UUID. Same key and unchanged input returns the saved operation without replaying its mutation." }, { "name": "expected_revision", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "responses": { "202": { "description": "Saved operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetMutation" } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } }, "get": { "operationId": "get_groupProviderAsset", "summary": "Read a saved Provider group", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Reads locally saved metadata only; unknown operation states require explicit reconciliation.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owned metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroup" } } } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/groups/{id}/refresh": { "post": { "operationId": "refresh_groupProviderAsset", "summary": "Refresh one owned Provider group", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Performs one explicit read of the original owned Provider reference and saves validated metadata. This is not a generation or mutation retry. Successful identity-validated reads persist nullable observation metadata even while the resource status and original uncertain operation remain unknown. Unknown writes remain blocked; this read does not redispatch, infer write completion, acknowledge a delete from 404, discover an unknown creation ID or grant material reuse. Failed reads preserve the previous observation and its timestamp.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owned metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroup" } } } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/media/assets": { "post": { "operationId": "create_assetProviderAsset", "summary": "Create a Provider asset from a URL", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Claims one durable operation before one upstream mutation. After-send errors retain unknown and never authorize automatic replay; accepted operation does not imply Provider processing readiness.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical nonnil UUID. Same key and unchanged input returns the saved operation without replaying its mutation." } ], "responses": { "202": { "description": "Saved operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetMutation" } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "group_id", "url", "kind" ], "properties": { "model": { "type": "string" }, "group_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "maxLength": 8192, "format": "uri" }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "kind": { "type": "string", "enum": [ "image", "audio", "video" ] } } } } } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } }, "get": { "operationId": "list_assetsProviderAsset", "summary": "List saved workspace Provider assets", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Lists only locally saved owned rows; it never performs a global Provider list request.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Owned metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetPage" } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/assets/{id}": { "patch": { "operationId": "rename_assetProviderAsset", "summary": "Rename a Provider asset", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Claims one durable operation before one upstream mutation. After-send errors retain unknown and never authorize automatic replay; accepted operation does not imply Provider processing readiness.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical nonnil UUID. Same key and unchanged input returns the saved operation without replaying its mutation." } ], "responses": { "202": { "description": "Saved operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetMutation" } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "name" ], "properties": { "model": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } }, "delete": { "operationId": "delete_assetProviderAsset", "summary": "Delete a Provider asset", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Claims one durable operation before one upstream mutation. After-send errors retain unknown and never authorize automatic replay; accepted operation does not imply Provider processing readiness.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Canonical nonnil UUID. Same key and unchanged input returns the saved operation without replaying its mutation." }, { "name": "expected_revision", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } } ], "responses": { "202": { "description": "Saved operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetMutation" } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } }, "get": { "operationId": "get_assetProviderAsset", "summary": "Read a saved Provider asset", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Reads locally saved metadata only; unknown operation states require explicit reconciliation.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owned metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAsset" } } } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/assets/{id}/refresh": { "post": { "operationId": "refresh_assetProviderAsset", "summary": "Refresh one owned Provider asset", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Performs one explicit read of the original owned Provider reference and saves validated metadata. This is not a generation or mutation retry. Successful identity-validated reads persist nullable observation metadata even while the resource status and original uncertain operation remain unknown. Unknown writes remain blocked; this read does not redispatch, infer write completion, acknowledge a delete from 404, discover an unknown creation ID or grant material reuse. Failed reads preserve the previous observation and its timestamp.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owned metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAsset" } } } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/media/operations/{id}": { "get": { "operationId": "get_operationProviderAsset", "summary": "Read a saved Provider mutation operation", "description": "Requires a workspace inference API key, current model permissions, composed workspace/key model and Provider grants, an enabled selectable credential and eligible Provider or matching personal owner. Only the explicitly configured fastrouter-actions-v1 model channel is supported. Opaque Provider references, credentials, private source URLs and upstream raw responses are never returned. Reads locally saved metadata only; unknown operation states require explicit reconciliation.", "tags": [ "Media assets and verification" ], "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owned metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" } } } } } }, "400": { "description": "Malformed or unsupported request fields" }, "401": { "description": "Missing, expired or revoked API key" }, "403": { "description": "Workspace or key policy refuses access" }, "404": { "description": "Owned object or model unavailable" }, "409": { "description": "Changed input, stale revision, unresolved identity or route conflict" }, "413": { "description": "Request exceeds its bounded size" }, "501": { "description": "Selected channel does not support asset management" }, "502": { "description": "Provider read failed safely" }, "503": { "description": "Credential, capacity or bounded storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/media-detectors": { "get": { "operationId": "listWorkspaceMediaDetectors", "summary": "List workspace-authorized media inspection configurations", "description": "Returns only deployment-authorized audio/video configuration metadata for the requested workspace. Declared conditions and a fingerprint do not establish successful inspection or consent; policy activation and media task references remain unavailable. No service endpoint, credential, environment variable or foreign workspace configuration is exposed. This operation performs no external inspection.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Declared workspace media processing conditions", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "detector", "detector_revision", "configuration_fingerprint", "recipient", "region", "retention", "schema_version", "kind", "content_sent", "processing_guarantees", "timeout_ms", "maximum_encoded_bytes", "concurrency", "declared_unmetered", "policy_activation", "requires_supported_presentation_facts" ], "properties": { "detector": { "type": "string" }, "detector_revision": { "type": "string" }, "configuration_fingerprint": { "type": "string" }, "recipient": { "type": "string" }, "region": { "type": "string" }, "retention": { "type": "string" }, "schema_version": { "type": "integer", "enum": [ 3 ] }, "kind": { "type": "string", "enum": [ "audio", "video" ] }, "content_sent": { "type": "string", "enum": [ "exact_encoded_media_with_embedded_tracks" ] }, "processing_guarantees": { "type": "string", "enum": [ "declared_unverified" ] }, "timeout_ms": { "type": "integer", "minimum": 1, "maximum": 30000 }, "maximum_encoded_bytes": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "concurrency": { "type": "integer", "minimum": 1, "maximum": 4 }, "declared_unmetered": { "type": "boolean" }, "policy_activation": { "type": "boolean", "enum": [ false ] }, "requires_supported_presentation_facts": { "type": "boolean", "enum": [ true ] } } } } } } } } }, "401": { "description": "Invalid management credential; inference keys cannot access this operation" }, "403": { "description": "Insufficient workspace permission" }, "404": { "description": "Workspace not found" }, "503": { "description": "Authorization or storage unavailable" } }, "x-niu-implementation": "implemented", "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/assets": { "get": { "operationId": "listWorkspaceAssets", "summary": "List saved workspace materials", "description": "Member Read permission required. Scope is the selected workspace, not the creating actor. Lists active objects with metadata only, ordered by creation time then identity. limit defaults to 50 and must be 1–100. after must be an active asset in the same workspace and kind filter or conflicts. Follow next_cursor; separate pages are not a frozen snapshot. No ciphertext, actor identifier, Provider URI, procurement or dispatch approval is returned.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "image", "video", "audio" ] } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Scoped asset metadata; no private ciphertext or actor identifier.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "media_kind", "content_type", "content_sha256", "byte_length", "revision", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal routing reference; never display as a user label." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "media_kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "video/mp4", "video/webm", "audio/wav", "audio/mpeg", "audio/ogg" ] }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the immutable original bytes." }, "byte_length": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "source": { "type": [ "object", "null" ], "description": "Authorized original generation context. Null when absent or not visible to this actor; sharing a retained copy does not grant source access.", "additionalProperties": false, "required": [ "reference", "kind", "output", "model", "created_at" ], "properties": { "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" }, "kind": { "const": "video" }, "output": { "enum": [ "video", "last_frame" ] }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/assets", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "post": { "operationId": "uploadWorkspaceAsset", "summary": "Save a workspace material", "description": "Member Write permission required. Raw binary body with exact supported Content-Type and required name query; no multipart or base64 envelope. Authentication and a bounded upload slot precede body collection. Original bytes are immutable, encrypted with workspace/asset identity binding, limited to 8 MiB each and 256 MiB/256 active objects per workspace. Images undergo bounded pixel decoding; audio/video undergo local frame/container structural validation. This is not content-inspection approval, Provider upload, licensing evidence or inference authorization. Repeated uploads create distinct objects; uncertain clients should reconcile the library before repeating.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Trimmed nonblank name; at most 200 UTF-8 bytes after trimming; no control characters." } ], "responses": { "201": { "description": "Scoped asset metadata; no private ciphertext or actor identifier.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "media_kind", "content_type", "content_sha256", "byte_length", "revision", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal routing reference; never display as a user label." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "media_kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "video/mp4", "video/webm", "audio/wav", "audio/mpeg", "audio/ogg" ] }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the immutable original bytes." }, "byte_length": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "source": { "type": [ "object", "null" ], "description": "Authorized original generation context. Null when absent or not visible to this actor; sharing a retained copy does not grant source access.", "additionalProperties": false, "required": [ "reference", "kind", "output", "model", "created_at" ], "properties": { "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" }, "kind": { "const": "video" }, "output": { "enum": [ "video", "last_frame" ] }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "413": { "description": "Raw body exceeds 8 MiB." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "image/jpeg": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "image/webp": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "video/mp4": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "video/webm": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "audio/wav": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } }, "audio/ogg": { "schema": { "type": "string", "format": "binary", "minLength": 1, "maxLength": 8388608 } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/assets", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/assets/{asset}": { "get": { "operationId": "getWorkspaceAsset", "summary": "Read workspace material metadata", "description": "Member Read permission required. Returns one active scoped asset without ciphertext or internal actor information. Unknown, deleted or foreign-workspace asset is 404.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scoped asset metadata; no private ciphertext or actor identifier.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "media_kind", "content_type", "content_sha256", "byte_length", "revision", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal routing reference; never display as a user label." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "media_kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "video/mp4", "video/webm", "audio/wav", "audio/mpeg", "audio/ogg" ] }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the immutable original bytes." }, "byte_length": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "source": { "type": [ "object", "null" ], "description": "Authorized original generation context. Null when absent or not visible to this actor; sharing a retained copy does not grant source access.", "additionalProperties": false, "required": [ "reference", "kind", "output", "model", "created_at" ], "properties": { "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" }, "kind": { "const": "video" }, "output": { "enum": [ "video", "last_frame" ] }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/assets/{asset}", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "patch": { "operationId": "renameWorkspaceAsset", "summary": "Rename a saved workspace material", "description": "Member Write permission required. Requires the exact current revision as a canonical positive decimal string. Renaming changes display metadata and increments revision, never bytes, content hash or Provider authorization. Stale revision returns 409. A missing scoped asset is 404; a concurrent deletion may conflict.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scoped asset metadata; no private ciphertext or actor identifier.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "media_kind", "content_type", "content_sha256", "byte_length", "revision", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal routing reference; never display as a user label." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "media_kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "video/mp4", "video/webm", "audio/wav", "audio/mpeg", "audio/ogg" ] }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the immutable original bytes." }, "byte_length": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "source": { "type": [ "object", "null" ], "description": "Authorized original generation context. Null when absent or not visible to this actor; sharing a retained copy does not grant source access.", "additionalProperties": false, "required": [ "reference", "kind", "output", "model", "created_at" ], "properties": { "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" }, "kind": { "const": "video" }, "output": { "enum": [ "video", "last_frame" ] }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "expected_revision" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters." }, "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks." } } } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/assets/{asset}", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "delete": { "operationId": "deleteWorkspaceAsset", "summary": "Delete a saved workspace material", "description": "Member Write permission required. Optional expected_revision protects against deleting a newly renamed active object. Deletion marks metadata inactive, erases ciphertext and releases quota atomically. Repeat deletion of the same scoped deleted asset is idempotent 204. Unknown or foreign asset is 404. No upstream asset or existing inference job is deleted.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_revision", "in": "query", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "description": "Optional canonical positive i64 revision of the active asset." } ], "responses": { "204": { "description": "Scoped deletion committed or already deleted; no response body." }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/assets/{asset}", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/assets/{asset}/content": { "get": { "operationId": "downloadWorkspaceAsset", "summary": "Download saved workspace material bytes", "description": "Member Read permission required. Authenticates encrypted identity binding and checks byte length and SHA-256 before returning the original bytes. Safe fixed attachment filename, exact supported Content-Type, Cache-Control:no-store and X-Content-Type-Options:nosniff. Unknown/deleted/foreign asset is 404; decryption/integrity failure is a safe unavailable response. Does not make content approved for Provider processing.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Exact retained bytes with no-store/nosniff and safe attachment disposition.", "content": { "image/png": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "image/jpeg": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "image/webp": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "video/mp4": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "video/webm": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "audio/wav": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } }, "audio/ogg": { "schema": { "type": "string", "format": "binary", "maxLength": 8388608 } } } }, "400": { "description": "Malformed query/body, unsupported type, invalid media bytes, name, page size or revision." }, "401": { "description": "Missing/invalid member administrator authentication; inference keys do not manage materials." }, "403": { "description": "Authenticated principal lacks workspace scope or required Read/Write permission." }, "404": { "description": "Workspace or scoped active asset not found." }, "409": { "description": "Stale revision, unavailable cursor or serialized workspace quota exceeded." }, "503": { "description": "Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed." } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/assets/{asset}/content", "tags": [ "Workspace assets" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}": { "patch": { "operationId": "renameWorkspaceById", "summary": "Rename a workspace by identity", "description": "Compatibility alias for the existing organization/workspace endpoint, which remains supported. Authorization is checked before resolving the stored workspace organization; member scope filters the lookup and foreign or missing workspaces return 404. The existing handler rechecks authorization before mutation. Requires scoped workspace write access. Trims the saved name; no optimistic revision is accepted. Response matches the legacy rename endpoint. Unknown body properties retain legacy parser behavior.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved workspace identity and trimmed name.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } }, "400": { "description": "Invalid identifier or name." }, "401": { "description": "Authentication required." }, "403": { "description": "Required management permission is missing." }, "404": { "description": "Workspace missing or outside authorized scope." }, "415": { "description": "JSON content type required." }, "422": { "description": "Invalid JSON body shape." }, "503": { "description": "Storage unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Must contain non-whitespace text and be at most 200 UTF-8 bytes before trimming." } } } } } }, "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "delete": { "operationId": "deleteWorkspaceById", "summary": "Delete an empty workspace by identity", "description": "Compatibility alias for the existing organization/workspace endpoint, which remains supported. Authorization is checked before resolving the stored workspace organization; member scope filters the lookup and foreign or missing workspaces return 404. The existing handler rechecks authorization before mutation. Requires installation authority or company-level owner/member-management permission. Workspace-scoped owners are refused with 403 before lookup for their own scope; another workspace remains concealed with 404. Dependent business records prevent deletion with 409; no business history cascade is requested. Response is the same empty 204 as the legacy endpoint.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Workspace deleted; empty response body." }, "400": { "description": "Invalid identifier." }, "401": { "description": "Authentication required." }, "403": { "description": "Required management permission is missing." }, "404": { "description": "Workspace missing or outside authorized scope." }, "409": { "description": "Workspace retains dependent business records." }, "503": { "description": "Storage unavailable." } }, "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/dispatch-denials": { "get": { "operationId": "listGuardrailDispatchDenials", "summary": "Read latest 100 workspace dispatch policy exceptions", "description": "Workspace read access required. Metadata only, newest first, combining dispatch and batch-admission policy rejections. Eligibility/status denials are outside this coverage. No request content, credentials or internal event identifiers. Latest 100 only; not a complete audit export. Cache-Control: no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Declared metadata or synthetic result; Cache-Control: no-store", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "coverage" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "stage", "outcome", "coverage", "reason", "key_name", "workspace_policy_name", "key_policy_name", "workspace_revision", "key_policy_revision", "key_assignment_revision", "recorded_at" ], "properties": { "stage": { "type": "string", "enum": [ "dispatch", "batch_admission" ] }, "outcome": { "type": "string", "enum": [ "blocked" ] }, "coverage": { "type": "string", "enum": [ "model_provider_access", "policy_binding" ] }, "reason": { "type": "string", "enum": [ "access_denied", "input_binding_missing", "policy_changed" ] }, "key_name": { "type": "string" }, "workspace_policy_name": { "type": [ "string", "null" ] }, "key_policy_name": { "type": [ "string", "null" ] }, "workspace_revision": { "type": [ "integer", "null" ] }, "key_policy_revision": { "type": [ "integer", "null" ] }, "key_assignment_revision": { "type": [ "integer", "null" ] }, "recorded_at": { "type": "string", "format": "date-time" } } } }, "coverage": { "type": "string", "enum": [ "latest_100_dispatch_policy_exceptions" ] } } } } } }, "401": { "description": "Invalid management credential; inference credentials cannot access management endpoints" }, "403": { "description": "Insufficient workspace permission or installation administrator authorization" }, "503": { "description": "Authorization/storage unavailable" } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/guardrails/detectors/{detector}/preview": { "post": { "operationId": "previewGuardrailDetector", "summary": "Preview installation text detector transport", "description": "Installation administrator only. Explicit consent and the current configuration fingerprint are required before supplied synthetic text is sent to the configured external detector. Does not activate a detector or enforce a policy; no customer billing integration. A detector-unavailable result is a 200 indeterminate outcome, not proof of successful inspection. Cache-Control: no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "detector", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Declared metadata or synthetic result; Cache-Control: no-store", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome", "reason", "synthetic", "enforcement" ], "properties": { "outcome": { "type": "string", "enum": [ "clear", "matched", "indeterminate" ] }, "reason": { "type": "string" }, "synthetic": { "type": "boolean", "enum": [ true ] }, "enforcement": { "type": "boolean", "enum": [ false ] } } } } } }, "400": { "description": "Malformed JSON, unknown fields, invalid content or missing/stale explicit consent" }, "401": { "description": "Invalid management credential; inference credentials cannot access management endpoints" }, "403": { "description": "Insufficient workspace permission or installation administrator authorization" }, "404": { "description": "Configured detector not found" }, "503": { "description": "Authorization/storage unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "configuration_fingerprint", "text", "consent_to_external_processing" ], "properties": { "configuration_fingerprint": { "type": "string" }, "text": { "type": "string" }, "consent_to_external_processing": { "type": "boolean" } } } } } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/guardrails/detectors/{detector}": { "get": { "operationId": "getGuardrailDetectorDescription", "summary": "Read installation text detector processing declaration", "description": "Installation administrator only; workspace-scoped management credentials are forbidden. Returns declared processing conditions for reviewing explicit synthetic-test consent. Does not send content. Declarations are not verified processing guarantees. Cache-Control: no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "detector", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Declared metadata or synthetic result; Cache-Control: no-store", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "schema_version", "detector_revision", "configuration_fingerprint", "recipient", "region", "retention", "processing_guarantees", "content_sent", "credential_source", "timeout_ms", "concurrency", "max_text_bytes", "max_response_bytes", "external_charge", "customer_billing", "policy_activation" ], "properties": { "schema_version": { "type": "integer", "enum": [ 1 ] }, "detector_revision": { "type": "string" }, "configuration_fingerprint": { "type": "string" }, "recipient": { "type": "string" }, "region": { "type": "string" }, "retention": { "type": "string" }, "processing_guarantees": { "type": "string", "enum": [ "declared_unverified" ] }, "content_sent": { "type": "string", "enum": [ "synthetic_text" ] }, "credential_source": { "type": "string", "enum": [ "server_environment" ] }, "timeout_ms": { "type": "integer" }, "concurrency": { "type": "integer" }, "max_text_bytes": { "type": "integer" }, "max_response_bytes": { "type": "integer", "enum": [ 4096 ] }, "external_charge": { "type": "string", "enum": [ "unknown", "declared_unmetered" ] }, "customer_billing": { "type": "string", "enum": [ "not_integrated" ] }, "policy_activation": { "type": "boolean" } } } } } }, "401": { "description": "Invalid management credential; inference credentials cannot access management endpoints" }, "403": { "description": "Insufficient workspace permission or installation administrator authorization" }, "404": { "description": "Configured detector not found" }, "503": { "description": "Authorization/storage unavailable" } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/detector-decisions": { "get": { "operationId": "listInputDetectorDecisions", "summary": "Read latest 100 workspace input detector decisions", "description": "Workspace read access required. Metadata only, newest first, including pre-admission decisions. No request text, detector response bodies, credentials or internal event identifiers. Latest 100 only; not a complete audit export. Cache-Control: no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Declared metadata or synthetic result; Cache-Control: no-store", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "coverage" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "detector", "configuration_fingerprint", "stage", "coverage", "enforcer_version", "outcome", "reason", "elapsed_ms", "key_name", "workspace_revision", "key_policy_revision", "key_assignment_revision", "recorded_at" ], "properties": { "detector": { "type": "string" }, "configuration_fingerprint": { "type": "string" }, "stage": { "type": "string", "enum": [ "input" ] }, "coverage": { "type": "string", "enum": [ "local_text" ] }, "enforcer_version": { "type": "string", "enum": [ "external-input-v1" ] }, "outcome": { "type": "string", "enum": [ "clear", "matched", "indeterminate" ] }, "reason": { "type": "string" }, "elapsed_ms": { "type": "number" }, "key_name": { "type": "string" }, "workspace_revision": { "type": [ "integer", "null" ] }, "key_policy_revision": { "type": [ "integer", "null" ] }, "key_assignment_revision": { "type": [ "integer", "null" ] }, "recorded_at": { "type": "string", "format": "date-time" } } } }, "coverage": { "type": "string", "enum": [ "latest_100_input_detector_decisions" ] } } } } } }, "401": { "description": "Invalid management credential; inference credentials cannot access management endpoints" }, "403": { "description": "Insufficient workspace permission or installation administrator authorization" }, "503": { "description": "Authorization/storage unavailable" } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/image-detectors/{detector}/preview": { "post": { "operationId": "previewWorkspaceImageDetector", "summary": "Preview explicitly consented workspace image processing", "description": "Workspace write access required. Sends the supplied inline PNG, JPEG or WebP image to a deployment-configured image detector only after workspace authorization, current explicit consent and declared-unmetered checks. Route request body limit is 2 MiB. Decode errors are 400; decode-worker busy/failure is 503. Inspection unavailability is a 200 indeterminate outcome. Does not save or activate a policy, grant dispatch access or integrate customer billing. Cache-Control: no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "detector", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Declared metadata or synthetic result; Cache-Control: no-store", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome", "reason", "synthetic", "enforcement", "policy_activation" ], "properties": { "outcome": { "type": "string", "enum": [ "clear", "matched", "indeterminate" ] }, "reason": { "type": "string", "enum": [ "inspected_image", "image_match", "inspection_unavailable" ] }, "synthetic": { "type": "boolean", "enum": [ true ] }, "enforcement": { "type": "boolean", "enum": [ false ] }, "policy_activation": { "type": "boolean", "enum": [ false ] } } } } } }, "400": { "description": "Malformed JSON, unknown fields, invalid content, oversized body or missing/stale explicit consent" }, "401": { "description": "Invalid management credential; inference credentials cannot access management endpoints" }, "403": { "description": "Insufficient workspace permission or installation administrator authorization" }, "404": { "description": "Workspace or configured detector not found" }, "503": { "description": "Authorization/storage unavailable or image decode workers unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "consent", "image" ], "properties": { "consent": { "type": "object", "additionalProperties": false, "required": [ "configuration_fingerprint", "consent_to_image_processing" ], "properties": { "configuration_fingerprint": { "type": "string" }, "consent_to_image_processing": { "type": "boolean" } } }, "image": { "type": "string", "description": "Inline data:image reference; bounded PNG, JPEG or WebP decoding." } } } } } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/image-detectors": { "get": { "operationId": "listWorkspaceImageDetectors", "summary": "List authorized workspace image detector declarations", "description": "Workspace read access required. Separate image processing discovery, sorted by detector name. Declared processing conditions are not verified guarantees. No image dispatch or policy activation. Cache-Control: no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Declared metadata or synthetic result; Cache-Control: no-store", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "detector", "schema_version", "detector_revision", "configuration_fingerprint", "recipient", "region", "retention", "content_sent", "processing_guarantees", "timeout_ms", "maximum_encoded_bytes", "maximum_width", "maximum_height", "maximum_decoded_bytes", "concurrency", "declared_unmetered", "policy_activation" ], "properties": { "detector": { "type": "string" }, "schema_version": { "type": "integer", "enum": [ 2 ] }, "detector_revision": { "type": "string" }, "configuration_fingerprint": { "type": "string" }, "recipient": { "type": "string" }, "region": { "type": "string" }, "retention": { "type": "string" }, "content_sent": { "type": "string", "enum": [ "exact_encoded_image" ] }, "processing_guarantees": { "type": "string", "enum": [ "declared_unverified" ] }, "timeout_ms": { "type": "integer" }, "maximum_encoded_bytes": { "type": "integer" }, "maximum_width": { "type": "integer" }, "maximum_height": { "type": "integer" }, "maximum_decoded_bytes": { "type": "integer" }, "concurrency": { "type": "integer" }, "declared_unmetered": { "type": "boolean" }, "policy_activation": { "type": "boolean", "enum": [ false ] } } } } } } } } }, "401": { "description": "Invalid management credential; inference credentials cannot access management endpoints" }, "403": { "description": "Insufficient workspace permission or installation administrator authorization" }, "404": { "description": "Workspace or configured detector not found" }, "503": { "description": "Authorization/storage unavailable" } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/detectors": { "get": { "operationId": "listWorkspaceDetectors", "summary": "List authorized workspace text detector declarations", "description": "Workspace read access required. Sorted by detector name; only deployment-authorized workspace detectors are returned. Declared processing conditions are not verified guarantees. No content is dispatched and no policy is activated. Cache-Control: no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Declared metadata or synthetic result; Cache-Control: no-store", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "schema_version", "detector_revision", "configuration_fingerprint", "recipient", "region", "retention", "processing_guarantees", "content_sent", "credential_source", "timeout_ms", "concurrency", "max_text_bytes", "max_response_bytes", "external_charge", "customer_billing", "policy_activation", "detector" ], "properties": { "schema_version": { "type": "integer", "enum": [ 1 ] }, "detector_revision": { "type": "string" }, "configuration_fingerprint": { "type": "string" }, "recipient": { "type": "string" }, "region": { "type": "string" }, "retention": { "type": "string" }, "processing_guarantees": { "type": "string", "enum": [ "declared_unverified" ] }, "content_sent": { "type": "string", "enum": [ "request_text_after_local_redaction" ] }, "credential_source": { "type": "string", "enum": [ "server_environment" ] }, "timeout_ms": { "type": "integer" }, "concurrency": { "type": "integer" }, "max_text_bytes": { "type": "integer" }, "max_response_bytes": { "type": "integer", "enum": [ 4096 ] }, "external_charge": { "type": "string", "enum": [ "unknown", "declared_unmetered" ] }, "customer_billing": { "type": "string", "enum": [ "not_integrated" ] }, "policy_activation": { "type": "boolean" }, "detector": { "type": "string" } } } } } } } } }, "401": { "description": "Invalid management credential; inference credentials cannot access management endpoints" }, "403": { "description": "Insufficient workspace permission or installation administrator authorization" }, "404": { "description": "Workspace or configured detector not found" }, "503": { "description": "Authorization/storage unavailable" } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/providers/{provider}/offers/{offer}/qualification/revoke": { "post": { "operationId": "revokeProviderOfferQualification", "x-niu-implementation": "implemented", "summary": "Revoke the current Provider offer qualification", "description": "Platform administration required. Appends an immutable reason digest and audit, clears the current offer review and pauses that offer atomically. Missing/deleted Provider, missing offer or absence of a current review conflicts, including repeated revocation. Other offers and historical request charges or earnings are unchanged.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason_sha256" ], "properties": { "reason_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." } } } } } }, "responses": { "200": { "description": "Qualification transaction committed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "qualification_status" ], "properties": { "qualification_status": { "type": "string", "enum": [ "revoked" ] } } } } } } } }, "400": { "description": "Invalid path UUID, malformed JSON, evidence digest, expiry or review metadata." }, "401": { "description": "Missing or invalid administrator authentication." }, "403": { "description": "Authenticated principal lacks platform management permission." }, "409": { "description": "Missing resource or qualification/revision prerequisites no longer hold." }, "415": { "description": "Request is not JSON." }, "422": { "description": "JSON has missing, unknown or incorrectly typed fields." }, "500": { "description": "Unexpected internal persistence failure." }, "503": { "description": "Persistence temporarily unavailable; no successful qualification is confirmed." } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/offers/{offer}/qualification": { "put": { "operationId": "qualifyProviderOffer", "x-niu-implementation": "implemented", "summary": "Record a Provider offer qualification review", "description": "Platform administration required. Requires current Provider business qualification, matching current rate_revision and a current media offer binding where applicable; otherwise 409. Records a new immutable review and audit, then selects that review. Evidence digests must represent independently reviewed facts; this operation does not validate their content, negotiate rates, call upstream or activate the offer.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "rate_revision", "model_identity_sha256", "protocol_matrix_sha256", "data_handling_sha256", "availability_sha256", "agreed_rates_sha256", "protocol_matrix_version", "valid_until_ms" ], "properties": { "rate_revision": { "type": "string", "format": "uuid", "description": "Must equal the current immutable offer rate revision." }, "model_identity_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." }, "protocol_matrix_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." }, "data_handling_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." }, "availability_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." }, "agreed_rates_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." }, "protocol_matrix_version": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonblank after trimming; at most 100 UTF-8 bytes before trimming; no control characters. Saved trimmed." }, "valid_until_ms": { "type": "integer", "format": "int64", "maximum": 253402300799999, "description": "Unix epoch milliseconds; must be strictly later than server time." } } } } } }, "responses": { "200": { "description": "Qualification transaction committed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "qualification_status" ], "properties": { "qualification_status": { "type": "string", "enum": [ "qualified" ] } } } } } } } }, "400": { "description": "Invalid path UUID, malformed JSON, evidence digest, expiry or review metadata." }, "401": { "description": "Missing or invalid administrator authentication." }, "403": { "description": "Authenticated principal lacks platform management permission." }, "409": { "description": "Missing resource or qualification/revision prerequisites no longer hold." }, "415": { "description": "Request is not JSON." }, "422": { "description": "JSON has missing, unknown or incorrectly typed fields." }, "500": { "description": "Unexpected internal persistence failure." }, "503": { "description": "Persistence temporarily unavailable; no successful qualification is confirmed." } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/qualification/revoke": { "post": { "operationId": "revokeProviderBusinessQualification", "x-niu-implementation": "implemented", "summary": "Revoke the current Provider business qualification", "description": "Platform administration required. Appends an immutable reason digest and audit, clears the current business review, and pauses all Provider offers while clearing their current reviews atomically. Missing/deleted Provider or absence of a current review conflicts, including repeated revocation. Does not erase historical reviews or change existing request charges or earnings.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason_sha256" ], "properties": { "reason_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." } } } } } }, "responses": { "200": { "description": "Qualification transaction committed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "qualification_status" ], "properties": { "qualification_status": { "type": "string", "enum": [ "revoked" ] } } } } } } } }, "400": { "description": "Invalid path UUID, malformed JSON, evidence digest, expiry or review metadata." }, "401": { "description": "Missing or invalid administrator authentication." }, "403": { "description": "Authenticated principal lacks platform management permission." }, "409": { "description": "Missing resource or qualification/revision prerequisites no longer hold." }, "415": { "description": "Request is not JSON." }, "422": { "description": "JSON has missing, unknown or incorrectly typed fields." }, "500": { "description": "Unexpected internal persistence failure." }, "503": { "description": "Persistence temporarily unavailable; no successful qualification is confirmed." } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/qualification": { "put": { "operationId": "qualifyProviderBusiness", "x-niu-implementation": "implemented", "summary": "Record a Provider business qualification review", "description": "Platform administration required; Provider membership does not grant this write. Records a new immutable review and audit with caller-supplied evidence digests, then selects that review. The server validates digest syntax and expiry, not the truth of supply rights, capability or data-handling evidence. No upstream check, commercial agreement, funds transfer or offer activation is performed. Missing or deleted Provider conflicts.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "supply_rights_sha256", "supply_capability_sha256", "data_handling_sha256", "valid_until_ms" ], "properties": { "supply_rights_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." }, "supply_capability_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." }, "data_handling_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of independently reviewed evidence; lowercase hexadecimal. Evidence content is not uploaded by this operation." }, "valid_until_ms": { "type": "integer", "format": "int64", "maximum": 253402300799999, "description": "Unix epoch milliseconds; must be strictly later than server time." } } } } } }, "responses": { "200": { "description": "Qualification transaction committed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "qualification_status" ], "properties": { "qualification_status": { "type": "string", "enum": [ "qualified" ] } } } } } } } }, "400": { "description": "Invalid path UUID, malformed JSON, evidence digest, expiry or review metadata." }, "401": { "description": "Missing or invalid administrator authentication." }, "403": { "description": "Authenticated principal lacks platform management permission." }, "409": { "description": "Missing resource or qualification/revision prerequisites no longer hold." }, "415": { "description": "Request is not JSON." }, "422": { "description": "JSON has missing, unknown or incorrectly typed fields." }, "500": { "description": "Unexpected internal persistence failure." }, "503": { "description": "Persistence temporarily unavailable; no successful qualification is confirmed." } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/auth/preferences": { "get": { "operationId": "getMemberPreferences", "summary": "Read current member appearance preference", "description": "Current authenticated member only; the target member is derived from authentication, never supplied by the caller. Requires an operator/member session with Read permission; installation bearer credentials are rejected. Browser member-cookie sessions are also supported by the existing authentication middleware. All responses carry Cache-Control: no-store. Returns the saved color mode; when no member preference exists, returns the installation branding default appearance. No revision field is exposed.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current saved member data.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "color_mode" ], "properties": { "color_mode": { "type": "string", "enum": [ "system", "light", "dark" ] } } } } } } } }, "401": { "description": "Missing, invalid or revoked member authentication." }, "403": { "description": "Read permission required; installation credentials cannot access member data, or a write failed origin/cookie checks." }, "503": { "description": "Durable storage unavailable." } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } }, "put": { "operationId": "updateMemberPreferences", "summary": "Save current member appearance preference", "description": "Current authenticated member only; the target member is derived from authentication, never supplied by the caller. Requires an operator/member session with Read permission; installation bearer credentials are rejected. Browser member-cookie sessions are also supported by the existing authentication middleware. All responses carry Cache-Control: no-store. When password authentication is configured, cookie/browser writes require a valid Origin and cookie-request checks; bearer writes validate Origin when supplied. Saves one of system, light or dark. This endpoint has no revision precondition; subsequent accepted writes replace the saved mode. Route body limit is 1024 bytes; rejected bodies are mapped to JSON invalid-request errors.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current saved member data.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "color_mode" ], "properties": { "color_mode": { "type": "string", "enum": [ "system", "light", "dark" ] } } } } } } } }, "400": { "description": "Invalid JSON, unknown fields or invalid input." }, "401": { "description": "Missing, invalid or revoked member authentication." }, "403": { "description": "Read permission required; installation credentials cannot access member data, or a write failed origin/cookie checks." }, "503": { "description": "Durable storage unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "color_mode" ], "properties": { "color_mode": { "type": "string", "enum": [ "system", "light", "dark" ] } } } } } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/auth/profile": { "get": { "operationId": "getMemberProfile", "summary": "Read current member profile", "description": "Current authenticated member only; the target member is derived from authentication, never supplied by the caller. Requires an operator/member session with Read permission; installation bearer credentials are rejected. Browser member-cookie sessions are also supported by the existing authentication middleware. All responses carry Cache-Control: no-store. Returns the saved name, nullable password-login email, nullable avatar and numeric profile revision.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current saved member data.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "name", "email", "avatar_data_url", "revision" ], "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "avatar_data_url": { "type": [ "string", "null" ], "description": "Normalized PNG data URL, or null when no avatar is saved." }, "revision": { "type": "integer", "format": "int64", "minimum": 0 } } } } } } } }, "401": { "description": "Missing, invalid or revoked member authentication." }, "403": { "description": "Read permission required; installation credentials cannot access member data, or a write failed origin/cookie checks." }, "503": { "description": "Durable storage unavailable." } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } }, "put": { "operationId": "updateMemberProfile", "summary": "Update current member profile", "description": "Current authenticated member only; the target member is derived from authentication, never supplied by the caller. Requires an operator/member session with Read permission; installation bearer credentials are rejected. Browser member-cookie sessions are also supported by the existing authentication middleware. All responses carry Cache-Control: no-store. When password authentication is configured, cookie/browser writes require a valid Origin and cookie-request checks; bearer writes validate Origin when supplied. Atomically updates name and avatar with optimistic revision checking. Email is read-only. Null or omitted avatar_data_url clears the avatar. Route body limit is 180000 bytes; rejected bodies are mapped to JSON invalid-request errors.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Current saved member data.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "name", "email", "avatar_data_url", "revision" ], "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "avatar_data_url": { "type": [ "string", "null" ], "description": "Normalized PNG data URL, or null when no avatar is saved." }, "revision": { "type": "integer", "format": "int64", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid JSON, unknown fields or invalid input." }, "401": { "description": "Missing, invalid or revoked member authentication." }, "403": { "description": "Read permission required; installation credentials cannot access member data, or a write failed origin/cookie checks." }, "409": { "description": "expected_revision does not match the saved profile; reload before retrying." }, "503": { "description": "Durable storage unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "expected_revision" ], "properties": { "name": { "type": "string", "maxLength": 100, "description": "Trimmed before saving; must contain 1 to 100 Unicode characters and no control characters." }, "avatar_data_url": { "type": [ "string", "null" ], "maxLength": 175000, "description": "Optional PNG data URL. Null or omission removes the existing avatar. Decoded and normalized PNG must each be at most 131072 bytes and dimensions at most 256 by 256 pixels." }, "expected_revision": { "type": "integer", "format": "int64", "minimum": 0, "description": "Numeric revision returned by GET; a profile with no saved customization starts at zero. Successful update increments it." } } } } } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/organizations/{organization}/projects": { "post": { "operationId": "createOrganizationWorkspace", "summary": "Create a workspace in the selected company", "description": "Legacy workspace-compatible endpoint. Uses the same company creation authorization and actor-scoped durable Idempotency-Key identity as canonical workspace creation. Returns only id, organization_id and name. Identical retries preserve one workspace; changed retry documents conflict. Workspace members cannot create sibling workspaces. New workspaces do not create funding or credit. Request fields other than name are ignored by the legacy parser.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Visible ASCII durable retry identity, scoped to the actor." } ], "responses": { "201": { "description": "Created workspace or durable replay of its current identity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid name or idempotency header." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace creation denied." }, "404": { "description": "Company outside authorized scope." }, "409": { "description": "Conflicting idempotency document." }, "422": { "description": "Missing or type-invalid name in JSON body." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } }, "get": { "operationId": "listOrganizationWorkspaces", "summary": "List scoped company workspaces", "description": "Legacy workspace-compatible endpoint. Installation authority sees up to 1000 company workspaces in creation order; member results are restricted to their authorized scope. Returns id/name only; use canonical workspace listing for richer metadata. Foreign company scope is concealed with 404.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized workspace names.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } } }, "401": { "description": "Authentication required." }, "404": { "description": "Company outside authorized scope." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/providers/{provider}/configuration-usage": { "get": { "operationId": "getProviderConfigurationUsage", "summary": "Inspect operational usage of Provider-owned configurations", "description": "Installation credential or explicit platform administrator required. Provider membership and customer roles do not grant access. Uses current explicit configuration ownership and persisted managed/media request routes; includes disabled configurations and does not infer unbound legacy/static traffic. This is current-configuration operational history, not historical financial attribution, qualified commercial supply, earnings or settlement. Counts each dispatched attempt once, including retry attempts. From is inclusive, to exclusive, in epoch milliseconds; maximum range 90 days. Token sums include only complete provider-reported aggregate token usage; unknown requests and non-token media remain separately counted. Failures count persisted safe failure observations, not an inference that every unsuccessful request has one. Timing counts refer to recorded HTTP delivery, not video job completion. Totals cover the whole range regardless of model page. after is an exclusive lexical model-alias boundary, not an identity lookup; pages are live statement snapshots. No customer identity, request/key IDs, endpoint, credentials, costs or prices are returned. No upstream call or mutation. Cache-Control no-store.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from_ms", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 253402300799999 } }, { "name": "to_ms", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 253402300799999 } }, { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Scoped operational counts; not supply or financial qualification.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "from_ms", "to_ms", "observed_at", "totals", "models", "next_after" ], "properties": { "from_ms": { "type": "integer" }, "to_ms": { "type": "integer" }, "observed_at": { "type": "string", "format": "date-time" }, "totals": { "type": "object", "additionalProperties": false, "required": [ "requests", "completed", "execution_unknown", "known_token_usage_requests", "unknown_token_usage_requests", "prompt_tokens", "completion_tokens", "failures", "observed_timing_requests", "complete_timing_requests", "complete_total_ms" ], "properties": { "requests": { "type": "string", "pattern": "^[0-9]+$" }, "completed": { "type": "string", "pattern": "^[0-9]+$" }, "execution_unknown": { "type": "string", "pattern": "^[0-9]+$" }, "known_token_usage_requests": { "type": "string", "pattern": "^[0-9]+$" }, "unknown_token_usage_requests": { "type": "string", "pattern": "^[0-9]+$" }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "failures": { "type": "string", "pattern": "^[0-9]+$" }, "observed_timing_requests": { "type": "string", "pattern": "^[0-9]+$" }, "complete_timing_requests": { "type": "string", "pattern": "^[0-9]+$" }, "complete_total_ms": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Sum of complete observed HTTP delivery durations; null without any complete timing. Not asynchronous job duration." } } }, "models": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "requests", "completed", "execution_unknown", "known_token_usage_requests", "unknown_token_usage_requests", "prompt_tokens", "completion_tokens", "failures", "observed_timing_requests", "complete_timing_requests", "complete_total_ms", "model" ], "properties": { "requests": { "type": "string", "pattern": "^[0-9]+$" }, "completed": { "type": "string", "pattern": "^[0-9]+$" }, "execution_unknown": { "type": "string", "pattern": "^[0-9]+$" }, "known_token_usage_requests": { "type": "string", "pattern": "^[0-9]+$" }, "unknown_token_usage_requests": { "type": "string", "pattern": "^[0-9]+$" }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "failures": { "type": "string", "pattern": "^[0-9]+$" }, "observed_timing_requests": { "type": "string", "pattern": "^[0-9]+$" }, "complete_timing_requests": { "type": "string", "pattern": "^[0-9]+$" }, "complete_total_ms": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Sum of complete observed HTTP delivery durations; null without any complete timing. Not asynchronous job duration." }, "model": { "type": "string" } } } }, "next_after": { "type": [ "string", "null" ] } } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid interval, cursor boundary, limit or query." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administration required." }, "404": { "description": "Provider does not exist or is deleted." }, "503": { "description": "Storage unavailable or diagnostic query deadline exceeded; no partial totals." } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/organizations/{organization}/projects/{project}/requests/{attempt}/usage-reconciliation": { "post": { "operationId": "reconcileRequestUsage", "summary": "Supplement missing native request usage from captured OpenRouter evidence", "description": "Installation write access only. Empty object input; no client-supplied generation identifier, quantities or costs. Uses the stored server response reference and original managed credential only while its vendor revision remains current and enabled. New captured references pin the dispatched upstream model independently of later mapping edits; legacy references without that binding still require the unchanged enabled model revision. Exact upstream model match required; aliases are not inferred equivalent. Bounded metadata lookup can return 502 while metadata is unavailable. Eligible requests have unknown aggregate usage, or confirmed provider-reported totals with missing cache-read/reasoning quantities and no recorded monetary or Credits customer charge. For known totals, metadata must match both totals and every reported known category, and add at least one previously missing category. Cache-write quantities are not supplied by this lookup; existing quantities are preserved. Canonical metadata must confirm not-cancelled execution with stop/length/tool_calls and an exact model/reference match. Cancelled or nonterminal metadata remains unresolved. Atomically retains the original execution/usage/category state and immutable supplemental terminal evidence, then marks execution confirmed-completed. Existing completion timestamps are preserved; absent timestamps record the time confirmation is stored. Original failure and delivery timing remain unchanged. Recorded does not mean settled: existing financial recovery applies the request-bound tariffs; missing required categories keep liability unresolved. Never resubmits inference. Identical replay returns the saved receipt without upstream access. Cache-Control no-store. New v2 receipts retain terminal finish/cancellation evidence. Legacy v1 receipts retain null terminal fields without invented backfill.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attempt", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Supplemental usage recorded; settlement may remain pending.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "source_version", "recorded_at", "prompt_tokens", "completion_tokens", "cached_input_tokens", "reasoning_output_tokens", "cache_write_input_tokens", "original_execution", "upstream_finish_reason", "upstream_cancelled" ], "properties": { "status": { "type": "string", "enum": [ "recorded" ] }, "source_version": { "type": "string", "enum": [ "openrouter-native-generation-v1", "openrouter-native-generation-v2" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "cached_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_output_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_input_tokens": { "type": "null" }, "original_execution": { "type": "string", "enum": [ "confirmed_completed", "may_have_executed" ] }, "upstream_finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", null ], "description": "Null for legacy v1 receipts; never backfilled." }, "upstream_cancelled": { "type": [ "boolean", "null" ], "enum": [ false, null ], "description": "Explicit false for v2 terminal evidence; null for legacy v1 receipts." } } } } } }, "400": { "description": "Malformed JSON input." }, "401": { "description": "Authentication required." }, "403": { "description": "Installation write access required." }, "404": { "description": "Scope unavailable." }, "409": { "description": "Ineligible completion, changed route or conflicting evidence. usage_reconciliation_identity_mismatch means upstream model/reference identity differs from captured request evidence; identities are not exposed. usage_reconciliation_incomplete means matching provider metadata does not confirm a non-cancelled terminal generation. Usage and charges remain unresolved in both cases." }, "422": { "description": "Input must be an empty JSON object; unknown fields are rejected." }, "502": { "description": "Upstream metadata unavailable, refused, malformed, oversized or timed out." }, "503": { "description": "Storage or credential decryption unavailable, including a bounded record-lock or statement timeout. A failed recording transaction preserves prior usage and leaves no partial receipt; retry does not resubmit inference." } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/requests/{attempt}/usage-reconciliation", "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "getRequestUsageReconciliation", "summary": "Read recorded supplemental request usage", "description": "Workspace read access required. Returns the same customer-safe immutable receipt as reconciliation, without querying upstream or modifying usage or accounting. Absence, unknown attempt and out-of-scope attempt return 404. Quantities are decimal strings; missing categories remain null. Recorded does not guarantee settlement. No original raw upstream metadata, generation reference, credential, Provider price or endpoint is exposed. Cache-Control no-store. New v2 receipts retain terminal finish/cancellation evidence. Legacy v1 receipts retain null terminal fields without invented backfill.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attempt", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Supplemental usage recorded; settlement may remain pending.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "source_version", "recorded_at", "prompt_tokens", "completion_tokens", "cached_input_tokens", "reasoning_output_tokens", "cache_write_input_tokens", "original_execution", "upstream_finish_reason", "upstream_cancelled" ], "properties": { "status": { "type": "string", "enum": [ "recorded" ] }, "source_version": { "type": "string", "enum": [ "openrouter-native-generation-v1", "openrouter-native-generation-v2" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "cached_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_output_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_input_tokens": { "type": "null" }, "original_execution": { "type": "string", "enum": [ "confirmed_completed", "may_have_executed" ] }, "upstream_finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", null ], "description": "Null for legacy v1 receipts; never backfilled." }, "upstream_cancelled": { "type": [ "boolean", "null" ], "enum": [ false, null ], "description": "Explicit false for v2 terminal evidence; null for legacy v1 receipts." } } } } } }, "401": { "description": "Authentication required." }, "404": { "description": "No recorded receipt in the authorized workspace." }, "503": { "description": "Storage or credential decryption unavailable." } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/requests/{attempt}/usage-reconciliation", "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/organizations/{organization}/workspaces/{project}/tariffs": { "get": { "operationId": "listPlatformCustomerTariffs", "summary": "Page current customer selling tariffs", "description": "Explicit platform administration required; ordinary company/workspace roles do not grant access. Configuration only, without usage, balances, statements, content, credentials or procurement. Keyset order is workspace UUID ascending for targets, model alias ascending for tariffs. Pass next_after unchanged as after; null means complete. Limit defaults to 50, maximum 100. Each page is one database snapshot; concurrent inserts before the cursor require refreshing the first page. Missing cursor returns 409. Identifiers are API references, never display labels. Cache-Control no-store. Tariff token rates are exact nanounits per million tokens; minimum and request fees are exact currency nanounits. Empty valid workspace returns an empty page.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Configuration page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_after" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "model_alias", "revision", "currency", "created_at", "prompt_rate", "completion_rate", "minimum_charge_nanos", "request_fee_nanos", "cached_prompt_rate", "reasoning_completion_rate", "cache_write_prompt_rate", "context_tiers" ], "properties": { "model_alias": { "type": "string" }, "revision": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "minimum_charge_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "request_fee_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." }, "discount_baseline_revision": { "type": [ "string", "null" ], "format": "uuid", "description": "Original selling-price revision for an explicit discount. API reference only; never a UI label. Resulting rates, currency, category presence and context thresholds are checked against the original. Existing requests retain their pinned revision." }, "pricing_health": { "$ref": "#/components/schemas/handler_operations_json_PlatformPricingHealth" } } } }, "next_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid query" }, "401": { "description": "Invalid management credential" }, "403": { "description": "Platform administration required" }, "404": { "description": "Company/workspace pair does not exist" }, "409": { "description": "Cursor absent from selected directory" }, "503": { "description": "Storage unavailable" } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/models": { "get": { "operationId": "listPlatformPricingModels", "summary": "List models eligible for customer tariff publication", "description": "Explicit platform administration required. Uses the same shared catalog as customer tariff publication, excluding personal owner-funded and unavailable aliases. This is a current eligibility read, not a price, supply qualification or dispatch guarantee. Publication rechecks eligibility. Sorted by model alias; limit defaults to 50, maximum 100. Pass next_after unchanged; null means complete. An unavailable cursor returns 409: restart pagination. No credentials, upstream mappings or procurement prices. Cache-Control no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Current eligible alias page", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_after" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "model_alias" ], "properties": { "model_alias": { "type": "string" } } } }, "next_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid page size or alias cursor" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Cursor no longer eligible; restart pagination" } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/targets": { "get": { "operationId": "listPlatformPricingTargets", "summary": "Discover named platform pricing targets", "description": "Explicit platform administration required; ordinary company/workspace roles do not grant access. Configuration only, without usage, balances, statements, content, credentials or procurement. Keyset order is workspace UUID ascending for targets, model alias ascending for tariffs. Pass next_after unchanged as after; null means complete. Limit defaults to 50, maximum 100. Each page is one database snapshot; concurrent inserts before the cursor require refreshing the first page. Missing cursor returns 409. Identifiers are API references, never display labels. Cache-Control no-store. Tariff token rates are exact nanounits per million tokens; minimum and request fees are exact currency nanounits. Empty valid workspace returns an empty page.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Configuration page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_after" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "organization_id", "workspace_id", "organization_name", "workspace_name" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "workspace_name": { "type": "string" } } } }, "next_after": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid query" }, "401": { "description": "Invalid management credential" }, "403": { "description": "Platform administration required" }, "409": { "description": "Cursor absent from selected directory" }, "503": { "description": "Storage unavailable" } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pricing/organizations/{organization}/workspaces/{project}/tariffs/{model}/history": { "get": { "operationId": "listPlatformCustomerTariffHistory", "summary": "Read platform customer selling-price history", "description": "Explicit platform administration required, independent of ordinary customer workspace read scope. Reuses immutable customer tariff history and its bounded cursor contract. Returns selling prices only: no customer usage, balances, invoices, content, credentials or Provider procurement. Missing tariff returns 404; cursor outside the selected tariff returns 409. Cache-Control no-store.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Exclusive revision cursor belonging to this workspace and model." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Current pointer and immutable bounded history page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "current_revision", "data", "has_more", "next_before" ], "properties": { "current_revision": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/handler_operations_json_CustomerTextTariffHistoryEntry" } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid path, query, model or page limit." }, "401": { "description": "Management authentication required." }, "403": { "description": "Platform administration required" }, "404": { "description": "Workspace access denied or no tariff for this model." }, "409": { "description": "Cursor does not belong to this workspace/model history." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/vendors/{vendor}/cooldown": { "get": { "operationId": "getVendorCooldown", "summary": "Read credential safe-failure cooldown", "description": "Platform administration only. Fixed policy: three new canonical OpenRouter text authentication rejections with pinned nonexecution qualification within 60 seconds pause new selection for 60 seconds. Further qualifying in-flight failures may extend the deadline; unknown execution never counts. State is shared in PostgreSQL, independent per credential, and survives restart and credential edits. Expiry automatically restores eligibility without a health probe or republish. Does not cancel pinned requests or saved video recovery. No historical failures are backfilled. This read performs no upstream request.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "vendor", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current state and fixed policy. Expired deadlines may remain in history while active is false.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "policy_revision", "failure_threshold", "window_seconds", "cooldown_seconds", "active", "cooldown_until", "qualifying_failures" ], "properties": { "policy_revision": { "type": "string", "const": "openrouter-auth-cooldown-v1" }, "failure_threshold": { "type": "integer", "const": 3 }, "window_seconds": { "type": "integer", "const": 60 }, "cooldown_seconds": { "type": "integer", "const": 60 }, "active": { "type": "boolean" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "qualifying_failures": { "type": "integer", "minimum": 0, "description": "New qualifying failures recorded in the current rolling window, not total upstream failures." } } } } } } } }, "401": { "description": "Invalid administrative credential." }, "403": { "description": "Platform permission required." }, "404": { "description": "Credential not found." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/vendors/{vendor}/request-rate-limit/history": { "get": { "operationId": "listVendorRequestRateLimitHistory", "summary": "Read credential request-limit history", "description": "Platform administration only. Applies to mapped inference dispatches pinned to this saved credential across workspaces and gateway instances, independent of customer key RPM. Null is unlimited; zero denies dispatch. Revision starts at string 0 and survives credential edits. Rolling 60-second admissions count dispatch, including upstream failures and uncertain outcomes; polling and connection checks are not inference dispatch. Unlimited dispatches also count when a cap is subsequently enabled. No automatic route substitution or replay. Duplicated credentials saved under different vendor IDs have independent windows. Storage operations use bounded transactions: read-only snapshots for reads and a recording transaction for updates, with transaction-local 250 ms lock and 2 s statement limits. Exceeded waits return sanitized 503; failed updates do not advance policy/history. These bounds exclude authorization and pool acquisition.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "vendor", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9223372036854776000 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Current policy or descending immutable history.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_VendorRequestRateLimitRevision" } } } } } } }, "400": { "description": "Invalid limit, revision or query." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administration required." }, "404": { "description": "Credential configuration not found." }, "409": { "description": "Stale revision on policy update." }, "503": { "description": "Storage unavailable or bounded storage wait exceeded; no empty-success policy/history fallback." } }, "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/vendors/{vendor}/request-rate-limit": { "get": { "operationId": "getVendorRequestRateLimit", "summary": "Read upstream credential request limit", "description": "Platform administration only. Applies to mapped inference dispatches pinned to this saved credential across workspaces and gateway instances, independent of customer key RPM. Null is unlimited; zero denies dispatch. Revision starts at string 0 and survives credential edits. Rolling 60-second admissions count dispatch, including upstream failures and uncertain outcomes; polling and connection checks are not inference dispatch. Unlimited dispatches also count when a cap is subsequently enabled. No automatic route substitution or replay. Duplicated credentials saved under different vendor IDs have independent windows. Storage operations use bounded transactions: read-only snapshots for reads and a recording transaction for updates, with transaction-local 250 ms lock and 2 s statement limits. Exceeded waits return sanitized 503; failed updates do not advance policy/history. These bounds exclude authorization and pool acquisition.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "vendor", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current policy or descending immutable history.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_VendorRequestRateLimit" } } } } } }, "400": { "description": "Invalid limit, revision or query." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administration required." }, "404": { "description": "Credential configuration not found." }, "409": { "description": "Stale revision on policy update." }, "503": { "description": "Storage unavailable or bounded storage wait exceeded; no empty-success policy/history fallback." } }, "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "put": { "operationId": "setVendorRequestRateLimit", "summary": "Set upstream credential request limit", "description": "Platform administration only. Applies to mapped inference dispatches pinned to this saved credential across workspaces and gateway instances, independent of customer key RPM. Null is unlimited; zero denies dispatch. Revision starts at string 0 and survives credential edits. Rolling 60-second admissions count dispatch, including upstream failures and uncertain outcomes; polling and connection checks are not inference dispatch. Unlimited dispatches also count when a cap is subsequently enabled. No automatic route substitution or replay. Duplicated credentials saved under different vendor IDs have independent windows. Storage operations use bounded transactions: read-only snapshots for reads and a recording transaction for updates, with transaction-local 250 ms lock and 2 s statement limits. Exceeded waits return sanitized 503; failed updates do not advance policy/history. These bounds exclude authorization and pool acquisition.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "vendor", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current policy or descending immutable history.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_VendorRequestRateLimit" } } } } } }, "400": { "description": "Invalid limit, revision or query." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administration required." }, "404": { "description": "Credential configuration not found." }, "409": { "description": "Stale revision on policy update." }, "503": { "description": "Storage unavailable or bounded storage wait exceeded; no empty-success policy/history fallback." } }, "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "requests_per_minute", "expected_revision" ], "properties": { "requests_per_minute": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000 }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact current revision. Concurrent stale updates return 409." } } } } } }, "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/providers/{provider}/offers/{offer}/revisions": { "get": { "operationId": "listProviderOfferHistory", "summary": "List immutable Provider quote history", "description": "Installation administration or active membership in this Provider is required. Company ownership does not grant procurement access. Newest first by created_at and revision UUID with exclusive keyset pagination, not commit order. One statement snapshot keeps each page and current pointer coherent; separate pages do not share a snapshot. New publications appear on a fresh first page. A foreign or missing cursor returns 409; a missing or inaccessible Provider/offer returns 404. Text prices are exact nanounits per million tokens; media text prices are null and use separate media rate cards. No credentials, endpoints or customer prices. Reading does not qualify, activate or reprice offers. Internal identifiers are API references, not UI labels.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Bounded historical procurement page.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "current_revision", "data", "has_more", "next_before" ], "properties": { "current_revision": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_ProviderOfferHistoryEntry" } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid query, limit or path." }, "401": { "description": "Management authentication required." }, "404": { "description": "Provider membership denied or offer not found." }, "409": { "description": "Cursor does not belong to this offer." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/organizations/{organization}/projects/{project}/billing/tariffs/{model}/history": { "get": { "operationId": "listCustomerTariffHistory", "summary": "Read immutable customer text price history", "description": "Same scoped management read permission as workspace billing. Newest first by created_at and revision UUID, with exclusive keyset pagination. A single database statement observes the current revision and page coherently. All prices are exact decimal strings: token rates are nanounits per million tokens, minimum and fixed fees are currency nanounits per known completed request. Includes no Provider procurement prices or upstream credentials. Unknown model returns 404; an unknown or foreign cursor returns 409. A newer publication can appear on a fresh first page but does not duplicate earlier entries when following an existing cursor. This read does not publish or reprice anything. Revision identifiers are API references, not display labels.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Exclusive revision cursor belonging to this workspace and model." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Current pointer and immutable bounded history page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "current_revision", "data", "has_more", "next_before" ], "properties": { "current_revision": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/handler_operations_json_CustomerTextTariffHistoryEntry" } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid path, query, model or page limit." }, "401": { "description": "Management authentication required." }, "404": { "description": "Workspace access denied or no tariff for this model." }, "409": { "description": "Cursor does not belong to this workspace/model history." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/projects/{project}/video/intents": { "get": { "operationId": "listVideoSubmissionIntents", "summary": "List the current actor video intent index", "description": "Actor-owned workspace records: installation authority shares one installation actor, while operator actors are isolated even within the same workspace. Current workspace permission applies. Request content is retained for 30 days from creation or until deletion; expiry is unreadable immediately and background maintenance clears retained content. Identity tombstones remain. Deletion does not cancel an already accepted concurrent submission, erase its job or refund charges. Newest-first creation order with UUID tie-breaker. The index contains only intent identity, revision, expiry and retention state; it intentionally exposes no request, model or key content. Index access remains available for deleting retained content after key revocation. Read each intent separately under current key authorization. A cursor must belong to this actor and workspace.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "List the current actor video intent index", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_before" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/handler_operations_json_VideoIntentIndexItem" } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential or no authorized current key in the original lineage." }, "403": { "description": "Workspace permission or current source policy denied." }, "404": { "description": "Intent is not owned by this actor and workspace, or selected model is inaccessible." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/video/intents", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/video/intents/{intent}": { "put": { "operationId": "saveVideoSubmissionIntent", "summary": "Save an immutable video submission intent with typed Niu references", "description": "Actor-owned workspace records: installation authority shares one installation actor, while operator actors are isolated even within the same workspace. Current workspace permission applies. Request content is retained for 30 days from creation or until deletion; expiry is unreadable immediately and background maintenance clears retained content. Identity tombstones remain. Deletion does not cancel an already accepted concurrent submission, erase its job or refund charges. Requires workspace write permission and an active selected key with model access and allowed source. A fresh client-generated intent UUID binds the exact request, original key and funding mode. Identical retries return the same record; changed input or key under that UUID conflicts. No attempt, upstream call or reservation is created. The internal idempotency identity is server-generated and is never exposed; use the submit operation rather than legacy job creation. Saving reference drafts reads only scoped material metadata and schema constraints. It never resolves private Provider URIs, reads upload bytes, queries upstream, reserves funds, inspects media or grants Active readiness. Original Niu references and explicit consent remain in the canonical request digest; all runtime bindings are revalidated at submit.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Save an immutable video submission intent with typed Niu references", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_VideoSubmissionIntent" } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential or no authorized current key in the original lineage." }, "403": { "description": "Workspace permission or current source policy denied." }, "404": { "description": "Intent is not owned by this actor and workspace, or selected model is inaccessible." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "413": { "description": "Request envelope exceeds 64 KiB." }, "501": { "description": "Unsupported video capability or saved-reference form." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "key_id", "request" ], "properties": { "key_id": { "type": "string", "format": "uuid" }, "request": { "$ref": "#/components/schemas/handler_operations_json_VideoIntentRequest" } } } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/video/intents/{intent}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "get": { "operationId": "getVideoSubmissionIntent", "summary": "Restore a saved video intent and its historical job", "description": "Accepts an internal UUID alias or permanent input reference. Both preserve existing workspace and actor authorization; mutation endpoints still require internal UUIDs. Current workspace Read permission and the original actor-owned intent are required. Restores saved request and job evidence independently of current inference key lifetime, model grants, source policy or Provider configuration. Original and available rotation-lineage key IDs are context only, never authority to submit, estimate or query upstream. Revoked/expired keys and lost model grants do not hide retained private input; deletion and original/bound-turn expiry still hide content immediately. Unknown submission evidence never grants permission to dispatch again. No upstream request, inference, reservation, settlement or write occurs. Storage failures remain errors.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "description": "Internal UUID alias or permanent input reference" } } ], "responses": { "200": { "description": "Restore a video intent and resolve its original job", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_VideoSubmissionIntent" } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential." }, "403": { "description": "Current workspace Read permission denied." }, "404": { "description": "Intent is not owned by this actor and workspace." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/video/intents/{intent}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "delete": { "operationId": "deleteVideoSubmissionIntent", "summary": "Erase saved intent content without cancelling its job", "description": "Actor-owned workspace records: installation authority shares one installation actor, while operator actors are isolated even within the same workspace. Current workspace permission applies. Request content is retained for 30 days from creation or until deletion; expiry is unreadable immediately and background maintenance clears retained content. Identity tombstones remain. Deletion does not cancel an already accepted concurrent submission, erase its job or refund charges. Requires write permission and the expected revision. Replaying the same successful deletion is idempotent. Does not require an active selected key. Deleted identities cannot be saved or submitted again.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erase saved intent content without cancelling its job", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "deleted" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "deleted": { "const": true } } } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential or no authorized current key in the original lineage." }, "403": { "description": "Workspace permission or current source policy denied." }, "404": { "description": "Intent is not owned by this actor and workspace, or selected model is inaccessible." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/video/intents/{intent}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/video/intents/{intent}/submit": { "post": { "operationId": "submitVideoSubmissionIntent", "summary": "Explicitly submit or replay an immutable saved video intent", "description": "Actor-owned workspace records: installation authority shares one installation actor, while operator actors are isolated even within the same workspace. Current workspace permission applies. Request content is retained for 30 days from creation or until deletion; expiry is unreadable immediately and background maintenance clears retained content. Identity tombstones remain. Deletion does not cancel an already accepted concurrent submission, erase its job or refund charges. Requires write permission, matching retained revision and current key/model/source authorization. Uses only the saved request and original rotation lineage. Rechecks configured video admission and rejects a changed owner-funded/customer funding mode before a new dispatch. Concurrent and restarted calls use one original submission identity. Interrupted original preparation is read back, never assumed safe to dispatch again. HTTP 202 can represent unresolved submission and is not a completed generation or settled charge. Fresh submissions use the same 24-hour inspected-request and Niu creation-response Logs capture as direct creation, with x-niu-log-payloads: false opt-out. Capture uses the saved inspected video request, not this revision-only submit body. Replay does not create or restore capture.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-niu-log-payloads", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" }, "description": "Capture the inspected Niu request and Niu creation response in bounded 24-hour Logs storage. False opts out; repeated or invalid values are rejected. Replay never creates a new capture." } ], "responses": { "202": { "description": "Explicitly submit or replay an immutable saved video intent", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "x-niu-attempt-id": { "description": "Present on fresh creation; identifies the attempt for scoped Logs. Replay does not generate a new capture.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "model", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "video.job" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "submission_unknown", "queued", "running", "succeeded", "failed", "unknown", "reconciliation_required" ] } } } } } }, "400": { "description": "Invalid path, query or request; framework rejections may be plain text." }, "401": { "description": "Invalid actor credential or no authorized current key in the original lineage." }, "402": { "description": "Insufficient funds or spending allowance before dispatch." }, "403": { "description": "Workspace permission or current source policy denied." }, "404": { "description": "Intent is not owned by this actor and workspace, or selected model is inaccessible." }, "409": { "description": "Immutable identity, request, funding mode, revision or cursor conflict." }, "429": { "description": "Current rate or concurrency policy denied admission." }, "501": { "description": "Unsupported video capability or saved-reference form." }, "503": { "description": "Required storage or route configuration is unavailable." } }, "x-niu-implementation": "implemented", "x-niu-status": "Durable text and typed Niu material-reference intent persistence with explicit submission. URL, inline data and ingested-image intent drafts remain unsupported; full browser restoration and customer-funded video qualification remain separate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/video/intents/{intent}/submit", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/payments/stripe/notify": { "post": { "operationId": "receiveStripePaymentNotification", "summary": "Receive a signed Stripe checkout notification", "description": "Server-to-server callback; no installation or workspace bearer token is required. Verifies the signature over the original request bytes before parsing JSON, then requires an existing merchant-bound order and its saved checkout session. Paid evidence must match the saved session, amount, currency and configured live mode. Settlement is idempotent. Creating a checkout or visiting its return URL does not credit a balance. Unsupported or unrelated events are rejected rather than silently acknowledged. Maximum request body: 262144 bytes.", "security": [], "x-niu-implementation": "implemented", "parameters": [ { "name": "stripe-signature", "in": "header", "required": true, "description": "Stripe timestamp and v1 signature of the unmodified request body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Original signed Stripe event JSON; proxies must preserve its bytes.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Verified settlement accepted, including an already settled replay; empty response body." }, "400": { "description": "Missing or invalid signature, malformed notification, unknown or unbound order, or mismatched paid evidence." }, "409": { "description": "Stored order conflicts with settlement." }, "413": { "description": "Request body exceeds 262144 bytes." }, "502": { "description": "Stripe is not configured or the payment clock is unavailable." }, "503": { "description": "Durable storage is unavailable." } }, "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/api/v1/providers/{provider}/members": { "get": { "operationId": "listProviderMembers", "summary": "List Provider business members", "description": "Requires platform management permission. Lists saved memberships ordered by member name and internal identity. active is false when membership is disabled or the member account is revoked; revoked reports account revocation separately. No tokens, merchant secrets or procurement amounts are returned. Internal operator identities are for routing, not product labels.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved membership list, including inactive or revoked members", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "operator_id", "name", "role", "active", "revoked" ], "properties": { "operator_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "manager", "viewer" ] }, "active": { "type": "boolean" }, "revoked": { "type": "boolean" } } } } } } } } }, "400": { "description": "Invalid identifier" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform management permission required" }, "409": { "description": "Provider missing or deleted" }, "503": { "description": "Storage unavailable" } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/organizations/{organization}/projects/{project}": { "patch": { "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "operationId": "renameWorkspace", "summary": "Rename a workspace", "description": "Requires scoped workspace write access. Trims the saved name. Returns the existing workspace identity and new name; no optimistic revision is accepted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Must contain non-whitespace text and be at most 200 UTF-8 bytes before trimming." } } } } } }, "responses": { "200": { "description": "Saved workspace name", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } }, "400": { "description": "Invalid name or identifier" }, "401": { "description": "Authentication required" }, "403": { "description": "Write permission required" }, "404": { "description": "Workspace missing or outside authorized scope" }, "422": { "description": "Invalid body shape" }, "503": { "description": "Storage unavailable" } }, "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "delete": { "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "operationId": "deleteWorkspace", "summary": "Delete an empty workspace", "description": "Requires installation authority or company-level membership with member-management permission. Workspace-scoped members cannot delete a workspace. Referenced workspaces are protected by storage foreign keys and return 409; no cascade deletion of business history is requested.", "responses": { "204": { "description": "Workspace deleted; empty body" }, "400": { "description": "Invalid identifier" }, "401": { "description": "Authentication required" }, "403": { "description": "Required company-level management permission missing" }, "404": { "description": "Workspace missing or outside authorized scope" }, "409": { "description": "Workspace still has dependent records" }, "503": { "description": "Storage unavailable" } }, "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/platform/financial-recovery": { "get": { "x-niu-implementation": "implemented", "operationId": "getFinancialRecoveryDiagnostics", "summary": "Read committed financial recovery progress", "description": "Platform administrators only. Stages are ordered by name. Null step fields mean no durable worker step has committed since diagnostics were installed. Counts describe the last committed candidate page, not settled rows, total backlog or throughput. A cursor indicates traversal position, not remaining recoverable debt. Zero failures does not establish settlement. Storage failures leave previous committed diagnostics unchanged and are reported separately in worker logs. No attempt IDs, amounts or credentials.", "tags": [ "Audit and recovery" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Committed stage diagnostics", "content": { "application/json": { "schema": { "type": "object", "required": [ "observed_at", "data" ], "properties": { "observed_at": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "type": "object", "required": [ "stage", "last_step_at", "last_candidate_count", "last_failure_count", "has_cursor" ], "properties": { "stage": { "type": "string", "enum": [ "balance_release", "customer_charge", "customer_media_charge", "media_completion", "supplier_earning", "upstream_cost" ] }, "last_step_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_candidate_count": { "type": [ "integer", "null" ], "minimum": 0 }, "last_failure_count": { "type": [ "integer", "null" ], "minimum": 0 }, "has_cursor": { "type": "boolean" } } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "503": { "description": "Storage unavailable" } }, "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/platform/audit-events": { "get": { "operationId": "listPlatformAuditEvents", "summary": "List platform operation audit logs", "description": "Platform administrators only. Aggregates saved operator, Provider configuration, Provider, branding, payment gateway and platform-access journals. Metadata only: no credentials, configuration values, request content or procurement prices. password_login_succeeded records verified password login; session_created records session issuance and does not prove login. Historical actor attribution may be unknown, and displayed names are current names. No historical completeness or failed-login coverage is asserted. Source-qualified keyset pagination orders newest first, using source and event ID for ties. Changing category requires restarting without a cursor. Successful responses are not cached. Includes immutable standard-price/promotion changes, text/media workspace enrollment, noncash grants and route media-liability qualification. Publishes and exact idempotent retries share the same saved event; no history is fabricated. Freeform reasons, quantities, schedules, balances and monetary values are not returned. New commercial sources remain platform-only; a cursor from another category is rejected.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Opaque source-qualified next_cursor from the previous page; do not parse or display." }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "authentication", "configuration", "access", "supplier" ] } } ], "responses": { "200": { "description": "Saved operation metadata and a nullable continuation cursor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_PlatformAuditPage" } } } }, "400": { "description": "Unknown query field, invalid category, page size or cursor, or cursor from a different category." }, "401": { "description": "Missing or invalid administrator authentication." }, "403": { "description": "Authenticated caller lacks platform administrator access. Workspace and Provider roles do not grant access." }, "503": { "description": "Durable storage unavailable." } }, "tags": [ "Audit and recovery" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/platform/configuration": { "get": { "operationId": "getPlatformConfiguration", "summary": "Read platform payment configuration presence", "description": "Requires platform management permission. Returns configuration-presence flags without merchant credentials. EPay is configured when a saved configuration exists (including disabled configurations) or deployment configuration is present; Zhifux and Stripe reflect loaded runtime adapters. Use customer payment-method discovery for checkout availability and the integration inventory for supported capabilities. This response does not prove successful external payments.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Sanitized configuration presence and current configuration-bound verification; no merchant identities or credentials.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "payment_gateways", "verification" ], "properties": { "payment_gateways": { "type": "array", "items": { "type": "object", "required": [ "name", "configured" ], "properties": { "name": { "type": "string", "enum": [ "Zhifux", "EPay", "Stripe" ] }, "configured": { "type": "boolean", "description": "Configuration presence only; not enabled checkout, merchant eligibility, or payment qualification." } } } }, "verification": { "type": "object", "required": [ "currency_configured", "gateways" ], "properties": { "currency_configured": { "type": "boolean" }, "gateways": { "type": "array", "items": { "type": "object", "required": [ "checkout_enabled", "currency_supported", "callback_verified", "ready", "gateway", "account_verified" ], "properties": { "checkout_enabled": { "type": "boolean" }, "currency_supported": { "type": "boolean" }, "callback_verified": { "type": "boolean" }, "ready": { "type": "boolean" }, "gateway": { "type": "string", "enum": [ "epay", "stripe", "zhifux" ] }, "account_verified": { "type": [ "boolean", "null" ], "description": "Current account eligibility for adapters with an account check; null when unsupported or simulated." } } } } } } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Platform management permission required" }, "503": { "description": "Configuration storage unavailable" } }, "tags": [ "Branding and settings" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/projects/{project}/requests/{attempt}": { "get": { "operationId": "getGatewayRequest", "summary": "Read a recorded gateway request", "description": "Scoped workspace read access required. Accepts a durable run reference or a legacy attempt UUID. Returns persisted metadata, usage, timing, safe failure classification and customer charges without prompts, response bodies or Provider procurement costs. Missing or foreign attempts return 404. Unknown values remain null. Legacy correlation fields are opaque metadata. Does not contact the upstream service or change billing. Reporting reads use a one-second database lock timeout and a five-second timeout per SQL statement. Timeout returns a sanitized 503 error, never partial results; these are not whole-request deadlines.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "project", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "attempt", "required": true, "schema": { "type": "string", "description": "Durable run reference or legacy attempt UUID" } } ], "responses": { "200": { "description": "Saved request metadata. Cache-Control: no-store.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GatewayRequestMetadata" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace read permission denied" }, "404": { "description": "Workspace or request unavailable in this scope" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/requests/{attempt}", "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/spending-limit": { "get": { "operationId": "listWorkspaceSpendingLimits", "summary": "List workspace spending currencies", "description": "Workspace readers may discover company account currencies and this workspace commitment without company-balance access. Absent limits and revisions are null. No state is changed.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "project", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current scoped state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceSpendingSummary" } } } } } } }, "400": { "description": "Invalid currency, decimal value or history query" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient role permissions" }, "404": { "description": "Workspace unavailable in the authorized scope" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/spending-limit", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/spending-limit/{currency}": { "get": { "operationId": "getWorkspaceSpendingLimit", "summary": "Read a workspace spending limit", "description": "Workspace read permission required. Returns data: null when no explicit limit exists. Does not expose company funds or other workspace usage.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "project", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "responses": { "200": { "description": "Current scoped state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_WorkspaceSpendingSummary" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid currency, decimal value or history query" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient role permissions" }, "404": { "description": "Workspace unavailable in the authorized scope" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/spending-limit/{currency}", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "setWorkspaceSpendingLimit", "summary": "Set a workspace spending limit", "description": "Scoped owner or installation administrator required. Both input fields are nonnegative decimal strings, not null. expected_revision 0 creates the first limit; later writes require the saved revision. Zero denies new paid liability; there is no null reset on this endpoint. A limit below existing commitment is rejected. Writes append actor history and never change company funds.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "project", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "responses": { "200": { "description": "Current scoped state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." } } } } } } } }, "400": { "description": "Invalid currency, decimal value or history query" }, "401": { "description": "Authentication required" }, "402": { "description": "Limit is below existing workspace commitment" }, "403": { "description": "Insufficient role permissions" }, "404": { "description": "Workspace unavailable in the authorized scope" }, "409": { "description": "Revision conflict or unavailable currency account" }, "422": { "description": "JSON input shape is invalid" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceSpendingInput" } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/spending-limit/{currency}", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/spending-limit/{currency}/history": { "get": { "operationId": "listWorkspaceSpendingLimitHistory", "summary": "List workspace spending revisions", "description": "Workspace read permission required. Descending immutable history. before_revision is exclusive. next_before_revision is a decimal string or null; an exactly full final page can yield an empty following page. Baseline timestamps and actor data may be null.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "path", "name": "organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "project", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "in": "query", "name": "before_revision", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Current scoped state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_before_revision" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceSpendingHistory" } }, "next_before_revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." } } } } } }, "400": { "description": "Invalid currency, decimal value or history query" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient role permissions" }, "404": { "description": "Workspace unavailable in the authorized scope" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/spending-limit/{currency}/history", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/units/limit": { "get": { "operationId": "getWorkspaceCustomerUnitSpendingLimit", "summary": "Read the workspace Credits spending limit and commitment", "description": "Workspace read permission required. Returns the workspace's explicit Credits atom limit, policy revision, committed atoms (settled charges minus original-range restorations plus unresolved holds and known overrun liabilities), remaining allowance, and whether an existing monetary workspace limit is preserved. A preserved monetary limit blocks Credits admission until an explicit Credits workspace limit revision (integer atoms or null for unlimited) is published. Never exposes company balance or procurement costs.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current workspace Credits spending limit state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "unit", "limit_atoms", "revision", "definition_revision", "committed_atoms", "remaining_atoms", "monetary_limit_preserved", "credits_admission_blocked_by_monetary_limit" ], "properties": { "unit": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "definition_revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "definition_revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "committed_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "remaining_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_limit_preserved": { "type": "boolean" }, "credits_admission_blocked_by_monetary_limit": { "type": "boolean" } } } } } } } }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace not found in the authorized scope" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/units/limit", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "setWorkspaceCustomerUnitSpendingLimit", "summary": "Set the workspace Credits spending limit", "description": "Workspace/company owner or installation administrator required and rechecked under lock. Sets an exact Credits atom cap or explicit null for unlimited, using optimistic revision checking and durable idempotency. Lowering below committed workspace liability (charges minus restorations plus unresolved holds and known overrun liabilities) returns 402. Preserves existing monetary workspace limits for currency mode while replacing their blocking effect in Credits admission.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "limit_atoms", "expected_revision", "idempotency_key" ], "properties": { "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$", "description": "Canonical nonnegative signed-64-bit integer string or explicit null for unlimited." }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Zero for initial configuration; maximum 9223372036854775806." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Immutable policy revision receipt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "expected_revision", "definition_revision", "limit_atoms", "recorded_at", "actor_kind", "actor_name" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } }, "400": { "description": "Invalid integer string" }, "401": { "description": "Authentication required or revoked" }, "402": { "description": "Proposed limit is below committed workspace liability" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace not found in the authorized scope" }, "409": { "description": "Stale revision, conflicting idempotency key or missing published unit definition" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/units/limit", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/units/limit/history": { "get": { "operationId": "listWorkspaceCustomerUnitSpendingLimitHistory", "summary": "List workspace Credits spending limit history", "description": "Workspace read permission required. Returns descending immutable revisions with exclusive before_revision pagination. Never exposes internal actor identifiers.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Descending immutable policy revisions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_before_revision" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "revision", "expected_revision", "definition_revision", "limit_atoms", "recorded_at", "actor_kind", "actor_name" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } }, "next_before_revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } } } } }, "400": { "description": "Invalid history cursor or page size" }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace not found in the authorized scope" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/units/limit/history", "tags": [ "Branded consumption units" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/units/limit": { "get": { "operationId": "getKeyCustomerUnitSpendingLimit", "summary": "Read an API key's Credits spending limit and commitment", "description": "Workspace read permission required. Rotated keys share their original spending root identity. Returns the key lineage's explicit Credits atom limit, policy revision, committed atoms (settled charges minus restorations plus unresolved holds and known overrun liabilities), remaining allowance, and whether an existing monetary key limit is preserved. A preserved monetary key limit blocks Credits admission until an explicit Credits key limit revision is published.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current API key Credits spending limit state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "unit", "limit_atoms", "revision", "definition_revision", "committed_atoms", "remaining_atoms", "monetary_limit_preserved", "credits_admission_blocked_by_monetary_limit" ], "properties": { "unit": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "definition_revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "definition_revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "committed_atoms": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "remaining_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "monetary_limit_preserved": { "type": "boolean" }, "credits_admission_blocked_by_monetary_limit": { "type": "boolean" } } } } } } } }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Key does not exist in the authorized workspace" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/units/limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "setKeyCustomerUnitSpendingLimit", "summary": "Set an API key's Credits spending limit", "description": "Workspace/company owner or installation administrator required and rechecked under lock. Updates the shared spending root identity across secret rotations using optimistic revision checking and durable idempotency. Lowering below committed key liability returns 402. Preserves existing monetary key limits for currency mode while replacing their blocking effect in Credits admission.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "limit_atoms", "expected_revision", "idempotency_key" ], "properties": { "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$", "description": "Canonical nonnegative signed-64-bit integer string or explicit null for unlimited." }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Zero for initial configuration; maximum 9223372036854775806." }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Immutable policy revision receipt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "expected_revision", "definition_revision", "limit_atoms", "recorded_at", "actor_kind", "actor_name" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } }, "400": { "description": "Invalid integer string" }, "401": { "description": "Authentication required or revoked" }, "402": { "description": "Proposed limit is below committed key liability" }, "403": { "description": "Owner permission required" }, "404": { "description": "Key does not exist in the authorized workspace" }, "409": { "description": "Stale revision, conflicting idempotency key, unattributed active liability or missing unit definition" }, "422": { "description": "Malformed request body" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/units/limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/units/limit/history": { "get": { "operationId": "listKeyCustomerUnitSpendingLimitHistory", "summary": "List API key Credits spending limit history", "description": "Workspace read permission required. Returns descending immutable revisions shared across key rotations, with exclusive before_revision pagination. Never exposes internal actor identifiers.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Descending immutable policy revisions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_before_revision" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "revision", "expected_revision", "definition_revision", "limit_atoms", "recorded_at", "actor_kind", "actor_name" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "limit_atoms": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } }, "next_before_revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } } } } }, "400": { "description": "Invalid history cursor or page size" }, "401": { "description": "Authentication required or revoked" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Key does not exist in the authorized workspace" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/units/limit/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/auth/password": { "put": { "operationId": "changeOwnMemberPassword", "summary": "Change the signed-in member's password with current-password proof", "security": [ { "bearerAuth": [] }, { "memberCookie": [] } ], "description": "All member roles may change their own password; installation credentials cannot. No target member or email is accepted. Verification uses shared sign-in throttling and bounded workers. Credential revision checks prevent concurrent resets from being overwritten. Success revokes all of this member's sessions atomically with audit records and requires fresh sign-in. Browser-cookie requests require the configured Origin and clear the cookie on success. Failed changes preserve sessions and do not clear the cookie. JSON bodies are limited to 4096 bytes. All responses are non-cacheable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "current_password", "password" ], "properties": { "current_password": { "type": "string", "maxLength": 1024, "writeOnly": true }, "password": { "type": "string", "minLength": 15, "maxLength": 1024, "writeOnly": true } } } } } }, "responses": { "200": { "description": "Password changed and sessions revoked", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "sign_in_required" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "sign_in_required": { "const": true } } } } } }, "400": { "description": "Invalid input or password policy failure; UTF-8 byte limit is 1024" }, "401": { "description": "Invalid session or incorrect current password" }, "403": { "description": "Installation identity or invalid browser origin" }, "409": { "description": "Credential revision changed during verification; no reset applied" }, "429": { "description": "Password verification limited; Retry-After 60" }, "501": { "description": "Password authentication not configured" }, "503": { "description": "Password change unavailable; do not assume completion" } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/auth/config": { "get": { "operationId": "getMemberAuthenticationConfiguration", "summary": "Discover member sign-in availability", "description": "Public capability discovery only. password_login and browser_token_login advertise the configured password and existing user-token browser sign-in transports. A missing browser_token_login field on an older Gateway does not establish support. This response does not disclose identities, credentials or upstream merchant status, and is not proof of deployed HTTPS/browser acceptance. Response carries Cache-Control: no-store.", "security": [], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Local password sign-in capability.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "password_login", "browser_token_login" ], "properties": { "password_login": { "type": "boolean" }, "browser_token_login": { "type": "boolean" }, "demo_login": { "type": "boolean" } } } } } } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/api/v1/auth/browser/login": { "post": { "operationId": "createBrowserMemberSession", "summary": "Sign in with a secure HttpOnly member cookie", "security": [], "description": "Requires the configured HTTPS Origin header. Uses the same password limits and durable throttling as bearer login. Sets __Host-niu_member_session with Secure, HttpOnly, SameSite=Lax, Path=/ and Max-Age=28800; no Domain. The response contains session metadata only, never the bearer token. When supplied, Sec-Fetch-Site must be a single same-origin value. All responses use Cache-Control no-store.", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email", "password" ], "properties": { "email": { "type": "string", "maxLength": 254, "description": "ASCII email; surrounding spaces and case are normalized." }, "password": { "type": "string", "maxLength": 1024, "description": "At most 1024 UTF-8 bytes; no trimming or normalization." } } } } } }, "responses": { "200": { "description": "Scoped browser session created", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "Secure HttpOnly host-only member session" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "session" ], "properties": { "session": { "$ref": "#/components/schemas/password_sessions_openapi_yaml_Session" } } } } } }, "400": { "description": "Invalid or oversized credentials" }, "401": { "description": "Incorrect email or password" }, "403": { "description": "Missing or mismatched Origin" }, "429": { "description": "Sign-in limited; Retry-After 60" }, "501": { "description": "Password login not configured" }, "503": { "description": "Session creation unavailable" } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/api/v1/auth/browser/demo": { "post": { "operationId": "createDemoBrowserSession", "tags": [ "Authentication" ], "summary": "Sign in to the configured shared demo account", "description": "Available only when NIU_DEMO_LOGIN_EMAIL and NIU_DEMO_LOGIN_PASSWORD are explicitly configured. Requires the configured browser Origin. Verifies the existing account password with ordinary sign-in admission and revocation checks, then issues an HttpOnly browser session cookie. Credentials are never returned. Existing account permissions apply; no account is provisioned. Disabled demo sign-in returns 404. Responses are not cached.", "security": [], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Browser session established." }, "401": { "description": "Demo credentials unavailable or revoked." }, "403": { "description": "Browser origin rejected." }, "404": { "description": "Demo sign-in disabled." }, "429": { "description": "Sign-in admission limit reached." } }, "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/api/v1/auth/browser/token": { "post": { "operationId": "exchangeOperatorTokenForBrowserSession", "summary": "Use an existing user access token in the browser", "description": "Requires an explicit trusted same-origin Origin and a valid durable Operator session token. Installation credentials, inference keys, revoked sessions and expired sessions are refused. Sets the existing HttpOnly SameSite cookie to the original token without creating an identity or session, extending expiry, changing role/scope, or returning the token in JSON. Cookie lifetime is capped at the original remaining lifetime and eight hours; every subsequent request rechecks the original durable session. Requires configured browser authentication origin. Responses are not cached.", "security": [], "x-niu-implementation": "implemented", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Exact configured browser origin, matching the trusted same-origin UI. A missing, mismatched or cross-site origin is refused.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 74, "maxLength": 74, "pattern": "^niu_admin_[0-9a-f]{64}$", "writeOnly": true, "description": "Original user access token; never place it in a URL or browser storage." } } } } } }, "responses": { "204": { "description": "Original session established as an HttpOnly browser cookie; no response body.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "description": "Existing original Operator session transported in the protected HttpOnly SameSite browser cookie, with lifetime bounded by its original expiry. No cookie value example is provided." } } }, "400": { "description": "Malformed JSON or unknown request fields." }, "401": { "description": "Invalid, expired, revoked or non-Operator credential." }, "403": { "description": "Missing, untrusted or cross-site Origin." }, "501": { "description": "Browser authentication origin is not configured." }, "503": { "description": "Durable authentication storage is unavailable." } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/api/v1/auth/browser/logout": { "post": { "operationId": "revokeBrowserMemberSession", "summary": "Revoke and clear the current browser member session", "security": [ { "memberCookie": [] } ], "description": "Requires the configured HTTPS Origin; supplied Sec-Fetch-Site must be a single same-origin value. Revokes the supplied member session and clears the cookie. Already expired or revoked sessions also clear the cookie successfully. Storage failure does not claim successful revocation or clear the cookie. Responses use Cache-Control no-store.", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session unusable and cookie expired; no response body" }, "401": { "description": "Missing or malformed member cookie" }, "403": { "description": "Missing or mismatched Origin" }, "501": { "description": "Password login not configured" }, "503": { "description": "Revocation unavailable; retry before assuming sign-out" } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/auth/logout": { "post": { "operationId": "revokeCurrentMemberSession", "summary": "Sign out the member session supplied in Authorization", "security": [ { "bearerAuth": [] } ], "description": "Available to every member role, independently of password login configuration. Revokes only the supplied active session and records a metadata-only audit event atomically. Other sessions remain active. Installation credentials are not member sessions. When password login is configured, a supplied Origin must match its HTTPS origin. All responses use Cache-Control no-store.", "responses": { "204": { "description": "Current session revoked; no response body" }, "401": { "description": "Missing, invalid, expired or already revoked member session" }, "403": { "description": "Supplied Origin does not match the configured origin" }, "503": { "description": "Storage unavailable; retry sign-out before assuming revocation" } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/auth/login": { "post": { "operationId": "createPasswordSession", "summary": "Exchange member credentials for a scoped eight-hour session", "security": [], "description": "JSON bodies are limited to 4096 bytes. Unknown identities and incorrect passwords return the same 401 response. Durable limits allow five attempts per normalized email and 120 per installation in windows expiring 60 seconds after their first attempt. A supplied Origin must match the configured HTTPS origin. All success and error responses are non-cacheable.", "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email", "password" ], "properties": { "email": { "type": "string", "maxLength": 254, "description": "ASCII email; surrounding spaces and case are normalized." }, "password": { "type": "string", "maxLength": 1024, "description": "At most 1024 UTF-8 bytes; no trimming or normalization." } } } } } }, "responses": { "200": { "description": "Session token returned once; use it as a Bearer credential.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token", "session" ], "properties": { "token": { "type": "string" }, "session": { "$ref": "#/components/schemas/password_sessions_openapi_yaml_Session" } } } } } }, "400": { "description": "Invalid or oversized JSON request." }, "401": { "description": "Email or password is incorrect, or the member was revoked during verification." }, "403": { "description": "Supplied browser Origin is not permitted." }, "429": { "description": "Durable admission limit or bounded password-worker capacity reached.", "headers": { "Retry-After": { "schema": { "type": "string", "const": "60" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "501": { "description": "Password sign-in has not been configured." }, "503": { "description": "Durable storage or credential processing is unavailable; no session token is returned." } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/api/v1/operators/{operator}/password": { "get": { "operationId": "getMemberPasswordConfiguration", "summary": "Read a member's sign-in configuration", "security": [ { "bearerAuth": [] } ], "description": "Requires installation administration or an owner permitted to manage the target member's scope. Returns only the saved email and credential revision, never the password or hash. Available even when password sign-in is disabled; use auth/config to check sign-in availability separately. After an uncertain reset, refresh this revision before another explicit reset. A changed revision is not proof that a particular password was saved. Revoked or missing members return 404. All responses are non-cacheable.", "parameters": [ { "in": "path", "name": "operator", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved sign-in configuration; null email and revision when unconfigured.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "configured", "email", "revision" ], "properties": { "configured": { "type": "boolean" }, "email": { "type": [ "string", "null" ] }, "revision": { "type": [ "integer", "null" ], "minimum": 1 } } } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Member management permission required." }, "404": { "description": "Member is missing", "revoked or outside the caller scope.": null }, "503": { "description": "Saved configuration could not be read." } }, "tags": [ "Users and sessions" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "put": { "operationId": "setMemberPassword", "summary": "Provision or reset an existing member password", "security": [ { "bearerAuth": [] } ], "description": "Requires installation administration or an owner permitted to manage the target member's scope. Admin and viewer roles cannot perform this operation. First provision omits expected_revision; resetting requires the previous returned revision. Changes revoke all previous sessions atomically and append metadata-only audit events. Hashes are never returned. Bodies are limited to 4096 bytes and all success/error responses are non-cacheable.", "parameters": [ { "in": "path", "name": "operator", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email", "password" ], "properties": { "email": { "type": "string", "maxLength": 254, "description": "Unique normalized ASCII email for this member identity." }, "password": { "type": "string", "minLength": 15, "maxLength": 1024, "description": "At most 1024 UTF-8 bytes; spaces and Unicode are preserved." }, "expected_revision": { "type": [ "integer", "null" ], "minimum": 1 } } } } } }, "responses": { "200": { "description": "New credential revision; no password or hash is returned.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision" ], "properties": { "revision": { "type": "integer", "minimum": 1 } } } } } }, "400": { "description": "Invalid email, password bounds or JSON request." }, "401": { "description": "Missing, expired or revoked administrative session." }, "403": { "description": "Role or supplied Origin is not permitted." }, "404": { "description": "Member is outside the caller's scope." }, "409": { "description": "Credential revision changed, member was revoked, or email is already assigned." }, "429": { "description": "Bounded password-worker capacity reached; Retry-After is 60 seconds." }, "501": { "description": "Password sign-in has not been configured." }, "503": { "description": "Durable storage or credential processing is unavailable." } }, "tags": [ "Users and sessions" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/media-rates/{revision}/retire": { "post": { "operationId": "retireCustomerMediaRate", "summary": "End a published customer media rate's eligibility", "description": "Platform-administrator write permission required. Installation credentials and explicitly granted member administrators are supported. Appends an immutable cutoff without modifying the original card or historical job snapshots. Cutoff is inclusive for retirement and must be within the original effective interval, including its start/end boundaries. Exact replay is idempotent; changed cutoff or unknown customer/revision conflicts. Publish the replacement with an effective start matching the cutoff. No rate or procurement fallback occurs if no eligible replacement exists; remaining overlaps are rejected as ambiguous.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "effective_until" ], "properties": { "effective_until": { "type": "integer", "description": "Unix seconds" } } } } } }, "responses": { "200": { "description": "Retirement saved or identical replay accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "effective_until" ], "properties": { "revision": { "type": "string" }, "effective_until": { "type": "string", "pattern": "^-?[0-9]+$" } } } } } } } }, "400": { "description": "Invalid revision or cutoff outside original interval" }, "401": { "description": "Administrator authentication required" }, "403": { "description": "Platform-administrator write permission required" }, "409": { "description": "Missing scoped revision or conflicting previous cutoff" }, "413": { "description": "Body exceeds 1 KiB" }, "422": { "description": "Malformed typed JSON body" }, "503": { "description": "Durable storage unavailable" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/media-rate-models": { "get": { "operationId": "listCustomerMediaRateModels", "summary": "Read named qualified commercial video configuration choices", "description": "Platform-administrator read permission required. Installation credentials and explicitly granted member administrators are supported. Lists currently active, qualified, nonpersonal routes with exact credential/model/offer/schema bindings. No credentials, endpoints, purchase prices or customer charges. Cursor advances over raw model aliases even when invalid schemas are omitted; empty pages can therefore have a continuation. Choices do not authorize dispatch or guarantee later availability.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Bounded current choices", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_after" ], "properties": { "has_more": { "type": "boolean" }, "next_after": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "type": "object", "required": [ "model_alias", "api_key_name", "vendor_id", "offer_revision", "vendor_revision", "model_revision", "schema_revision", "channel", "resolutions", "reference_video" ], "properties": { "model_alias": { "type": "string" }, "api_key_name": { "type": "string" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Internal configuration binding; never a display label." }, "offer_revision": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "string", "pattern": "^[0-9]+$" }, "model_revision": { "type": "string", "pattern": "^[0-9]+$" }, "schema_revision": { "type": "string" }, "channel": { "type": "string" }, "resolutions": { "type": "array", "items": { "type": "string" } }, "reference_video": { "type": "boolean" } } } } } } } } }, "400": { "description": "Invalid cursor or page size" }, "401": { "description": "Administrator authentication required" }, "403": { "description": "Platform-administrator read permission required" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/media-rates/replace": { "post": { "operationId": "replaceCustomerMediaRate", "summary": "Atomically replace a customer media selling schedule", "description": "Platform-administrator write permission required. Installation credentials and explicitly granted member administrators are supported. Publishes the immutable replacement and retires the previous scoped schedule at the new effective start in one transaction. Dimensions and meter must match; competing effective schedules conflict. Identical replay is accepted while route bindings remain current. Any publication or retirement failure rolls back both changes. Historical cards and pinned jobs are unchanged. No procurement fallback or automatic submission retry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "previous_revision", "rate" ], "properties": { "previous_revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "rate": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingCustomerMediaRateCard" } } } } } }, "responses": { "200": { "description": "Replacement committed or identical replay accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision", "effective_from" ], "properties": { "revision": { "type": "string" }, "effective_from": { "type": "string", "pattern": "^-?[0-9]+$" } } } } } } } }, "400": { "description": "Invalid card, changed dimensions or cutoff outside original interval" }, "401": { "description": "Administrator authentication required" }, "403": { "description": "Platform-administrator write permission required" }, "409": { "description": "Missing scoped revision, competing schedule, stale route or conflicting receipt" }, "413": { "description": "Body exceeds 128 KiB" }, "422": { "description": "Malformed typed JSON body" }, "503": { "description": "Durable storage unavailable" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/media-rates": { "post": { "operationId": "publishCustomerMediaRate", "summary": "Publish an immutable customer video selling schedule", "description": "Platform administrator with write access required. Ordinary company members and inference keys cannot publish prices or liability limits. Pins exact credential/model/schema revisions and a configured qualification reference; registration does not qualify commercial supply or enable video dispatch. Rejects personal credentials and stale routes. Replaying identical current configuration is idempotent; changed content under the same revision conflicts. Procurement terms never belong in this body. Maximum JSON body is 128 KiB.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingCustomerMediaRateCard" } } } }, "responses": { "200": { "description": "Customer selling revision published or identical replay accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision" ], "properties": { "revision": { "type": "string" } } } } } } } }, "400": { "description": "Invalid tariff, dimensions, discount or liability configuration" }, "401": { "description": "Administrator authentication required" }, "403": { "description": "Platform-administrator write permission required" }, "409": { "description": "Changed revision, stale route or personal credential" }, "413": { "description": "Body exceeds 128 KiB" }, "422": { "description": "Malformed typed JSON body" }, "503": { "description": "Durable storage unavailable" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "listCustomerMediaRates", "summary": "Read bounded immutable customer selling history", "description": "Platform-administrator read permission required. Installation credentials and explicitly granted member administrators are supported. Ordinary company members and inference keys cannot read platform pricing configuration. Returns original cards, immutable retirement and creation time; never reads Provider purchase terms. Card vendor/model revisions, tariff amount/time values and discount times are exact decimal strings, while quantities retain numerator/denominator strings. Ordering and cursors use the immutable card revision.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Scoped history page, including an empty page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_after" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "card", "retirement_effective_until", "created_at" ], "properties": { "card": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingCustomerMediaRateRecordCard" }, "retirement_effective_until": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+$" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid page size or cursor" }, "401": { "description": "Administrator authentication required" }, "403": { "description": "Platform-administrator read permission required" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/reservations": { "get": { "operationId": "listCustomerBalanceReservations", "summary": "Inspect open customer balance reservations", "description": "Organization-wide owner/admin or installation read access required, matching company balance permissions. Newest-first keyset pages observe one statement snapshot; pages do not share a snapshot. Released reservations are omitted, but a released cursor remains usable. Unknown or foreign cursors and currency-mismatched cursors return 409. Exact nanounit strings distinguish the original reservation from outstanding liability, including known media overrun and excluding posted charge debits. This is a read-only diagnostic; states do not prove nonexecution or authorize releasing funds or retrying inference. No Provider prices, upstream endpoints, credentials or payment references are exposed. Names are current display metadata; IDs are internal links only. Cache-Control no-store. missing_usage_categories lists the absent token categories required by the request-bound customer tariff and selected context tier. Null means classification is unavailable (including unknown aggregate usage, incomplete execution or non-text pricing); an empty list means no required category is missing, not that settlement succeeded. Later price publication does not change this diagnostic.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "Open reservations; empty data is not evidence that paid accounting works.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_before" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "attempt_id", "workspace_id", "api_key_id", "workspace_name", "model", "execution", "usage_confidence", "api_key_name", "currency", "reserved_nanos", "outstanding_nanos", "created_at", "observed_at", "status", "missing_usage_categories" ], "properties": { "attempt_id": { "type": "string", "format": "uuid", "description": "Internal API reference; do not render as a product label." }, "workspace_id": { "type": "string", "format": "uuid", "description": "Internal API reference; do not render as a product label." }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Internal API reference; do not render as a product label." }, "workspace_name": { "type": "string" }, "model": { "type": "string" }, "execution": { "type": "string" }, "usage_confidence": { "type": "string" }, "api_key_name": { "type": [ "string", "null" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "reserved_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "outstanding_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "created_at": { "type": "string", "format": "date-time" }, "observed_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "preparing", "in_progress", "execution_unknown", "usage_unknown", "settlement_pending" ] }, "missing_usage_categories": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "cached_input_tokens", "cache_write_input_tokens", "reasoning_output_tokens" ] }, "description": "Missing required categories under the pinned customer tariff; null when classification is unavailable. Empty does not establish settlement. No prices or private accounting metadata." } } } }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid currency, cursor, limit or query fields." }, "401": { "description": "Authentication required." }, "404": { "description": "Company balance permission required." }, "409": { "description": "Cursor is unknown or does not match the company/currency." } }, "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/charge-reconciliation": { "get": { "operationId": "getCustomerChargeReconciliation", "summary": "Compare customer charge records with prepaid ledger debits", "description": "Organization-wide owner/admin or installation read access required. One database snapshot compares prepaid-bound text and media charges against original charge entries per currency. Refunds do not reduce original charge matching. Reports counts and exact decimal amounts only, with no internal identifiers or Provider prices. Zero counts on an empty account do not establish financial readiness. This is read-only and does not verify external payment settlement, recalculate prices, reconcile legacy invoices or repair discrepancies. Pending settlement can appear as a discrepancy; use a later observation to distinguish an in-flight write from a persistent mismatch.", "responses": { "200": { "description": "Per-currency observations", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "currency", "observed_at", "charge_records", "completed_unaccrued_attempts", "expected_charge_nanos", "posted_charge_nanos", "missing_charge_entries", "mismatched_charge_entries", "unexpected_charge_entries", "duplicate_charge_sources", "settled_open_reservations" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "observed_at": { "type": "string", "format": "date-time" }, "charge_records": { "type": "string", "pattern": "^[0-9]+$" }, "completed_unaccrued_attempts": { "type": "string", "pattern": "^[0-9]+$", "description": "Completed prepaid-bound attempts without a text or media charge record. May await usage or financial recovery; not an amount, corruption finding or authorization to retry inference." }, "expected_charge_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "posted_charge_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "missing_charge_entries": { "type": "string", "pattern": "^[0-9]+$" }, "mismatched_charge_entries": { "type": "string", "pattern": "^[0-9]+$" }, "unexpected_charge_entries": { "type": "string", "pattern": "^[0-9]+$" }, "duplicate_charge_sources": { "type": "string", "pattern": "^[0-9]+$" }, "settled_open_reservations": { "type": "string", "pattern": "^[0-9]+$" } } } } } } } } }, "401": { "description": "Missing or invalid administration credentials" }, "404": { "description": "Company billing scope unavailable to this principal" }, "503": { "description": "Storage unavailable" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/providers/{provider}/offers/{offer}/revisions/{revision}": { "get": { "operationId": "getProviderOfferRevision", "summary": "Read an immutable Provider procurement quote", "description": "Installation administrators or active members of this Provider may read a quote. Ordinary company/workspace ownership grants no procurement access. Provider, offer and revision must all match; inaccessible or missing records return 404. Text prices are exact currency nanounits per million tokens. Media revisions have null text prices; use the separate media rate-card contract. This read does not activate, qualify or reprice an offer. Procurement data must never be exposed in customer workspace billing. Internal identifiers are API references, not display labels.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Immutable procurement quote; no upstream credentials or endpoint.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_ProviderOfferRevision" } } } } } }, "400": { "description": "Malformed path identifier." }, "401": { "description": "Management authentication required." }, "404": { "description": "Provider membership denied or quote identity not found." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/platform/payments/integrations": { "get": { "operationId": "listPaymentIntegrations", "summary": "List supported payment integrations", "description": "Installation credential or an explicit platform-administrator grant required, independent of customer company role. Capability inventory is independent of merchant activation. checkout_enabled and enabled_methods describe locally configured checkout, not merchant approval, funding or verified settlement. Customer checkout additionally requires the matching company currency account. Returns no merchant identity, endpoint or credentials. Refunds means refund initiation; query recovery is limited to the declared scope.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Supported integrations, not enabled customer checkout methods", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "configuration", "checkout", "signed_notifications", "query_recovery", "refunds", "checkout_enabled", "enabled_methods" ], "properties": { "id": { "type": "string", "enum": [ "epay", "stripe", "zhifux" ] }, "name": { "type": "string" }, "configuration": { "type": "string", "enum": [ "administration_api", "server_environment", "server_file" ] }, "checkout": { "type": "boolean" }, "signed_notifications": { "type": "boolean" }, "query_recovery": { "type": "string", "enum": [ "unsupported", "bound_session", "saved_order" ] }, "refunds": { "type": "boolean" }, "checkout_enabled": { "type": "boolean", "description": "A local checkout configuration is enabled; this does not certify merchant activation or actual payment." }, "enabled_methods": { "type": "array", "items": { "type": "string" }, "description": "Configured method identifiers; empty when checkout is disabled. No company balance-account eligibility is implied." } } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration authority required" } }, "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/platform/payments/stripe/verification": { "get": { "operationId": "getStripeVerification", "summary": "Read Stripe verification evidence", "x-niu-implementation": "implemented", "description": "Installation administrator only. Reads evidence bound to current effective Stripe configuration and currency. Account and callback verification are separate; no merchant identity or credentials are returned. Does not contact Stripe.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current configuration-bound verification", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "account_verified": { "type": "boolean" }, "callback_verified": { "type": "boolean" } } } } } } } }, "400": { "description": "Real Stripe checkout is not configured" }, "403": { "description": "Installation administrator required" } }, "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "operationId": "verifyStripeAccount", "summary": "Check the configured Stripe account", "x-niu-implementation": "implemented", "description": "Installation administrator write permission required. Performs a bounded read-only Stripe account check and persists evidence for the current configuration for ten minutes. Does not create checkout, charge money, or assert callback verification. Transient check failure preserves prior evidence only until its original expiry; credential rejection or disabled charges revokes it immediately. Mock mode is excluded. Merchant errors are sanitized.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Account check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "account_enabled", "account_disabled", "credentials_rejected", "check_unavailable" ] } } } } } } } }, "400": { "description": "Real Stripe checkout is not configured" }, "403": { "description": "Installation administrator required" } }, "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/pools": { "put": { "operationId": "setModelRoutePool", "security": [ { "bearerAuth": [] } ], "summary": "Create or revise a model candidate pool", "description": "Platform administration required: installation credentials or an explicitly authorized platform administrator. Ordinary company/workspace ownership does not grant this access. Revisions start at zero for creation. Ownership is immutable. Candidate aliases identify existing credential/model mappings, not nested pools. Personal pools require all candidates owned by that organization; shared pools require nonpersonal priced mappings. Video mappings are rejected. Ordered routing rules evaluate first-match AND conditions before falling back to default_action. Highest eligible priority wins, with weighted selection within that tier. Billing mode selects either unified pool pricing (pool_tariff) or pass-through candidate pricing (candidate_tariff). Chat pools permit at most one successor after a qualified OpenRouter authentication rejection; other failures and uncertain or streamed outcomes do not trigger automatic failover. See the Chat completion contract for exact eligibility and deadline constraints.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "alias", "organization_id", "enabled", "expected_revision", "candidates" ], "properties": { "alias": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]+$" }, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ], "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 4000 }, "slug": { "type": [ "string", "null" ], "maxLength": 80 }, "public_catalog": { "type": "boolean" }, "billing_mode": { "type": "string", "enum": [ "pool_tariff", "candidate_tariff" ] }, "enabled": { "type": "boolean" }, "expected_revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740990 }, "candidates": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "object", "additionalProperties": false, "required": [ "alias", "priority", "weight", "enabled" ], "properties": { "alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "priority": { "type": "integer", "minimum": -1000, "maximum": 1000 }, "weight": { "type": "integer", "minimum": 1, "maximum": 10000 }, "enabled": { "type": "boolean" } } } }, "rules": { "type": "array", "maxItems": 32, "items": { "type": "object" } }, "default_action": { "type": "string", "enum": [ "candidates", "reject" ] } } } } } }, "responses": { "200": { "description": "Saved revision; changes apply to later admission and stale snapshots reject before dispatch", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } } } } } } }, "400": { "description": "Invalid candidates, bounds, ownership, reserved alias or unsupported mapping" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "409": { "description": "Stale revision or attempted ownership change" }, "422": { "description": "Malformed body schema or unknown fields; framework rejection may use plain text." } }, "x-niu-implementation": "implemented", "tags": [ "Model routing" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "listPools", "summary": "List platform-managed model route pools", "description": "Installation credential or explicit platform-administrator grant required. Lists enabled and disabled shared and personal pools with their current configuration. Ordered by alias using database ordering. after is the exclusive alias cursor returned as next_after; it need not identify a currently existing pool. This is a live view, not a cross-page snapshot: new aliases before the cursor require a fresh traversal. No upstream requests, credentials, endpoints or prices are returned. Pool organization identifiers are API references, not display labels. Without alias this is the paginated collection. For compatibility, ?alias= returns the original single-pool envelope; alias cannot be combined with paging parameters. New member reads use /pools/{reference}. The /pools/index route retains its existing collection contract.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]+$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "alias", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Bounded current configurations and continuation cursor.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "data", "has_more", "next_after" ], "additionalProperties": false, "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/handler_operations_json_ModelRoutePool" } }, "has_more": { "type": "boolean" }, "next_after": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_ModelRoutePool" } } } ] } } } }, "400": { "description": "Invalid query, alias cursor or page size; framework query errors may use plain text." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administration required." } }, "tags": [ "Model routing" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pools/index": { "get": { "operationId": "listModelRoutePools", "summary": "List platform-managed model route pools", "description": "Installation credential or explicit platform-administrator grant required. Lists enabled and disabled shared and personal pools with their current configuration. Ordered by alias using database ordering. after is the exclusive alias cursor returned as next_after; it need not identify a currently existing pool. This is a live view, not a cross-page snapshot: new aliases before the cursor require a fresh traversal. No upstream requests, credentials, endpoints or prices are returned. Pool organization identifiers are API references, not display labels.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]+$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Bounded current configurations and continuation cursor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_after" ], "additionalProperties": false, "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/handler_operations_json_ModelRoutePool" } }, "has_more": { "type": "boolean" }, "next_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid query, alias cursor or page size; framework query errors may use plain text." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administration required." } }, "tags": [ "Model routing" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/pools/history": { "get": { "operationId": "listModelRoutePoolHistory", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "alias", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "before_revision", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "At most 100 immutable revisions in descending order", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "allOf": [ { "$ref": "#/components/schemas/handler_operations_json_ModelRoutePool" }, { "type": "object", "required": [ "recorded_at" ], "properties": { "recorded_at": { "type": "string", "format": "date-time" } } } ] } } } } } } }, "400": { "description": "Invalid query or revision cursor; framework query errors may use plain text." }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administration required" }, "404": { "description": "Pool not found" } }, "x-niu-implementation": "implemented", "summary": "Read immutable model candidate pool revisions", "description": "Platform administration required: installation credentials or an explicitly authorized platform administrator. Ordinary company/workspace ownership does not grant this access.", "tags": [ "Model routing" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/token-rate-limit": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyTokenRateLimit", "description": "Scoped readers may inspect the policy shared across secret rotations.", "responses": { "200": { "description": "Null revision means never configured. Null removes the limit; zero denies dispatch.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_KeyTokenRatePolicy" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Read API key token rate policy", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/token-rate-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeyTokenRateLimit", "description": "Owner or installation administrator only. Rotation preserves this policy. Does not cancel already admitted requests.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "tokens_per_minute", "expected_revision" ], "properties": { "tokens_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyTokenRateTokenRateLimit" }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New policy and immutable history committed atomically. Existing unresolved work remains counted across revisions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid limit or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "409": { "description": "Stale policy revision" }, "422": { "description": "Missing or invalid JSON fields" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Set API key token rate policy", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/token-rate-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/token-rate-limit/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeyTokenRateLimitHistory", "description": "Scoped readers receive descending revisions shared across rotations. Use the last revision as the next page cursor.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Immutable policy history; no internal actor identifiers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "tokens_per_minute", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "tokens_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyTokenRateTokenRateLimit" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "summary": "List API key token rate policy history", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/token-rate-limit/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/token-usage-window": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyTokenUsageWindow", "description": "Scoped reader access. Dispatches in the rolling 60 seconds ending at window_end, across secret rotations. Known subtotals exclude unknown requests; zero known tokens does not mean zero actual usage. This endpoint does not enforce TPM and exposes no Provider cost.", "responses": { "200": { "description": "One consistent database snapshot, including an empty window for an unused key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "window_seconds", "window_end", "requests", "known_usage_requests", "unknown_usage_requests", "known_prompt_tokens", "known_completion_tokens" ], "properties": { "window_seconds": { "type": "integer", "const": 60 }, "window_end": { "type": "string", "format": "date-time" }, "requests": { "type": "integer", "minimum": 0 }, "known_usage_requests": { "type": "integer", "minimum": 0 }, "unknown_usage_requests": { "type": "integer", "minimum": 0 }, "known_prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "known_completion_tokens": { "type": "string", "pattern": "^[0-9]+$" } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Read permission required" }, "404": { "description": "Workspace outside operator scope or key absent from workspace" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Read API key token usage window", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/token-usage-window", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/spending-limit": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeySpendingLimits", "description": "Scoped readers may inspect customer commitments. Rotated keys share the original spending identity. Personal upstream routes do not consume customer funds. No Provider costs or company balance are exposed.", "responses": { "200": { "description": "Account currencies and lifetime key commitments; null limit means unlimited and null revision means never configured.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "currency", "limit_nanos", "revision", "committed_nanos", "remaining_nanos" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "limit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "committed_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "remaining_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Maximum of cap minus committed customer amount and zero; null for unlimited. This is key allowance only, not company balance or guaranteed admission." } } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Key does not exist in the authorized workspace" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "summary": "List API key spending limits", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/spending-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/spending-limit/{currency}": { "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeySpendingLimit", "description": "Workspace/company owner or installation administrator. Cap includes settled customer charges minus refunds plus unreleased reservations, across secret rotations. Lowering below committed liability is rejected. Account and workspace limits still apply. Writes do not add funds. Null explicitly restores unlimited; omission is rejected.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "limit_nanos", "expected_revision" ], "properties": { "limit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Nonnegative signed-64-bit nanounits or explicit null." }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New immutable policy revision recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid amount or currency" }, "401": { "description": "Authentication required" }, "402": { "description": "Proposed limit is below committed key liability" }, "403": { "description": "Owner permission required" }, "404": { "description": "Key does not exist in the authorized workspace" }, "409": { "description": "Stale revision, missing account, or unresolved attribution" }, "422": { "description": "Missing or invalid body fields" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "x-niu-implementation": "implemented", "summary": "Set API key spending limit", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/spending-limit/{currency}", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/spending-limit/{currency}/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeySpendingLimitHistory", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "description": "Descending immutable revision history shared across rotations. Use the last returned revision as before_revision for the next page. Returns currency, nullable limit_nanos, revision, recorded_at, actor_kind and actor_name; never an internal actor identifier.", "responses": { "200": { "description": "Data array of policy revisions", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "currency", "limit_nanos", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "limit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid currency or pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Key does not exist in the authorized workspace" } }, "x-niu-implementation": "implemented", "summary": "List API key spending history", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/spending-limit/{currency}/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/ip-policy": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyIpPolicy", "description": "Scoped readers may inspect the policy shared across secret rotations. Storage reads use a read-only snapshot with transaction-local 250 ms lock and 2 s statement limits.", "responses": { "200": { "description": "Null revision means never configured. Null networks permit all sources; an empty array denies all sources.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "allowed_cidrs", "revision" ], "properties": { "allowed_cidrs": { "type": [ "array", "null" ], "maxItems": 64, "items": { "type": "string", "maxLength": 64 }, "description": "IPv4/IPv6 addresses or CIDRs, normalized to network CIDRs. Null permits all; empty denies all." }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "503": { "description": "Storage read unavailable, including a bounded lock or statement timeout. Preserve known policy/history; this does not permit bypassing source restrictions." } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "summary": "Read API key source policy", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/ip-policy", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeyIpPolicy", "description": "Owner or installation administrator only. Rotation preserves this policy. Does not cancel already admitted requests.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "allowed_cidrs", "expected_revision" ], "properties": { "allowed_cidrs": { "type": [ "array", "null" ], "maxItems": 64, "items": { "type": "string", "maxLength": 64 }, "description": "IPv4/IPv6 addresses or CIDRs, normalized to network CIDRs. Null permits all; empty denies all." }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New policy and immutable history committed atomically.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid network or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "409": { "description": "Stale policy revision" }, "422": { "description": "Missing or invalid JSON fields" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "summary": "Set API key source policy", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/ip-policy", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/ip-policy/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeyIpPolicyHistory", "description": "Scoped readers receive descending revisions shared across rotations. Use the last revision as the next page cursor. Storage reads use a read-only snapshot with transaction-local 250 ms lock and 2 s statement limits.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Immutable policy history; no internal actor identifiers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "allowed_cidrs", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "allowed_cidrs": { "type": [ "array", "null" ], "maxItems": 64, "items": { "type": "string", "maxLength": 64 }, "description": "IPv4/IPv6 addresses or CIDRs, normalized to network CIDRs. Null permits all; empty denies all." }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "503": { "description": "Storage read unavailable, including a bounded lock or statement timeout. Preserve known policy/history; this does not permit bypassing source restrictions." } }, "x-niu-implementation": "implemented", "summary": "List API key source policy history", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/ip-policy/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/request-rate-limit": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyRequestRateLimit", "description": "Scoped readers may inspect the policy shared across secret rotations.", "responses": { "200": { "description": "Null revision means never configured. Null removes the limit; zero denies dispatch.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_KeyRequestRatePolicy" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Read API key request rate policy", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/request-rate-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeyRequestRateLimit", "description": "Owner or installation administrator only. Rotation preserves this policy. Does not cancel already admitted requests.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "requests_per_minute", "expected_revision" ], "properties": { "requests_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyRequestRateRequestLimit" }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New policy and immutable history committed atomically. Rolling windows persist across revisions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid limit or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "409": { "description": "Stale policy revision" }, "422": { "description": "Missing or invalid JSON fields" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Set API key request rate policy", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/request-rate-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/request-rate-limit/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeyRequestRateLimitHistory", "description": "Scoped readers receive descending revisions shared across rotations. Use the last revision as the next page cursor.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Immutable policy history; no internal actor identifiers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "requests_per_minute", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "requests_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyRequestRateRequestLimit" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "summary": "List API key request rate policy history", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/request-rate-limit/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/capacity": { "get": { "operationId": "listKeyCapacityRequests", "summary": "Inspect requests contributing unresolved key capacity", "description": "Workspace read authority required. Includes the full secret-rotation lineage. Concurrency uses unresolved dispatched requests. Tokens uses reservations and unbounded usage from unresolved dispatches plus completed unknown-usage requests in the rolling 60-second window, matching the token-budget calculation; known recent usage is not returned here. Each page has a fresh statement snapshot. UUID keyset cursor is internal; rows may resolve between pages. Refresh to restart investigation. This read does not contact Providers, reconcile usage, release reservations or retry requests. No credentials, prompt content or procurement data. Cache-Control no-store.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "concurrency", "tokens" ], "default": "concurrency" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Matching current contributors and snapshot count", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "total", "snapshot_at", "next_after" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "attempt_id", "model_alias", "key_name", "created_at", "dispatched_at", "completed_at", "execution", "reserved_tokens" ], "properties": { "attempt_id": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "key_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "dispatched_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "execution": { "type": "string", "enum": [ "may_have_executed", "confirmed_completed" ] }, "reserved_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } } } }, "total": { "type": "integer", "minimum": 0 }, "snapshot_at": { "type": "string", "format": "date-time" }, "next_after": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid query" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient management permission" }, "404": { "description": "Key or workspace outside the authorized scope" }, "409": { "description": "Cursor unavailable; restart pagination" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/capacity", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/concurrency-limit": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getKeyConcurrencyLimit", "description": "Scoped readers may inspect the policy shared across secret rotations.", "responses": { "200": { "description": "Null revision means never configured. Null removes the limit; zero denies dispatch.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_KeyConcurrencyPolicy" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient management permission" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Read API key concurrency policy", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/concurrency-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "security": [ { "bearerAuth": [] } ], "operationId": "setKeyConcurrencyLimit", "description": "Owner or installation administrator only. Rotation preserves this policy. Does not cancel already admitted requests.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "max_concurrent_requests", "expected_revision" ], "properties": { "max_concurrent_requests": { "$ref": "#/components/schemas/handler_operations_json_KeyConcurrencyConcurrencyLimit" }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Zero for initial configuration; maximum 9223372036854775806." } } } } } }, "responses": { "200": { "description": "New policy and immutable history committed atomically. Existing unresolved work remains counted across revisions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } } } } } }, "400": { "description": "Invalid limit or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Owner permission required" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" }, "409": { "description": "Stale policy revision" }, "422": { "description": "Missing or invalid JSON fields" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "summary": "Set API key concurrency policy", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/concurrency-limit", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/concurrency-limit/history": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "listKeyConcurrencyLimitHistory", "description": "Scoped readers receive descending revisions shared across rotations. Use the last revision as the next page cursor.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Immutable policy history; no internal actor identifiers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "max_concurrent_requests", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "max_concurrent_requests": { "$ref": "#/components/schemas/handler_operations_json_KeyConcurrencyConcurrencyLimit" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid pagination" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient management permission" }, "404": { "description": "Workspace is outside operator scope, or key is absent from authorized workspace" } }, "summary": "List API key concurrency policy history", "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/keys/{key}/concurrency-limit/history", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/image-ingestions": { "get": { "operationId": "listImageIngestions", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "summary": "Recover this API key's saved ingestion history", "description": "Returns at most fifty newest records ordered by consent creation time and identity. Follow next_cursor as before until null. History includes revoked, expired and completed records without changing consent, publishing source capabilities or contacting an upstream service. A cursor from another key is unavailable. Later inserts do not shift continuation pages.", "parameters": [ { "in": "query", "name": "before", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Customer-safe status array in data and nullable next_cursor; same safe fields as individual status" }, "400": { "description": "Invalid cursor or query" }, "401": { "description": "Active original API key required" }, "404": { "description": "Cursor unavailable under this key" } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/image-ingestions/{id}/readiness/{read_id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "read_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "refreshIngestedImageReadiness", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "summary": "Observe accepted image status using its original account", "description": "Separate current GetAsset permission and the original API key are required. One outstanding observation per ingestion, sixty per rolling hour and four concurrent gateway reads. One fixed bounded GetAsset request validates asset identity, group, project and image type before persisting status. The worker survives disconnect; interrupted reads record failure. This does not repeat creation, download media or grant reusable-reference rights. A claimed read_id is never replayed; use GET to inspect its saved outcome.", "requestBody": { "required": false, "description": "Omit the body or send an empty JSON object. Unknown fields and other JSON values are rejected before any upstream claim.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } }, "responses": { "200": { "description": "Persisted observation; status pending/succeeded/failed, asset_status Active/Processing/Failed or null, safe reason, duration_ms, observed_at and reuse_available false. A successful Processing observation does not imply an active asset." }, "400": { "description": "Expected an empty command object" }, "401": { "description": "Active original API key required" }, "403": { "description": "Current workspace authorization required" }, "409": { "description": "Accepted ingestion or reviewed permission unavailable, claimed read identity, pending observation or polling limit" }, "503": { "description": "Read capacity, credentials or persistence unavailable" } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } }, "get": { "operationId": "getIngestedImageReadiness", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "summary": "Retrieve one persisted readiness observation without an upstream request", "responses": { "200": { "description": "Customer-safe observation; no upstream identifiers, raw response, credentials or commercial procurement data" }, "401": { "description": "Active original API key required" }, "404": { "description": "Observation unavailable under this key and ingestion" } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/image-sources": { "post": { "operationId": "prepareInspectedImageSource", "summary": "Inspect and temporarily retain one exact inline image", "description": "Active workspace inference key required. Every required image detector must have current workspace processing consent. Detector approval is obtained server-side; client verdicts, hashes and remote URLs are rejected. Saves encrypted approved bytes, never publishes a fetch token or dispatches an asset. Four preparations may run concurrently. Retention is 1 to 900 seconds, with separate workspace and installation storage ceilings. Maximum JSON body is 12 MiB plus 1024 bytes. No request-payload logging on this endpoint. The source ID is an internal API reference, not a display label. Missing inspection prerequisites fail before detector disclosure.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "image", "valid_for_seconds" ], "properties": { "image": { "type": "string", "maxLength": 12582912, "description": "Inline PNG, JPEG or WebP base64 data URL subject to configured detector decode limits." }, "valid_for_seconds": { "type": "integer", "minimum": 1, "maximum": 900 } } } } } }, "responses": { "201": { "description": "Approved encrypted source retained; no image bytes or fetch capability returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "source_id", "retained", "retention_seconds" ], "properties": { "source_id": { "type": "string", "format": "uuid" }, "retained": { "const": true }, "retention_seconds": { "type": "integer", "minimum": 1, "maximum": 900 } } } } } } } }, "400": { "description": "Invalid or unsupported input, including a JSON body exceeding the endpoint limit" }, "401": { "description": "Active inference key required" }, "403": { "description": "Current inspection consent or detector approval unavailable. Missing authorized inspection prerequisites use error.type image_inspection_required; other policy refusals retain their existing error type." }, "409": { "description": "Workspace policy changed during preparation" }, "503": { "description": "Encryption, preparation capacity, storage capacity or durable storage unavailable" } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/media/image-sources/{id}": { "delete": { "operationId": "eraseInspectedImageSource", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "summary": "Erase this API key's retained source bytes", "description": "Idempotent and opaque for absent or foreign sources. Immutable provenance remains. Does not cancel an already accepted upstream asset or erase it upstream.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Scoped source erased or unavailable; no existence disclosure" }, "401": { "description": "Active API key required" } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/media/image-ingestions/{id}/dispatch": { "post": { "operationId": "dispatchImageIngestion", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "summary": "Claim and dispatch one inspected image ingestion", "description": "Requires original source API key, current policy, detector terms and reviewed CreateAsset permission. A trusted configured HTTPS origin serves the exact inspected bytes using an expiring capability. Four uploads may run concurrently. The bounded worker survives client disconnect; its immutable accepted or uncertain outcome is persisted. Never automatically replay an uncertain upload. Acceptance does not mean asset readiness. No client-supplied source URL, destination override or credential is accepted.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "description": "Omit the body or send an empty JSON object. Unknown fields and other JSON values are rejected before any upstream claim.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } }, "responses": { "200": { "description": "Persisted customer-safe accepted or uncertain ingestion status" }, "400": { "description": "Expected an empty command object" }, "401": { "description": "Active original API key required" }, "403": { "description": "Current policy required" }, "409": { "description": "Consent unavailable, already claimed or no longer authorized" }, "503": { "description": "Source origin or encryption unavailable, upload capacity exhausted or worker storage unavailable" } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/media/image-ingestions/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "operationId": "prepareImageIngestionConsent", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "summary": "Consent to ingestion of one inspected image into one ordinary asset group", "description": "Requires the original source API key and current workspace policy. Repeating identical unexpired consent is idempotent; consent cannot be renewed or retargeted. The dispatch_available flag requires retained unexpired source bytes, unrevoked unclaimed consent, configured source origin and encryption; it is not an admission guarantee. Erasing the source disables dispatch without rewriting consent or accepted history. This endpoint neither claims nor dispatches an upload. Dispatch requires a configured public HTTPS source origin and separate admission checks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "source_id", "group_intent_id", "authorization_id", "valid_for_seconds", "confirm_ingestion" ], "properties": { "source_id": { "type": "string", "format": "uuid" }, "group_intent_id": { "type": "string", "format": "uuid" }, "authorization_id": { "type": "string", "format": "uuid" }, "valid_for_seconds": { "type": "integer", "minimum": 1, "maximum": 900 }, "confirm_ingestion": { "type": "boolean", "const": true } } } } } }, "responses": { "200": { "description": "Identical active consent already exists" }, "201": { "description": "Consent saved; returns data with consent_id, expires_at, status, consent_revoked and dispatch_available" }, "400": { "description": "Invalid or unconfirmed consent" }, "401": { "description": "Active API key required" }, "403": { "description": "Current workspace policy required" }, "409": { "description": "Source, destination or reviewed authorization unavailable; consent conflict" } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } }, "get": { "operationId": "getImageIngestionConsent", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "summary": "Read customer-safe ingestion status under the original API key", "responses": { "200": { "description": "Consent status with nullable allowlisted reason, duration_ms and observed_at from its immutable outcome; no credentials, source tokens, upstream identifiers or procurement data" }, "401": { "description": "Active API key required" }, "404": { "description": "Consent unavailable under this API key" } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } }, "delete": { "operationId": "revokeImageIngestionConsent", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "summary": "Revoke source publication consent without erasing immutable history", "description": "Idempotent for the original API key. Revocation does not cancel an upload already accepted upstream or resolve an uncertain outcome.", "responses": { "204": { "description": "Consent revoked or already revoked" }, "401": { "description": "Active API key required" }, "404": { "description": "Consent unavailable under this API key" } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/media/sources/{token}": { "head": { "operationId": "rejectMediaSourceHead", "summary": "Reject HEAD probes of image source capabilities", "description": "Always returns 405 without a response body. This handler does not authenticate, validate, claim or consume the path capability and does not access storage or return image metadata. HEAD cannot establish whether a source exists or is available. Only GET performs capability delivery checks. Capability tokens are secrets and must not be logged or disclosed. No bearer or workspace API key is required to receive this uniform refusal.", "x-niu-implementation": "implemented", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Opaque short-lived source capability; ignored by the HEAD refusal handler.", "schema": { "type": "string" } } ], "responses": { "405": { "description": "HEAD is deliberately unsupported; empty response body regardless of capability validity.", "headers": { "Cache-Control": { "description": "no-store, max-age=0", "schema": { "type": "string", "enum": [ "no-store, max-age=0" ] } }, "Referrer-Policy": { "description": "no-referrer", "schema": { "type": "string", "enum": [ "no-referrer" ] } }, "X-Content-Type-Options": { "description": "nosniff", "schema": { "type": "string", "enum": [ "nosniff" ] } }, "Cross-Origin-Resource-Policy": { "description": "same-origin", "schema": { "type": "string", "enum": [ "same-origin" ] } }, "Content-Security-Policy": { "description": "default-src 'none'; sandbox", "schema": { "type": "string", "enum": [ "default-src 'none'; sandbox" ] } } } } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } }, "get": { "operationId": "fetchInspectedImageSource", "security": [], "summary": "Fetch exact approved image bytes using an expiring capability", "description": "Internal Provider handoff capability, not a customer download API. The secret path token authorizes at most four deliveries within sixty seconds. Current consent, policy, detector configuration and retained content are checked on every fetch. Never log or persist the token URL. Issuance is not exposed by this API. Query parameters, request bodies and range requests are unsupported.", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string", "pattern": "^nis_[a-f0-9]{64}$" } } ], "responses": { "200": { "description": "Exact verified image bytes; Cache-Control no-store, Referrer-Policy no-referrer and X-Content-Type-Options nosniff. No destination credentials are returned.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Unsupported query or request body" }, "404": { "description": "Opaque unavailable capability or source" }, "405": { "description": "Only GET is supported" }, "416": { "description": "Range requests are unsupported" }, "503": { "description": "Transfer capacity exhausted", "headers": { "Retry-After": { "schema": { "type": "integer", "const": 1 } } } } }, "tags": [ "Image ingestion" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/v1/branding": { "get": { "operationId": "getPublicBranding", "summary": "Read public branding and theme defaults", "description": "Public safe projection only; no authentication required. Returns display name, normalized logo/favicon PNG data URLs, default appearance and light/dark token maps; excludes actors, credentials and commercial settings. When no saved configuration exists, returns revision string 0 and Niu defaults. Theme fields are part of settings; there is no separate theme endpoint.", "security": [], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Branding revision and settings in data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_BrandingConfiguration" } } } }, "503": { "description": "Durable storage unavailable." } }, "tags": [ "Branding and settings" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/api/v1/platform/branding": { "get": { "operationId": "getBranding", "summary": "Read platform branding and theme configuration", "description": "Installation credentials or an explicit platform-administrator grant required; company owner/admin role alone does not grant platform administration. Returns the same public-safe branding/theme shape. When no saved configuration exists, returns revision string 0 and Niu defaults. Theme fields are part of settings; there is no separate theme endpoint.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Branding revision and settings in data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_BrandingConfiguration" } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administration required." }, "503": { "description": "Durable storage unavailable." } }, "tags": [ "Branding and settings" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "put": { "operationId": "saveBranding", "summary": "Save platform branding and theme configuration", "description": "Installation credentials or an explicit platform-administrator grant required; company owner/admin role alone does not grant platform administration. Returns the same public-safe branding/theme shape. Canonical nonnegative decimal expected_revision string controls atomic snapshot and audit save. Valid display name is nonempty, already trimmed and at most 80 Unicode characters without controls. Palette maps only accept eight supported tokens with six-digit hex colors and readable contrast; empty maps inherit Niu defaults. No arbitrary CSS or executable branding is accepted. Optional null/omitted images reset to defaults. PNG images are decoded and re-encoded before persistence. Route JSON body limit is 450000 bytes. Successful save returns the exact committed snapshot and incremented string revision.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Branding revision and settings in data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_BrandingConfiguration" } } } }, "400": { "description": "Invalid revision, name, palette, contrast or image." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administration required." }, "409": { "description": "Stale revision, exhausted revision or image normalization capacity exceeded; no accepted overwrite." }, "413": { "description": "JSON body exceeds route size limit." }, "415": { "description": "JSON content type required." }, "422": { "description": "Invalid JSON body shape." }, "503": { "description": "Durable storage unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "settings" ], "properties": { "expected_revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "settings": { "$ref": "#/components/schemas/handler_operations_json_BrandingSettings" } } } } } }, "tags": [ "Branding and settings" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/v1/video/models": { "get": { "operationId": "listVideoModels", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "summary": "Read customer-safe configured text-video capabilities", "description": "Current workspace key grants, Provider availability, personal ownership and video-compatible Guardrails apply. Omits unsupported channels/meters, callback controls and media-reference inputs. Returns only mapped output choices without credentials, upstream mappings, revisions or procurement prices. This read makes no upstream calls and does not guarantee tariffs, funds or future admission; estimate and submission recheck those independently.", "responses": { "200": { "description": "Configured text-video capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoModelList" } } } }, "401": { "description": "Invalid or inactive credential" }, "403": { "description": "Workspace permission denied" } }, "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/video/estimate": { "post": { "operationId": "estimateVideoGeneration", "summary": "Estimate a configured text-video request without submission", "description": "Checks current key/model, route, capability, tariff and policy access. Performs no upstream request, job creation, reservation or debit. Estimates are not binding quotes, final charges or admission guarantees. Submission rechecks current configuration and available funds. Owner-funded amounts remain null; missing output estimators and unqualified contracts are unavailable.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "content" ], "additionalProperties": true, "properties": { "model": { "type": "string" }, "content": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string", "minLength": 1 } } } } } } } } }, "responses": { "200": { "description": "Nonbinding estimate and independently reviewed maximum charge", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "object", "model", "mode", "effective_output", "estimate", "maximum_charge_nanos", "selected_at" ], "properties": { "object": { "const": "video.estimate" }, "model": { "type": "string" }, "mode": { "type": "string", "enum": [ "owner_funded", "customer" ] }, "effective_output": { "$ref": "#/components/schemas/handler_operations_json_VideoJobBilling" }, "estimate": { "$ref": "#/components/schemas/handler_operations_json_VideoJobBilling" }, "unit_code": { "type": [ "string", "null" ] }, "maximum_charge_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Customer maximum from separately reviewed liability; not funds reserved by this read." }, "maximum_charge_atoms": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Customer maximum in Credits atoms from separately reviewed liability; not funds reserved by this read." }, "selected_at": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Customer tariff selection time in Unix seconds; does not guarantee future availability." } } } } } }, "400": { "description": "Request violates configured capabilities" }, "401": { "description": "Invalid credential" }, "403": { "description": "Policy cannot be satisfied" }, "404": { "description": "Model access denied" }, "501": { "description": "Unsupported channel, meter, estimator, media or callback contract" }, "503": { "description": "Qualified route or original tariff binding unavailable" } }, "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/video/jobs/{id}/observations": { "get": { "summary": "Read saved video query observations", "description": "Reads immutable, content-free saved query receipts in descending observation-time/receipt order. Reported quantity is not a customer charge or settled usage. Missing/invalid quantities remain explicit; provider timestamps are epoch seconds, not measured transport spans. Does not poll upstream, submit work, reserve funds or mutate financial state. No upstream identity, URL, credential, raw error, cost, procurement price or protocol configuration is returned. Cursor and receipt page share a bounded read-only snapshot (250 ms lock / 2 s statement limits); authorization and whole-request deadlines are separate. Separate pages are live views. Cache-Control no-store.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "after", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Saved observations only; empty data means no saved query receipt in this range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VideoQueryObservationPage" } } } }, "400": { "description": "Malformed cursor or page size." }, "401": { "description": "Invalid, expired or revoked credential." }, "403": { "description": "Source or workspace permission denied." }, "404": { "description": "Unknown job or outside authorized workspace/model scope." }, "409": { "description": "Cursor absent from this job scope." }, "503": { "description": "Storage read unavailable; never empty successful history." } }, "x-niu-implementation": "implemented", "operationId": "videoQueryObservations", "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/video/jobs/{id}/billing": { "get": { "operationId": "retrieveVideoJobBilling", "summary": "Read saved customer video billing", "description": "Current workspace/model authorization applies. This read performs no upstream query or settlement. Exact amounts are decimal strings in billionths of the declared currency. Only a posted customer debit is a charge; unresolved liability remains explicit. Personal owner-funded jobs have no Niu customer price or charge. Procurement terms and internal revision identifiers are excluded.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved customer accounting snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VideoJobBilling" } } } }, "401": { "description": "Invalid credential" }, "404": { "description": "Missing job or workspace/model access denied" } }, "x-niu-implementation": "implemented", "x-niu-status": "Reads persisted scoped evidence without upstream dispatch. Available results and customer charge settlement require separate evidence.", "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/video/jobs/{id}/timings": { "get": { "operationId": "retrieveVideoTransportTimings", "summary": "Read measured gateway video transport spans", "description": "Same current workspace/model authorization as job reads. Returns at most the latest 100 spans in chronological order with explicit truncation. Submission/query network intervals are distinct from Provider queue/run timestamps; unavailable is a transport outcome, not a generation failure or refund. No upstream references or internal span IDs are exposed.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Measured spans; missing observations are not invented", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more" ], "properties": { "lifecycle": { "type": "object", "additionalProperties": false, "required": [ "source", "submitted_unix_ms", "observations", "conflicting_terminal" ], "properties": { "source": { "type": "string", "enum": [ "gateway_observation" ] }, "submitted_unix_ms": { "type": [ "integer", "null" ] }, "conflicting_terminal": { "type": "boolean" }, "observations": { "type": "array", "maxItems": 5, "items": { "type": "object", "additionalProperties": false, "required": [ "status", "observed_unix_ms" ], "properties": { "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "unknown" ] }, "observed_unix_ms": { "type": "integer" } } } } } }, "has_more": { "type": "boolean" }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "phase", "started_unix_ms", "elapsed_ms", "outcome" ], "properties": { "phase": { "type": "string", "enum": [ "submission", "query", "result" ], "description": "Result measures retrieval transport only; received does not imply client delivery or another generation." }, "started_unix_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "elapsed_ms": { "type": "integer", "minimum": 0, "maximum": 120000 }, "outcome": { "type": "string", "enum": [ "received", "unavailable" ] }, "upstream_http_status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599, "description": "Safe HTTP failure status only; null for historical or unclassified outcomes. Does not prove generation nonexecution or authorize a refund." }, "upstream_error_code": { "type": [ "string", "null" ], "maxLength": 128, "description": "Bounded observed Provider error code; no response message or body." }, "upstream_request_id": { "type": [ "string", "null" ], "maxLength": 200, "description": "Bounded observed Provider correlation identifier for diagnostics." }, "transport_phase": { "type": [ "string", "null" ], "enum": [ "connection", "request", null ], "description": "Observed stage only; historical unknown remains null and does not prove nonexecution." } } } } } } } } }, "401": { "description": "Invalid credential" }, "404": { "description": "Missing job or workspace/model access denied" } }, "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/video/jobs/{id}/refresh": { "post": { "operationId": "refreshOwnerFundedVideoJob", "summary": "Refresh one direct-channel video job", "description": "Rechecks current workspace/model/policy access and original pinned account/route. Performs one bounded GET and applies saved status evidence. Missing references require reconciliation and never trigger a new generation. Does not expose private result URLs. Explicit refresh supports personal ownership or the original customer pricing binding. Reported successful customer usage settles the pinned price once; missing/conflicting usage retains liability. Opt-in automatic recovery includes prepaid jobs; successful jobs with missing usage or unposted liability keep recovery active. Saved successful reported usage can settle locally without another upstream query, including after key revocation; new queries still require a current key. Result retrieval and live channel qualification remain pending.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Refreshed durable scoped state" }, "401": { "description": "Invalid credential" }, "403": { "description": "Current policy denies access" }, "404": { "description": "Missing job or workspace/model access denied" }, "409": { "description": "Missing reference or original route changed" }, "501": { "description": "Unsupported recovery channel" }, "502": { "description": "Query could not be refreshed; original generation is not retried" } }, "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/video/jobs": { "get": { "operationId": "listVideoJobHistory", "summary": "List durable workspace video jobs", "description": "Reads saved dispatched jobs, including uncertain submissions, in newest-first creation order with an ID tie-breaker. Applies current key workspace/model grants and returns no upstream references, prompts, credentials or procurement terms. Listing does not poll or regenerate videos. Cursor jobs must remain accessible under the current key. New head entries do not move existing cursor positions.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "next_before from the preceding page; scoped to currently accessible jobs." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Saved scoped job history", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_before" ], "properties": { "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "model", "status", "created_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "video.job" }, "model": { "type": "string" }, "created_at_ms": { "type": "string", "pattern": "^-?[0-9]+$", "description": "Exact Unix milliseconds from the saved attempt." }, "status": { "type": "string", "enum": [ "submission_unknown", "queued", "running", "succeeded", "failed", "unknown", "reconciliation_required" ] } } } } } } } } }, "400": { "description": "Invalid limit, unknown query field, malformed or inaccessible cursor" }, "401": { "description": "Invalid, expired or revoked credential" } }, "x-niu-implementation": "implemented", "x-niu-status": "Reads persisted scoped evidence without upstream dispatch. Available results and customer charge settlement require separate evidence.", "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } }, "post": { "operationId": "createOwnerFundedVideoJob", "summary": "Submit a schema-validated video job", "description": "Personal routes support configured ark-direct-v1 or openrouter-video-v1 channels. Customer-funded video currently requires a qualified ark-direct-v1 route and video_tokens pricing; OpenRouter remains personal-only. Shared routes with a legacy procurement budget are unsupported, while personal routes retain ordinary authorization and key limits. Exactly one upstream submission follows durable dispatch intent. HTTP or transport errors retain submission_unknown and any unresolved liability. Observed non-success HTTP statuses are saved as upstream_http_error in scoped request diagnostics, without upstream bodies or credentials; they do not prove nonexecution or authorize a retry. Fresh creation responses include x-niu-attempt-id. Logs retain the inspected Niu request and delivered Niu creation response for up to 24 hours by default; x-niu-log-payloads: false opts out. Requests larger than the 1 MiB capture bound are not retained. This is not an upstream transport-body capture, and replay does not recreate deleted or expired payloads. Optional workspace-scoped Idempotency-Key supports text and schema-approved upstream URL creation: identical replay returns the original reference and current saved status, including after restart. Changed input conflicts. Unkeyed requests are not idempotent. Configured controls, reference inputs and required inspection remain subject to the selected schema and supported channel. Ordinary public HTTPS image/audio/video URLs are forwarded only when the exact selected upstream schema supports them. Inline image data follows the configured schema. Explicit required image policies still enforce local inspection; unsupported remote inspection fails closed. Short-lived ordinary ingested_image references accept Niu ingestion/readiness IDs with explicit consent_to_reuse. Provider asset URIs remain private and are resolved only for the exact selected Ark route. This does not grant durable library or portrait rights; expired, erased, revoked or unavailable bindings fail closed before dispatch. Durable workspace image references do not reuse Provider readiness or old inspection receipts; they undergo fresh current inspection and atomic local-content authorization. Owned Provider references use content.type provider_asset with provider_asset.id identifying a Niu workspace asset, not a raw upstream URI. Current scope, model, account, acknowledged creation and Active asset state are checked; the same live binding is checked atomically with dispatch. Source model revision is retained as history, while current selected model/schema and tariffs govern the request. Kind, roles and input limits follow backend metadata and the selected schema. Explicit required image inspection refuses these remote assets; ordinary default policy adds no detector. Mixing these references with ingested/workspace material or inline image data is currently unsupported. On creation, idempotency and request captures retain Niu IDs and inspected text, never the resolved asset URI.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Reuse only with the same JSON document in the same workspace; object field order is ignored." }, { "name": "x-niu-log-payloads", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" }, "description": "Capture the inspected Niu request and Niu creation response in bounded 24-hour Logs storage. False opts out; repeated or invalid values are rejected. Replay never creates a new capture." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "content" ], "properties": { "model": { "type": "string", "minLength": 1 }, "content": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "oneOf": [ { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string", "minLength": 1 }, "role": { "type": "string", "description": "Only roles explicitly supported by the selected schema are accepted." } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "image_url" ], "properties": { "type": { "const": "image_url" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^(https://|data:image/(png|jpeg|webp);base64,)" } }, "additionalProperties": false }, "role": { "type": "string", "description": "Only roles explicitly supported by the selected schema are accepted." } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "audio_url" ], "properties": { "type": { "const": "audio_url" }, "audio_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^https://", "description": "Public HTTPS input, accepted only when the selected upstream channel and exact model schema support this kind." } }, "additionalProperties": false }, "role": { "type": "string", "description": "Only roles explicitly supported by the selected schema are accepted." } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "video_url" ], "properties": { "type": { "const": "video_url" }, "video_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^https://", "description": "Public HTTPS input, accepted only when the selected upstream channel and exact model schema support this kind." } }, "additionalProperties": false }, "role": { "type": "string", "description": "Only roles explicitly supported by the selected schema are accepted." } }, "additionalProperties": false }, { "type": "object", "additionalProperties": false, "required": [ "type", "ingested_image" ], "properties": { "type": { "const": "ingested_image" }, "role": { "type": "string", "description": "Only roles declared by the selected image input rule." }, "ingested_image": { "type": "object", "additionalProperties": false, "required": [ "ingestion_id", "readiness_id", "consent_to_reuse" ], "properties": { "ingestion_id": { "type": "string", "format": "uuid" }, "readiness_id": { "type": "string", "format": "uuid" }, "consent_to_reuse": { "const": true } } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "workspace_asset" ], "properties": { "type": { "const": "workspace_asset" }, "role": { "type": "string", "minLength": 1 }, "workspace_asset": { "type": "object", "additionalProperties": false, "required": [ "asset_id", "consent_to_process" ], "properties": { "asset_id": { "type": "string", "format": "uuid" }, "consent_to_process": { "const": true } } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "provider_asset" ], "properties": { "type": { "type": "string", "const": "provider_asset" }, "provider_asset": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "role": { "type": "string" } } } ] }, "description": "Ordered model-supported text, image data, public HTTPS image/audio/video URLs or Niu ingested_image IDs. Ingested references require current original-account Active observation, retained inspected content and unexpired original grants/consent; dispatch rechecks all bindings atomically. Ordinary URL inputs require direct Ark and exact schema support; OpenRouter remains text-only. Mixed inline/ingested input and idempotency for ingested or independently inspected inline references are unsupported. Client asset:// URIs are never accepted. Workspace image-library references require explicit processing consent and current workspace ownership; fresh configured inspection is required only when the current policy requires it. Local bytes are resolved privately and deletion/content identity is rechecked atomically before dispatch. Stored audio/video and mixed ingested/library input remain unsupported; canonical idempotency supports ordinary upstream URL requests and durable workspace image references, preserving the original Niu reference identity." } }, "additionalProperties": true } } } }, "responses": { "202": { "description": "Durable Niu reference; acceptance alone does not establish upstream execution or billing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "model", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "video.job" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "unknown", "submission_unknown", "queued", "running", "succeeded", "failed", "reconciliation_required" ] } } } } }, "headers": { "x-niu-attempt-id": { "description": "Present on fresh creation; identifies the attempt for scoped Logs. Replay does not generate a new capture.", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid request/schema or idempotency header." }, "401": { "description": "Invalid, expired or revoked key." }, "402": { "description": "Customer capacity or spending limit denied before submission." }, "403": { "description": "Current workspace/model policy cannot be satisfied." }, "404": { "description": "Model or original job is unavailable to this scope." }, "409": { "description": "Changed idempotent input or conflicting route/key/policy/offer revision." }, "429": { "description": "Current key request/concurrency limit exceeded." }, "501": { "description": "Unsupported video channel, notification contract, mixed inline/ingested inputs or unsupported ingested/inspected-inline idempotency; no upstream dispatch." }, "503": { "description": "Qualified offer, original route or storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/video/jobs/{id}/results/{kind}": { "get": { "operationId": "retrieveVideoResult", "summary": "Retrieve a bounded saved video or last frame", "description": "Requires current workspace/model and compatible Guardrail access, checked again after retrieval. Uses encrypted references with a fixed 24-hour retention window. URLs may expire sooner. Never returns or redirects to a signed Provider URL. Supports MP4/WebM up to 64 MiB and PNG/JPEG up to 10 MiB; no Range support or automatic retry. Local transport tests do not qualify a live channel.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Attachment with private no-store caching and nosniff headers", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/webm": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Unknown result kind" }, "401": { "description": "Invalid, expired or revoked key" }, "403": { "description": "Required policy cannot be satisfied" }, "404": { "description": "Inaccessible, missing, locally expired or deleted reference" }, "502": { "description": "Safe media_result_* error category for unavailable links, rejected destinations, oversized or invalid media, or transport failure" }, "503": { "description": "Encryption, configuration or bounded retrieval capacity unavailable; capacity errors use media_result_busy" }, "504": { "description": "Overall result retrieval deadline exceeded; media_result_timeout" } }, "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/video/jobs/{id}/results": { "get": { "operationId": "getVideoResultsStatus", "summary": "Read saved result availability without downloading media", "description": "Requires current scoped model and compatible policy access. Returns no URLs or media content. Missing means no captured reference; unavailable includes expiry, deletion or conflicting terminal evidence. No regeneration, download or automatic query is performed.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current saved availability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoResultAvailability" } } } }, "401": { "description": "Invalid credential" }, "403": { "description": "Workspace or policy access denied" }, "404": { "description": "Missing or inaccessible job" } }, "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } }, "delete": { "operationId": "deleteVideoResults", "summary": "Permanently remove locally saved result references", "description": "Requires current workspace/model access. Removes encrypted URLs and leaves content-free markers preventing later refresh from restoring them, including unfinished jobs. Preserves status and financial records. Does not delete media held by a Provider or downloaded copies.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Result references deleted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deleted" ], "properties": { "deleted": { "const": true } } } } } }, "401": { "description": "Invalid, expired or revoked key" }, "404": { "description": "Inaccessible or missing job" } }, "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/video/jobs/{id}": { "get": { "operationId": "retrieveVideoJobState", "summary": "Read persisted video job state", "description": "Requires a current workspace API key with access to the original model. Reads saved evidence only; performs no upstream poll, generation or settlement. Succeeded does not guarantee available results, reported usage or a settled charge. No upstream identifiers, credentials or procurement values are returned.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Durable scoped state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "model", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "video.job" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "submission_unknown", "queued", "running", "succeeded", "failed", "unknown", "reconciliation_required" ] } } } } } }, "401": { "description": "Invalid, expired or revoked credential" }, "404": { "description": "Missing job, workspace mismatch or model access denied" } }, "x-niu-implementation": "implemented", "x-niu-status": "Reads persisted scoped evidence without upstream dispatch. Available results and customer charge settlement require separate evidence.", "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/chats/draft": { "get": { "operationId": "getChatDraft", "x-niu-implementation": "implemented", "summary": "Read the persistent personal Chat draft", "description": "The draft is isolated by authenticated personal owner and workspace. Operators have distinct drafts; installation credentials share the installation owner. Read authorization and workspace scope are required. An absent draft returns null payload and revision zero.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved personal draft state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ChatDraftResponse" } } } }, "401": { "description": "Missing or invalid administration/member authentication." }, "403": { "description": "Insufficient permission or workspace scope." }, "500": { "description": "Internal storage failure." }, "503": { "description": "Storage unavailable." } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/chats/draft", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "saveChatDraft", "x-niu-implementation": "implemented", "summary": "Save or clear the personal Chat draft with an expected revision", "description": "Write authorization and workspace scope are required. Browser-member requests require an allowed Origin when password authentication is configured; other requests also undergo Origin validation. Strict typed JSON rejects unknown fields. A referenced conversation must belong to the same owner and workspace. Saving does not call a model. The 24 MiB route body bound applies. Compare-and-swap prevents stale tabs from overwriting a newer draft; clearing retains and advances the revision.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved personal draft state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ChatDraftResponse" } } } }, "400": { "description": "Malformed or unknown JSON fields, invalid payload limits, or unavailable owner-scoped conversation." }, "401": { "description": "Missing or invalid administration/member authentication." }, "403": { "description": "Insufficient permission or workspace scope. Missing or disallowed browser Origin also refuses the write." }, "409": { "description": "Negative, stale or unavailable expected revision; no draft overwrite." }, "500": { "description": "Internal storage failure." }, "503": { "description": "Storage unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ChatDraftUpdate" } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/chats/draft", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/chats/{id}/export": { "get": { "operationId": "exportChatSession", "summary": "Export one owned saved conversation", "description": "Requires workspace read access and the authenticated conversation owner. Reads durable content directly, including sessions outside the latest-100 list. Excludes internal identifiers, settings, diagnostic errors and accounting. Conversation and attachment content is deliberately included and may contain user-supplied sensitive text. Legacy single-turn sessions become one turn. Does not export request Logs or billing evidence.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Portable conversation JSON", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "format", "version", "turns" ], "properties": { "format": { "const": "niu-chat" }, "version": { "const": 1 }, "title": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "turns": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "prompt", "results" ], "properties": { "prompt": { "type": "string" }, "results": { "type": "array", "maxItems": 4, "items": { "type": "object", "additionalProperties": false, "required": [ "model", "content", "phase" ], "properties": { "model": { "type": "string" }, "content": { "type": "string" }, "finishReason": { "type": [ "string", "null" ], "maxLength": 128, "description": "Model completion reason, when supplied. Transport completion alone does not establish a complete answer." }, "phase": { "type": "string", "enum": [ "connecting", "streaming", "complete", "failed", "cancelled" ] } } } }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "type", "content" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" } } } } } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace read access required" }, "404": { "description": "No saved conversation for this workspace and owner" }, "503": { "description": "Durable storage unavailable" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/chats/{id}/export", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/denials": { "get": { "operationId": "listGuardrailPreparationDenials", "summary": "Read latest 100 workspace preparation refusals", "description": "Workspace read access required. Safe immutable metadata for pre-dispatch model/Provider access, local input inspection, output configuration and external input detector refusals. No request content, matched patterns, detector responses, credentials or internal event/key identifiers. Does not cover dispatch-time races or post-dispatch output inspection. Latest 100 only, newest first; not a complete audit export. Policy names and revisions identify the saved decision. Cache-Control no-store. Inference credentials cannot read these diagnostics.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Latest 100 preparation refusals", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "coverage" ], "properties": { "coverage": { "const": "latest_100_preparation_denials" }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "stage", "outcome", "coverage", "enforcer_version", "reason", "key_name", "workspace_policy_name", "key_policy_name", "workspace_revision", "key_policy_revision", "key_assignment_revision", "recorded_at" ], "properties": { "stage": { "const": "preparation" }, "outcome": { "const": "blocked" }, "coverage": { "enum": [ "model_provider_access", "local_input", "output_configuration", "external_input" ] }, "enforcer_version": { "enum": [ "access-v1", "local-input-v1", "buffer-mode-v1", "external-input-v1" ] }, "reason": { "enum": [ "model_denied", "provider_denied", "unsupported_policy", "input_blocked", "input_unsupported", "input_resource_limit", "input_unavailable", "output_incompatible", "detector_blocked", "detector_unsupported", "detector_unavailable" ] }, "key_name": { "type": "string" }, "workspace_policy_name": { "type": [ "string", "null" ] }, "key_policy_name": { "type": [ "string", "null" ] }, "workspace_revision": { "type": [ "integer", "null" ] }, "key_policy_revision": { "type": [ "integer", "null" ] }, "key_assignment_revision": { "type": [ "integer", "null" ] }, "recorded_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Invalid management credential; inference keys cannot read decisions" }, "403": { "description": "Workspace outside authorized scope" }, "503": { "description": "Durable storage unavailable" } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/chats/{id}": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getChatSession", "x-niu-implementation": "implemented", "summary": "Read one complete owned saved Chat conversation", "description": "Requires workspace read permission and the authenticated personal owner. Returns the full saved conversation and archive state without scanning history pages, including sessions beyond the recent-100 list. Selection and authoritative customer-charge hydration share a bounded read-only snapshot (250 ms lock and 2 s statement limits); preceding authorization and pool acquisition are separate. Saved browser accounting is ignored. Saved JSON above 32 MiB returns 413; no content is truncated. Archived sessions remain directly readable. Accepts an internal UUID alias or permanent chat reference; both require the same workspace and personal-owner authorization. The returned data includes its server-assigned reference.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Internal UUID alias or permanent chat reference" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Complete owned conversation and separate archive state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "archived", "revision", "guardedWrites" ], "properties": { "data": { "type": "object" }, "archived": { "type": "boolean" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Opaque positive decimal write revision. Pass as expectedRevision for guarded saves." }, "guardedWrites": { "type": "boolean", "description": "True after guarded content save. Version-free saves are then rejected; this mode cannot be disabled by a content save." } } } } }, "headers": { "Cache-Control": { "description": "Complete personal conversation responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read permission required." }, "404": { "description": "No conversation for this personal owner and workspace." }, "413": { "description": "Saved JSON exceeds one-response capacity; use individual content export." }, "503": { "description": "Durable storage unavailable or read wait exceeded." } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/chats/{id}", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "operationId": "saveChatSession", "summary": "Save an owned Chat session in a workspace", "description": "Requires workspace write access. Stores conversation content separately from accounting. Only supported top-level and nested fields are retained. Client-supplied accounting fields are discarded. Numeric timestamps, durations and token counts must be nonnegative JavaScript-safe integers; token counts may be null. Settings and attachment shapes are validated. This endpoint does not establish authoritative request charges or detect secrets embedded in conversation text. Omit expectedRevision for a compatibility write only while the owned record has not enabled guarded writes. Explicit null creates only if no owned row exists; a canonical positive decimal revision updates only that exact owned version. Stale, missing or duplicate-create guarded writes return 409 without replacing content. Revisions are global sequence values, not timestamps, and are never reused by API delete/recreate. Guarded success includes a decimal revision; direct GET provides it. A successful guarded creation/update permanently enables guarded writes on that owned row. Compatibility saves thereafter return 409; there is no content-write downgrade. A content-free guard identity survives deletion, so legacy autosaves cannot resurrect a protected reference; explicit null guarded creation may recreate it. Untouched legacy rows retain compatibility behavior until guarded save.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt", "results", "createdAt" ], "properties": { "prompt": { "type": "string" }, "title": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "turns": { "type": "array", "maxItems": 100, "description": "Ordered conversation turns. Each retains its prompt and up to four model responses, validated with the same result fields as the current turn. Unknown turn/result fields are stripped. Optional for legacy single-turn sessions.", "items": { "type": "object", "required": [ "prompt", "results" ], "properties": { "prompt": { "type": "string" }, "results": { "type": "array", "maxItems": 4, "items": { "type": "object" } }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "name", "type", "content" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" } } } } } } }, "results": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "model", "content", "elapsedMs", "phase" ], "properties": { "model": { "type": "string" }, "content": { "type": "string" }, "elapsedMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "finishReason": { "type": [ "string", "null" ], "maxLength": 128, "description": "Model completion reason, when supplied. Transport completion alone does not establish a complete answer." }, "phase": { "type": "string", "enum": [ "connecting", "streaming", "complete", "failed", "cancelled" ] }, "promptTokens": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "completionTokens": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "totalTokens": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 } } } }, "settings": { "type": "object", "properties": { "systemPrompt": { "type": "string" }, "maxTokens": { "type": "integer", "minimum": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "logPayloads": { "type": "boolean" } } }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "name", "type", "content" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" } } } }, "expectedRevision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$", "description": "Omitted: compatibility write. Null: create-only. Positive decimal string: exact current revision from GET." } } } } } }, "responses": { "200": { "description": "Compatibility saved flag, or confirmed guarded saved flag, revision and guardedWrites=true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "saved" ], "properties": { "saved": { "const": true }, "reference": { "type": [ "string", "null" ], "description": "Permanent server-assigned Chat reference for product links." }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "guardedWrites": { "const": true, "description": "Present with revision only for confirmed guarded saves; older compatibility servers do not confirm this mode." } } } } } }, "400": { "description": "Invalid content or expected revision." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace write access required." }, "409": { "description": "Guarded creation/update does not match current owned state." }, "413": { "description": "Request exceeds the 24 MiB transport limit." }, "503": { "description": "Storage unavailable or bounded write wait exceeded." } }, "x-niu-implementation": "implemented", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/chats/{id}", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "delete": { "operationId": "deleteChatSession", "summary": "Delete an owned Chat session in a workspace", "description": "Requires write access to the workspace. Deletion is scoped to the authenticated owner and workspace. Missing or already deleted sessions return the same result without disclosing another owner's history. Does not delete request accounting or billing records.", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Session deleted or absent." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace write access required." } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/chats/{id}", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/chats": { "get": { "operationId": "listChatSessions", "x-niu-implementation": "implemented", "summary": "List personal saved Chat history or one continuation page", "description": "Without limit or after, retain the latest-100 compatibility response. Either paging parameter selects a bounded page, default 50, ordered by updated time and ID descending within the authenticated owner, workspace and archive state. Session payload and customer-charge hydration share a read-only snapshot with 250 ms lock and 2 s statement limits. A changed, deleted, foreign-owner or different-archive cursor returns 409; pages are live views, not a frozen cross-request snapshot. Before loading saved bodies, paging also limits the sum of saved JSON text bytes to 32 MiB and may return fewer rows than limit; follow next_cursor. Customer-charge hydration can increase wire size. Legacy latest-100 calls over that saved-payload budget return 413 rather than truncated success.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "archived", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "description": "Opaque next_cursor from the previous page; do not interpret or display it.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}:[0-9a-fA-F]{64}$" } } ], "responses": { "200": { "description": "Compatibility data array or paged data array with nullable next_cursor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Malformed cursor or invalid page size." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." }, "409": { "description": "Cursor no longer matches an accessible session in this archive." }, "413": { "description": "Saved Chat history exceeds one-response capacity; use paging or individual conversation export." }, "503": { "description": "Storage unavailable or read wait exceeded; no empty-success fallback." } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/chats", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/chats/{id}/archive": { "put": { "operationId": "setChatSessionArchived", "summary": "Archive or restore the authenticated owner's Chat session", "description": "Updates backend-owned archive state without changing content or conversation ordering. Autosaves preserve archive state. Repeating the same value is idempotent.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "archived" ], "properties": { "archived": { "type": "boolean" } } } } } }, "responses": { "204": { "description": "Archive state saved." }, "400": { "description": "Invalid input." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace write access required." }, "404": { "description": "No session in the caller's owner and workspace scope." } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/chats/{id}/archive", "tags": [ "Chat sessions" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/vendors/{id}/supplier": { "get": { "operationId": "getConfigurationProvider", "summary": "Read the Provider owning an API configuration", "description": "Installation credential or explicitly granted platform administrator required. Provider membership and customer ownership alone do not grant access. Returns the Provider identity and name, or null when no association exists, including an unknown configuration. Never returns credentials or procurement values.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Provider association or null.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } ] } } } } } }, "401": { "description": "Invalid or missing administrative credential." }, "403": { "description": "Installation administration required." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "put": { "operationId": "associateConfigurationProvider", "summary": "Associate an API configuration with a Provider", "description": "Installation credential or explicitly granted platform administrator required. Provider membership and customer ownership alone do not grant access. Atomic and audited. The first association requires the current configuration revision. Repeating the same Provider association is idempotent even with the original revision and does not increment it again. A different Provider cannot take over an existing association. Deleted Providers cannot receive configurations. Association and deletion serialize: once ownership commits, deletion returns 409. Does not activate, qualify or price an offer.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "supplier_id", "expected_revision" ], "properties": { "supplier_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "format": "int64", "description": "Current configuration revision for a first association; ignored on an identical existing association." } } } } } }, "responses": { "204": { "description": "Association established or already present; no response body." }, "401": { "description": "Invalid or missing administrative credential." }, "403": { "description": "Installation administration required." }, "409": { "description": "Unknown or deleted Provider, unknown configuration, stale first-association revision, conflicting offer ownership or attempted reassignment." }, "422": { "description": "Malformed request fields or unknown properties." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/projects/{project}/requests/{attempt}/guardrails": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attempt", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getRequestGuardrailDecision", "summary": "Read immutable policy attribution for an allowed dispatch", "description": "Requires workspace read access. Returns data null for attempts without recorded attribution, including historical attempts and denied transitions. Does not reconstruct denial records or claim content inspection. Policy names and revisions are historical; current policy changes do not rewrite them. Responses use Cache-Control no-store and exclude content, credentials, internal identifiers and commercial data.", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Scoped attribution or null.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "stage", "outcome", "coverage", "enforcer_version", "workspace_revision", "workspace_policy_name", "key_policy_revision", "key_policy_name", "key_assignment_revision", "recorded_at", "input_inspection", "output_inspection", "output_observation" ], "properties": { "stage": { "const": "dispatch" }, "outcome": { "const": "allowed" }, "coverage": { "const": "model_provider_access" }, "enforcer_version": { "const": "access-v1" }, "workspace_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "workspace_policy_name": { "type": [ "string", "null" ] }, "key_policy_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "key_policy_name": { "type": [ "string", "null" ] }, "key_assignment_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "recorded_at": { "type": "string", "format": "date-time" }, "output_inspection": { "description": "Null means no complete-output decision was recorded. Blocking does not cancel incurred customer charges or Provider usage. No original output is returned in decision metadata.", "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "outcome", "reason", "mode", "coverage", "enforcer_version", "elapsed_ms" ], "properties": { "outcome": { "enum": [ "allowed", "redacted", "blocked", "indeterminate" ] }, "reason": { "enum": [ "inspected_text", "pattern_denial", "unsupported_content", "resource_limit", "inspection_unavailable" ] }, "mode": { "const": "buffered_full" }, "coverage": { "const": "local_text" }, "enforcer_version": { "const": "local-output-v1" }, "elapsed_ms": { "type": "integer", "minimum": 0 } } } ] }, "output_observation": { "description": "Non-enforcing inspection of the original complete response. A match does not mean output was withheld. Null means no observation was recorded; no original or matched content is returned.", "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "outcome", "reason", "mode", "enforcement", "coverage", "enforcer_version", "elapsed_ms" ], "properties": { "outcome": { "enum": [ "clear", "matched", "indeterminate" ] }, "reason": { "enum": [ "inspected_text", "pattern_match", "unsupported_content", "resource_limit", "inspection_unavailable" ] }, "mode": { "const": "observe_only" }, "enforcement": { "const": false }, "coverage": { "const": "local_text" }, "enforcer_version": { "const": "local-output-v1" }, "elapsed_ms": { "type": "integer", "minimum": 0 } } } ] }, "input_inspection": { "description": "Null means no recorded local inspection result; never infer historical content protection. Duration includes local compilation and worker execution, not upstream generation.", "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "outcome", "coverage", "enforcer_version", "elapsed_ms" ], "properties": { "outcome": { "enum": [ "allowed", "redacted" ] }, "coverage": { "const": "local_text" }, "enforcer_version": { "const": "local-input-v1" }, "elapsed_ms": { "type": "integer", "minimum": 0 } } } ] } } } ] } } } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." } }, "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/output-preview": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "previewGuardrailOutput", "summary": "Test synthetic output against local text rules without enforcement", "description": "Requires workspace read permission. Does not save content or policy, create requests, or call inference/detector services. Returns safe outcome codes only, with no original, transformed or matched text. Does not validate route availability or activate content controls. Responses use Cache-Control no-store. The complete synthetic request envelope is limited to 1 MiB. Uses the live buffered-full local output inspector, with a 1 MiB serialized-response and transformed-response limit; unsupported/opaque/tool content is indeterminate. This does not qualify streaming inspection or external detectors. Local tests use at most four blocking workers per gateway process with no waiting queue and a five-second response deadline; cancellation does not release a slot until computation finishes.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "protocol", "rules", "response" ], "properties": { "mode": { "type": "string", "enum": [ "buffered_full", "observe_only" ], "default": "buffered_full" }, "protocol": { "type": "string", "enum": [ "chat", "responses" ] }, "response": { "description": "Synthetic complete protocol response to inspect." }, "rules": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "action" ], "oneOf": [ { "required": [ "pattern" ], "not": { "required": [ "preset" ] } }, { "required": [ "preset" ], "not": { "required": [ "pattern" ] } } ], "properties": { "pattern": { "type": "string", "minLength": 1, "description": "Regex limited to 4096 UTF-8 bytes and bounded compiled size." }, "preset": { "type": "string", "enum": [ "email_v1", "api_key_prefix_v1" ], "description": "Versioned syntax patterns; not universal PII or secret detection." }, "action": { "type": "string", "enum": [ "block", "redact" ] } } } } } } } } }, "responses": { "200": { "description": "Synthetic inspection outcome; unsupported content and resource limits are indeterminate.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "outcome", "reason", "redacted", "synthetic", "enforcement", "mode", "coverage" ], "properties": { "outcome": { "type": "string", "enum": [ "allowed", "blocked", "clear", "matched", "indeterminate" ] }, "reason": { "type": "string", "enum": [ "inspected_text", "pattern_denial", "pattern_match", "unsupported_content", "resource_limit", "invalid_pattern" ] }, "redacted": { "type": "boolean" }, "synthetic": { "const": true }, "enforcement": { "const": false }, "mode": { "enum": [ "buffered_full", "observe_only" ] }, "coverage": { "const": "local_text" } } } } } }, "400": { "description": "Invalid JSON shape, enum value or oversized/invalid rule set. Errors do not echo submitted content." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." }, "503": { "description": "Inspection capacity unavailable, worker failure or response deadline exceeded. No inference is dispatched." } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/input-preview": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "previewGuardrailInput", "summary": "Test synthetic input against local text rules without enforcement", "description": "Requires workspace read permission. Does not save content or policy, create requests, or call inference/detector services. Returns safe outcome codes only, with no original, transformed or matched text. Does not validate route availability or activate content controls. Responses use Cache-Control no-store. Local tests use at most four blocking workers per gateway process with no waiting queue and a five-second response deadline; cancellation does not release a slot until computation finishes.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "protocol", "rules", "request" ], "properties": { "protocol": { "type": "string", "enum": [ "chat", "responses", "embeddings" ] }, "request": { "description": "Synthetic protocol request to inspect." }, "rules": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "action" ], "oneOf": [ { "required": [ "pattern" ], "not": { "required": [ "preset" ] } }, { "required": [ "preset" ], "not": { "required": [ "pattern" ] } } ], "properties": { "pattern": { "type": "string", "minLength": 1, "description": "Regex limited to 4096 UTF-8 bytes and bounded compiled size." }, "preset": { "type": "string", "enum": [ "email_v1", "api_key_prefix_v1" ], "description": "Versioned syntax patterns; not universal PII or secret detection." }, "action": { "type": "string", "enum": [ "block", "redact" ] } } } } } } } } }, "responses": { "200": { "description": "Synthetic inspection outcome; unsupported content and resource limits are indeterminate.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "outcome", "reason", "redacted", "synthetic", "enforcement" ], "properties": { "outcome": { "type": "string", "enum": [ "allowed", "blocked", "indeterminate" ] }, "reason": { "type": "string", "enum": [ "inspected_text", "pattern_denial", "unsupported_content", "resource_limit", "invalid_pattern" ] }, "redacted": { "type": "boolean" }, "synthetic": { "const": true }, "enforcement": { "const": false } } } } } }, "400": { "description": "Invalid JSON shape, enum value or oversized/invalid rule set. Errors do not echo submitted content." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." }, "503": { "description": "Inspection capacity unavailable, worker failure or response deadline exceeded. No inference is dispatched." } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/guardrail/history": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read immutable key policy assignment history", "description": "Returns at most 100 newest events with assignment/policy revisions, nullable policy name, readable actor name and creation time. Removal events have a null policy revision and name. Internal actor identifiers and credentials are excluded. History before audit support was installed is not reconstructed. Cache-Control is no-store.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "before_assignment_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Exclusive cursor from next_cursor." } ], "responses": { "200": { "description": "Data array and nullable next_cursor; an empty history returns an empty array." }, "400": { "description": "Invalid cursor." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/guardrail": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a workspace-scoped key policy assignment", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Data contains assignment_revision, policy_revision and policy, or null when no assignment exists in this workspace." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "summary": "Assign a preserved workspace policy revision to an active key", "description": "Key restrictions intersect mandatory workspace restrictions and cannot weaken them. Revision zero creates an assignment; subsequent updates require its current assignment revision. An explicit null policy_revision clears only the key assignment while retaining an incremented assignment revision and immutable history. Omission is rejected. Rotation preserves assigned policies; mandatory workspace restrictions remain enforced.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "policy_revision", "expected_assignment_revision" ], "properties": { "policy_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "expected_assignment_revision": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "New assignment_revision." }, "400": { "description": "Invalid revision or unsupported policy." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace write access required." }, "404": { "description": "Policy revision absent in this workspace." }, "409": { "description": "Stale assignment revision or inactive, expired or foreign key." }, "422": { "description": "Missing required assignment fields or malformed JSON shape." } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/revisions/{revision}": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "get": { "operationId": "getWorkspaceGuardrailRevision", "summary": "Inspect a preserved workspace policy version before restoring", "description": "Workspace read access required. Returns the original saved policy with input/output rules, without credentials or internal actor identifiers. Cache-Control is no-store. Does not activate or dispatch anything.", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Saved version and policy.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision", "policy" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "policy": { "$ref": "#/components/schemas/guardrails_openapi_yaml_Policy" } } } } } } } }, "400": { "description": "Invalid revision." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." }, "404": { "description": "No such version in this workspace." } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/history": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listWorkspaceGuardrailHistory", "summary": "Browse immutable workspace policy revision metadata", "description": "Workspace read access required. Newest first, at most 100 records per page. Excludes policy content, internal actor identifiers and credentials. Active reflects the workspace head at the time of each page read. Cache-Control is no-store.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "before_revision", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Exclusive cursor returned as next_cursor." } ], "responses": { "200": { "description": "Revision metadata, including rollback attribution. An empty workspace returns an empty array.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": [ "integer", "null" ], "minimum": 1 }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "revision", "policy_name", "active", "actor_name", "activated_at", "restored_from_revision" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "policy_name": { "type": "string" }, "active": { "type": "boolean" }, "actor_name": { "type": "string" }, "activated_at": { "type": "string", "format": "date-time" }, "restored_from_revision": { "type": [ "integer", "null" ], "minimum": 1 } } } } } } } } }, "400": { "description": "Invalid history cursor. Errors do not echo submitted values." }, "401": { "description": "Authentication required, including malformed query requests." }, "403": { "description": "Workspace read access required." } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/rollback": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "summary": "Restore a preserved policy as a new active revision", "description": "Requires workspace write access. Revalidates the selected policy under the current supported schema. Prior revisions remain unchanged; stale expected revisions conflict.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "target_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "target_revision": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "New revision and restored_from_revision." }, "400": { "description": "Invalid target or unsupported stored policy." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace write access required." }, "404": { "description": "Target revision absent in this workspace." }, "409": { "description": "Active revision changed." } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read active workspace access policy", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Active revision and policy in data, or null when no policy is configured." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "put": { "summary": "Activate a validated workspace access-policy revision", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "policy" ], "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "policy": { "$ref": "#/components/schemas/guardrails_openapi_yaml_Policy" } } } } } }, "responses": { "200": { "description": "Newly activated revision." }, "400": { "description": "Invalid policy." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace write access required." }, "409": { "description": "Revision conflict; active policy remains unchanged." } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/guardrails/preview": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "summary": "Preview draft model and Provider access without persistence", "description": "Returns allowed, coverage=model_provider_access and route_availability_checked=false. Does not check route availability, content, retention, budgets or credential grants.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "policy", "model", "provider" ], "properties": { "policy": { "$ref": "#/components/schemas/guardrails_openapi_yaml_Policy" }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "provider": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Access-only preview verdict." }, "400": { "description": "Invalid policy or candidate." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace read access required." } }, "tags": [ "Guardrails" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/requests/{attempt}/payloads": { "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attempt", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getRequestPayload", "summary": "Read retained request content in an authorized workspace", "description": "Content is separate from accounting, expires 24 hours after the original request creation time and is retained by default unless the inference request opts out. Missing or expired content returns null. Headers and known confidential Provider cost fields are excluded, including historical response usage metadata sanitized on read. Truncated SSE captures expose only complete sanitized events. Truncated JSON that cannot be safely parsed is withheld as an empty response string with response_omitted true, while authorized request content stays readable. Other malformed or incomplete structured responses fail closed with 503. Known credential fields in historical request objects are removed on read. Arbitrary secrets embedded in prompts are not automatically redacted.", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Workspace read permission required. Response uses Cache-Control no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/request_observability_openapi_yaml_RequestPayload" } ] } } } } } }, "401": { "description": "Authentication required." }, "403": { "description": "The authenticated role lacks the required permission." }, "404": { "description": "Workspace is outside the authenticated scope." }, "503": { "description": "Retained structured response cannot be safely serialized, or content storage is unavailable. No unsanitized payload is returned." } }, "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "delete": { "operationId": "deleteRequestPayload", "summary": "Delete retained content without deleting accounting records", "description": "Requires workspace write permission. A durable content-free deletion marker prevents concurrent or late capture from recreating deleted payloads, including deletion before capture. Accounting records remain unchanged. Cross-workspace or absent attempts do not create markers.", "security": [ { "adminBearerAuth": [] } ], "responses": { "204": { "description": "Scoped deletion completed; workspace write permission required." }, "401": { "description": "Authentication required." }, "403": { "description": "The authenticated role lacks the required permission." }, "404": { "description": "Workspace is outside the authenticated scope." } }, "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/warning-threshold": { "put": { "operationId": "setCustomerBalanceWarning", "summary": "Set company low-balance warning threshold", "description": "Organization-wide owner/admin with write access or installation administrator only. Updates an existing account warning preference with revision checking; never changes funds or approved credit. Null or omitted threshold disables the warning. This does not configure external notifications.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "warning_threshold_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Exact nonnegative nanounits up to 9223372036854775807; null disables the warning." }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact current policy revision from zero through 9223372036854775806." } } } } } }, "responses": { "200": { "description": "Updated preference revision", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revision": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "revision" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid amount or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Write permission required" }, "404": { "description": "Company billing access not granted" }, "409": { "description": "Missing account or stale revision" }, "422": { "description": "Invalid body schema or unexpected field" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/topups": { "get": { "operationId": "listCustomerTopups", "summary": "Recover company checkout history", "description": "Organization-wide owner/admin with read access or installation administrator only. Backend-owned history survives browser changes. At most 100 saved intents per page, ordered by descending creation time and internal routing reference. No upstream calls, merchant credentials or procurement data. Paid/closed entries withhold checkout URLs. Traversal is a live view, not a fixed snapshot; refresh to see newly created orders. Internal IDs are routing/cursor references, never product labels. Storage reads use transaction-local 250 ms lock and 2 s statement limits; pool admission and the complete HTTP deadline are separate. Timeout returns sanitized 503, never empty or partial success. Cursor and history rows share one read-only snapshot.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "next_cursor from the previous company page. Foreign or missing cursors return conflict." } ], "responses": { "200": { "description": "Saved checkout history page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "currency", "amount_nanos", "payment_method", "status", "checkout_url", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal routing/cursor reference; never display as a product label." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "payment_method": { "type": "string" }, "status": { "type": "string", "enum": [ "reconciliation_required", "pending", "paid", "closed" ] }, "checkout_url": { "type": [ "string", "null" ], "format": "uri" }, "created_at": { "type": "string", "format": "date-time" }, "credits": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "credit_atoms", "definition_revision", "rule_revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "rule_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } } } } } } } } } }, "400": { "description": "Invalid company or cursor syntax" }, "401": { "description": "Authentication required" }, "404": { "description": "Company billing access not granted" }, "409": { "description": "Foreign or missing cursor" }, "503": { "description": "Durable storage unavailable" } }, "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } }, "post": { "operationId": "createCustomerTopup", "summary": "Create or recover a company prepaid top-up", "description": "Organization-wide owner/admin with write access or installation administrator only. Requires an enabled method and an existing account in the selected integration's currency. Classic EPay and native Zhifux use CNY; Stripe uses its configured supported currency. Exact positive amounts must match the integration's minor-unit precision. No implicit account creation, FX or approved credit. Reuse the same idempotency key and identical intent after an uncertain response. Remote creation is durably claimed before contact and never automatically repeated; EPay atomically saves its intent and deterministic signed checkout locally. A checkout write failure rolls back a new intent; replay can complete an older saved intent without a link. Checkout alone grants no balance. Independently verified payment gates funding. Merchant credentials and enabled methods are deployment configuration. An explicit payment_gateway never falls through to another integration. Omission preserves runtime priority for compatibility. Credits-mode settlement issues the original quoted unit quantity in a separate lot; it does not credit the monetary wallet. The purchase rule is pinned before checkout and later publication cannot change it. Simulated payment provenance is retained with zero verified cash backing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "amount_nanos", "payment_method", "idempotency_key" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Optional account currency. Selects a matching enabled integration; omission preserves existing default priority. Never implies conversion." }, "payment_gateway": { "type": "string", "enum": [ "epay", "stripe", "zhifux" ], "description": "Optional explicit integration. Never falls through to a different gateway; omission preserves default priority." }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact positive account-currency nanounits, at most 9223372036854775807. CNY requires divisibility by 10000000; other currencies require their supported minor-unit precision. Never a JSON number." }, "payment_method": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9.-]+$", "description": "Must be enabled for the configured merchant." }, "idempotency_key": { "type": "string", "format": "uuid" }, "quote_id": { "type": "string", "format": "uuid", "description": "Required for a new Credits-mode checkout and forbidden for a new currency-mode checkout. Must be an unexpired unused quote for the same company, amount and currency. Preserve it on retries." } } } } } }, "responses": { "200": { "description": "Saved top-up status; checkout and pending status confer no spending capacity", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "currency", "amount_nanos", "payment_method", "status", "checkout_url" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal API routing reference; never display as a product label." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Immutable saved account currency; no implicit conversion." }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "payment_method": { "type": "string" }, "status": { "type": "string", "enum": [ "reconciliation_required", "pending", "paid", "closed" ] }, "checkout_url": { "type": [ "string", "null" ], "format": "uri", "description": "Validated HTTPS checkout for pending orders only; null for paid and closed orders." }, "credits": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "credit_atoms", "definition_revision", "rule_revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "rule_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } } } } } } } } }, "400": { "description": "Invalid amount or unavailable payment method" }, "401": { "description": "Authentication required" }, "403": { "description": "Write permission required" }, "404": { "description": "Company billing access not granted" }, "409": { "description": "Missing currency account or conflicting saved intent" }, "422": { "description": "Invalid body schema or unexpected field" }, "502": { "description": "Integration unavailable or checkout creation uncertain; preserve the intent and idempotency key" }, "503": { "description": "Durable storage unavailable; no successful creation is implied" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/payment-methods": { "get": { "operationId": "getCustomerPaymentMethods", "summary": "Read company checkout availability", "description": "Organization-wide owner/admin with read access or installation administrator only. Returns enabled merchant method codes for the requested currency when configured and an account exists. Omitted currency preserves the configured default. No merchant credentials, account identifiers or upstream queries. Availability does not guarantee collection or grant write permission. No FX or account provisioning is implied.", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "payment_gateway", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "epay", "stripe", "zhifux" ] }, "description": "Select one configured integration without falling through to another." } ], "responses": { "200": { "description": "Configured checkout methods or explicit unavailable state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "currency", "payment_gateway", "available", "payment_methods", "unavailable_reason" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "available": { "type": "boolean" }, "payment_methods": { "type": "array", "items": { "type": "string" }, "description": "Empty when unavailable; exact configured codes otherwise." }, "payment_gateway": { "type": [ "string", "null" ], "enum": [ "epay", "stripe", "zhifux", null ], "description": "Selected configured integration for these methods. Forward this value with currency when creating a top-up; null means no matching integration. This is adapter identity, not merchant credentials or a payment-method display label." }, "unavailable_reason": { "type": [ "string", "null" ], "enum": [ "integration_unavailable", "currency_account_missing", null ] } } } } } } } }, "400": { "description": "Invalid company identifier or currency query" }, "401": { "description": "Authentication required" }, "404": { "description": "Company billing access not granted" }, "503": { "description": "Durable account storage unavailable" } }, "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/topups/{order}": { "get": { "operationId": "getCustomerTopup", "summary": "Read saved company top-up status", "description": "Organization-wide owner/admin with read access or installation administrator only. Reads durable records without querying the payment service. Paid and closed orders withhold checkout URLs. Internal routing references must not become product labels. No merchant, platform receipt, ledger identity, Provider cost or margin is returned. Storage reads use transaction-local 250 ms lock and 2 s statement limits; pool admission and the complete HTTP deadline are separate. Timeout returns sanitized 503, never empty or partial success.", "responses": { "200": { "description": "Saved top-up status; checkout and pending status confer no spending capacity", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "currency", "amount_nanos", "payment_method", "status", "checkout_url" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal API routing reference; never display as a product label." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Immutable saved account currency; no implicit conversion." }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "payment_method": { "type": "string" }, "status": { "type": "string", "enum": [ "reconciliation_required", "pending", "paid", "closed" ] }, "checkout_url": { "type": [ "string", "null" ], "format": "uri", "description": "Validated HTTPS checkout for pending orders only; null for paid and closed orders." }, "credits": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "credit_atoms", "definition_revision", "rule_revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "rule_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } } } } } } } } }, "400": { "description": "Invalid route identifier" }, "401": { "description": "Authentication required" }, "404": { "description": "Order missing or company billing access not granted" }, "503": { "description": "Durable storage unavailable" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/topups/{order}/reconcile": { "post": { "operationId": "reconcileCustomerTopup", "summary": "Independently reconcile a saved payment", "description": "Installation administrator or organization-wide billing owner/admin. Queries the original configured merchant under bounded query admission. Exact verified paid evidence funds atomically once; verified closed evidence records closure without funding. Never creates a checkout or automatically retries. Already paid or closed orders return their durable status without requiring merchant configuration or an upstream query. A successful response reports durable status, not necessarily paid. EPay query recovery is unsupported (501); signed notifications remain available. Merchant activation and received-cash funding require separate deployment evidence.", "responses": { "200": { "description": "Saved top-up status; checkout and pending status confer no spending capacity", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "currency", "amount_nanos", "payment_method", "status", "checkout_url" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Internal API routing reference; never display as a product label." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Immutable saved account currency; no implicit conversion." }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "payment_method": { "type": "string" }, "status": { "type": "string", "enum": [ "reconciliation_required", "pending", "paid", "closed" ] }, "checkout_url": { "type": [ "string", "null" ], "format": "uri", "description": "Validated HTTPS checkout for pending orders only; null for paid and closed orders." }, "credits": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "credit_atoms", "definition_revision", "rule_revision", "name", "display_precision", "atoms_per_unit" ], "properties": { "credit_atoms": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "rule_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" } } } } } } } } } }, "400": { "description": "Invalid route identifier" }, "401": { "description": "Authentication required" }, "403": { "description": "Organization-wide billing write access required" }, "404": { "description": "Saved order missing" }, "409": { "description": "Conflicting immutable identity or terminal evidence" }, "501": { "description": "Saved adapter does not support query recovery" }, "502": { "description": "Integration unavailable, unresolved payment evidence or query admission busy/rate limited" }, "503": { "description": "Durable storage unavailable" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/payments/epay/notify": { "post": { "operationId": "receiveEPayFormNotification", "summary": "Receive a signed classic EPay form notification", "security": [], "description": "Same verified funding contract as GET. Form bodies are limited to 8192 bytes. Rejects duplicate and unknown fields before verification. Post-body processing has a two-second deadline. Acknowledgment follows durable funding; replay never creates a second credit.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": false, "required": [ "pid", "out_trade_no", "trade_no", "type", "money", "trade_status", "sign", "sign_type" ], "properties": { "pid": { "type": "string", "pattern": "^[0-9]{1,32}$" }, "out_trade_no": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "trade_no": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "type": { "type": "string" }, "money": { "type": "string", "description": "Exact decimal CNY matching the saved intent." }, "trade_status": { "type": "string", "const": "TRADE_SUCCESS" }, "sign": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "sign_type": { "type": "string", "const": "MD5" }, "name": { "type": "string", "maxLength": 1024 } } } } } }, "responses": { "200": { "description": "Verified payment committed or replayed; exactly one saved-order credit", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "text/plain": { "schema": { "type": "string", "const": "success" } } } }, "400": { "description": "Invalid form content type, notification or signed saved-order evidence" }, "409": { "description": "Payment identity conflicts with an existing binding or another order" }, "413": { "description": "Form exceeds 8192 bytes" }, "502": { "description": "Integration unavailable or processing deadline exceeded; retry delivery" }, "503": { "description": "Durable storage unavailable; retry notification" } }, "x-niu-implementation": "implemented", "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } }, "get": { "operationId": "receiveEPayQueryNotification", "summary": "Receive a signed classic EPay query notification", "security": [], "description": "Bounded to 8192 query bytes. Duplicate or unknown fields are rejected. Verifies the configured merchant and exact saved CNY order, method and amount before binding payment identity and funding exactly once. A browser return is never payment evidence. Post-input processing has a two-second deadline; timeout requires delivery retry. Merchant compatibility and live collection remain unqualified.", "parameters": [ { "name": "pid", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,32}$" } }, { "name": "out_trade_no", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } }, { "name": "trade_no", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "money", "in": "query", "required": true, "schema": { "type": "string", "description": "Exact decimal CNY matching the saved intent." } }, { "name": "trade_status", "in": "query", "required": true, "schema": { "type": "string", "const": "TRADE_SUCCESS" } }, { "name": "sign", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } }, { "name": "sign_type", "in": "query", "required": true, "schema": { "type": "string", "const": "MD5" } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } } ], "responses": { "200": { "description": "Verified payment committed or replayed; exactly one saved-order credit", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "text/plain": { "schema": { "type": "string", "const": "success" } } } }, "400": { "description": "Invalid notification, signature or saved-order evidence" }, "409": { "description": "Payment identity conflicts with an existing binding or another order" }, "502": { "description": "Integration unavailable or processing deadline exceeded; retry delivery" }, "503": { "description": "Durable storage unavailable; retry notification" } }, "x-niu-implementation": "implemented", "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/payments/zhifux/notify": { "post": { "operationId": "receiveZhifuxNotification", "summary": "Receive signed merchant notification", "security": [], "description": "Public signed post_form callback for the configured merchant, limited to 8192 body bytes. Verifies exact saved intent and commits an immutable receipt before acknowledgement. Unsigned extra fields are ignored and never authorize funding or closure. Independent authenticated query gates funding. Post-body receipt processing has a two-second deadline; errors and timeout must be retried by the sender. Browser return URLs are not accepted as evidence.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "merchantNum", "orderNo", "amount", "state", "sign" ], "properties": { "merchantNum": { "type": "string" }, "orderNo": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "amount": { "type": "string", "description": "Exact requested decimal CNY amount from the saved intent." }, "state": { "type": "string", "enum": [ "1" ] }, "sign": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } } } }, "responses": { "200": { "description": "Durable verified receipt accepted; does not mean paid or funded", "content": { "text/plain": { "schema": { "type": "string", "const": "success" } } } }, "400": { "description": "Invalid signed evidence or malformed form" }, "404": { "description": "Saved merchant order missing" }, "413": { "description": "Body exceeds 8192 bytes" }, "415": { "description": "Form content type required" }, "422": { "description": "Required form field missing" }, "502": { "description": "Integration unavailable or receipt processing timed out; retry notification" }, "503": { "description": "Durable receipt storage unavailable; retry notification" } }, "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/policy": { "put": { "operationId": "configureCustomerBalancePolicy", "summary": "Configure approved credit and low-balance threshold", "description": "Explicit platform administration required; ordinary company owners/admins cannot approve their own credit. Creates a zero-balance account if absent, with expected revision zero. Updates are revision checked and recorded in immutable history with an authenticated credit-approval actor in the same transaction. Historical revisions remain unattributed. Credit changes do not credit funds. Reductions that would invalidate held reservations are rejected. With no holds, reduced credit can exhaust capacity while preserving the actual debt. A null warning threshold disables low-balance warnings. This configures warning state, not notification-channel delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "credit_limit_nanos", "expected_revision" ], "properties": { "credit_limit_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "warning_threshold_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$" } } } } } }, "responses": { "200": { "description": "Policy saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revision": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "revision" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid currency, amount or revision" }, "401": { "description": "Authentication required" }, "403": { "description": "Installation write access required" }, "409": { "description": "Stale revision, unknown company or outstanding reservations prevent credit reduction" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/billing/transactions": { "get": { "operationId": "getCustomerBalanceTransactions", "summary": "Read a company balance transaction page", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "next_cursor returned by the previous page. Must belong to this company." }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "funding", "charge", "refund", "funding_reversal", "adjustment" ] } } ], "description": "Organization-wide owner/admin or installation access required. Customer ledger only; no Provider costs or margins. Ordered by descending recorded time and internal reference. UUIDs are API routing references and must not be displayed as product labels. Each page contains up to 100 entries; next_cursor is null at the end. Pass the cursor as before to read older entries. Unknown or foreign cursors return a conflict. Traversal is a live view, not a fixed export snapshot; newly inserted later entries appear on refresh. Optional currency and kind filters apply before pagination. Keep filters fixed while following cursors; out-of-filter cursors return 409. Each page and cursor check share one database snapshot.", "responses": { "200": { "description": "Customer balance entries", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "funding", "charge", "refund", "funding_reversal", "adjustment" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": "string", "pattern": "^-?[0-9]+$" }, "created_at": { "type": "string", "format": "date-time" }, "reverses_entry_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } } } } }, "400": { "description": "Invalid currency, entry kind or query" }, "401": { "description": "Authentication required" }, "404": { "description": "Company account access not granted" }, "409": { "description": "Cursor does not belong to this company ledger" } }, "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/entries/{entry}/reversal": { "post": { "operationId": "reverseCustomerBalanceEntry", "summary": "Record a balance refund or settled-funding reversal", "description": "Installation write access only. Funding entries can be reversed; charge entries can be refunded to account balance. Original records remain immutable. Cumulative reversals cannot exceed the original amount. Identical idempotency-key replay applies once; conflicting reuse is rejected. A verified funding reversal may create debt and reduce available funds without releasing in-flight liabilities. This records a ledger adjustment and does not execute external refunds or payments.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "amount_nanos", "idempotency_key" ], "properties": { "amount_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive signed-64-bit nanounit amount" }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Recorded or identical replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "recorded": { "type": "boolean", "const": true } }, "required": [ "recorded" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid amount" }, "401": { "description": "Authentication required" }, "403": { "description": "Installation write access required" }, "409": { "description": "Unknown or unsupported original entry, over-refund or conflicting replay" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "entry", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/balance": { "get": { "operationId": "getCustomerBalance", "summary": "Read shared company account balances", "description": "Requires organization-wide owner/admin access or installation administration. Workspace-only sessions and organization viewers cannot read shared funds. Exact nanounit amounts are decimal strings. Available funds equal posted balance plus approved credit minus outstanding liabilities (including known media charges above their original holds); each request must still atomically reserve its full liability. No account identifiers, Provider prices or payment references are exposed. Storage reads retain one amount snapshot with transaction-local 250 ms lock and 2 s statement limits. Timeout returns sanitized 503, never zero balances or partial success; pool admission and a complete HTTP deadline remain separate.", "responses": { "200": { "description": "Customer balance summaries by currency", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "currency", "balance_nanos", "reserved_nanos", "outstanding_nanos", "available_nanos", "credit_limit_nanos", "warning_threshold_nanos", "policy_revision", "low_balance", "posted_credit_exhausted" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "balance_nanos": { "type": "string", "pattern": "^-?[0-9]+$" }, "reserved_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "outstanding_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Open customer liabilities, including known media charges above their original holds, excluding already posted debits." }, "available_nanos": { "type": "string", "pattern": "^-?[0-9]+$", "description": "Posted balance plus approved credit minus outstanding_nanos; may be negative." }, "credit_limit_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "policy_revision": { "type": "string", "pattern": "^[0-9]+$" }, "warning_threshold_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "low_balance": { "type": "boolean" }, "posted_credit_exhausted": { "type": "boolean" } } } } } } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Company account access not granted" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/organizations/{organization}/billing/funding/settled": { "parameters": [ { "$ref": "#/components/parameters/billing_openapi_yaml_Organization" } ], "post": { "operationId": "recordSettledCustomerFunding", "summary": "Record an externally verified settled customer payment", "description": "Installation write access only. Trusted administration must verify external payment settlement before calling. This is not a customer self-credit endpoint or a payment-channel callback integration. The channel/payment reference credits funds once; changed organization, currency or amount is a conflict. Pending payments must not be submitted. No commercial payment channel is implied by this administrative record API.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "currency", "amount_nanos", "channel", "payment_reference" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive signed-64-bit nanounit amount" }, "channel": { "type": "string", "minLength": 1, "maxLength": 100 }, "payment_reference": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Recorded or identical receipt replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "recorded": { "type": "boolean", "const": true } } } } } } } }, "400": { "description": "Invalid funding details" }, "401": { "description": "Authentication required" }, "403": { "description": "Installation write access required" }, "409": { "description": "Unknown organization or conflicting payment reference" } }, "security": [ { "adminBearerAuth": [] } ], "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/projects/{project}/billing": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getCustomerBilling", "summary": "Read workspace customer charges, tariffs and latest 100 invoices", "description": "Requires workspace read access. Balances cover the full ledger per currency. Tariffs are current effective customer selling prices using the same workspace/standard enrollment and customer/global promotion selection as model discovery, within the billing read snapshot. Enabled personally funded routes are excluded. Rates are informational and do not establish route availability or spending authorization. All monetary amounts and aggregate counts are decimal integer strings. Upstream costs are separate. Cache-Control is no-store.", "responses": { "200": { "description": "Billing overview", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "balances", "unresolved", "unpriced", "tariffs", "invoices" ], "properties": { "balances": { "type": "array", "items": { "type": "object", "required": [ "currency", "charged_nanos", "unbilled_nanos", "due_nanos", "paid_nanos" ], "properties": { "currency": { "type": "string" }, "charged_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "unbilled_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "due_nanos": { "allOf": [ { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Invoiced charges without an invoice receipt or matching balance debit." }, "paid_nanos": { "allOf": [ { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Charges settled by a balance debit or invoice receipt, counted once, including balance debits before invoicing." } } } }, "unresolved": { "allOf": [ { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Dispatched non-personal requests with a text or media price binding but no corresponding charge; excludes confirmed nonexecution." }, "unpriced": { "allOf": [ { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Dispatched non-personal requests without either a text or media price binding; excludes confirmed nonexecution." }, "tariffs": { "type": "array", "items": { "type": "object", "required": [ "model_alias", "revision", "currency", "prompt_rate", "completion_rate" ], "properties": { "model_alias": { "type": "string" }, "revision": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "minimum_charge_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Minimum customer charge in currency nanounits (0 to 9223372036854775807), not a token rate. Defaults to zero for new tariffs. Replacing a nonzero minimum requires an explicit value; zero disables it. Known completed usage is charged the greater of the rounded token amount plus request_fee_nanos and this minimum. Unknown usage remains unresolved." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "request_fee_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Customer-only fixed fee in currency nanounits (0 to 9223372036854775807). Charge = max(rounded token charge + request fee, minimum charge) for known completed usage. Unknown execution/usage and confirmed rejection do not create a fee. Defaults to zero on new tariffs; replacement of a nonzero fee requires an explicit value; zero disables it." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." }, "discount_baseline_revision": { "type": [ "string", "null" ], "format": "uuid", "description": "Original selling-price revision for an explicit discount. API reference only; never a UI label. Resulting rates, currency, category presence and context thresholds are checked against the original. Existing requests retain their pinned revision." }, "pricing_source": { "type": "string", "enum": [ "workspace", "platform" ] }, "promotion_scope": { "type": [ "string", "null" ], "enum": [ "customer", "global", null ] }, "price_version": { "type": "string", "pattern": "^[0-9]+$" }, "selected_at": { "type": "string", "pattern": "^[0-9]+$", "description": "Selection cutoff as Unix seconds; informational, not a pinned request quote." } } } }, "invoices": { "type": "array", "items": { "type": "object", "required": [ "id", "from_ms", "to_ms", "currency", "amount_nanos", "created_at", "status", "payment_reference" ], "properties": { "id": { "type": "string", "format": "uuid" }, "from_ms": { "type": "integer", "format": "int64" }, "to_ms": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "issued", "paid" ], "description": "Paid when an invoice receipt exists or every included charge is settled by a matching balance debit or has zero value. Credit-backed account debt remains separate." }, "payment_reference": { "type": [ "string", "null" ] } } } } } } } } } } }, "401": { "description": "Invalid or expired credential" }, "404": { "description": "Workspace outside authorized scope" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/billing", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/billing/tariffs": { "post": { "security": [ { "bearerAuth": [] } ], "operationId": "publishCustomerSellingRate", "summary": "Publish an immutable customer selling rate revision", "description": "Installation administration or an explicitly granted platform administrator required. Ordinary company/workspace owners cannot set selling prices. Personal owner-funded models do not accept customer tariffs, even when callable by their owner. This does not grant invoice, payment or credit-policy writes. Rates are currency nanounits per million text tokens, bounded at 1000000000000000. Optional cached_prompt_rate independently prices reported cached input. Null selects flat input pricing. When replacing an existing cached tariff this field must be explicit; omission conflicts. Missing cached usage keeps charges unresolved. No retroactive billing. Cache-Control is no-store. Optional reasoning_completion_rate prices the reported reasoning subset of completion tokens without double counting. Null selects flat output pricing. Replacing a separately priced reasoning tariff requires an explicit rate or null; omission conflicts. Unknown reasoning quantity leaves the charge unresolved. Admission bounds use the larger ordinary/reasoning output rate. Provider procurement rates remain independent. Optional discount_baseline_revision publishes explicit discounted rates against an immutable original revision for the same model and currency. Missing or already discounted baselines, increased rates, changed category presence or context thresholds return 409. No runtime multiplier or historical repricing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model_alias", "currency", "prompt_rate", "completion_rate" ], "properties": { "model_alias": { "type": "string", "maxLength": 200 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "minimum_charge_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Minimum customer charge in currency nanounits (0 to 9223372036854775807), not a token rate. Defaults to zero for new tariffs. Replacing a nonzero minimum requires an explicit value; zero disables it. Known completed usage is charged the greater of the rounded token amount plus request_fee_nanos and this minimum. Unknown usage remains unresolved." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Optional cache-read rate with the same unit and maximum as prompt_rate." }, "expected_revision": { "type": [ "string", "null" ], "format": "uuid" }, "request_fee_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Customer-only fixed fee in currency nanounits (0 to 9223372036854775807). Charge = max(rounded token charge + request fee, minimum charge) for known completed usage. Unknown execution/usage and confirmed rejection do not create a fee. Defaults to zero on new tariffs; replacement of a nonzero fee requires an explicit value; zero disables it." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." }, "discount_baseline_revision": { "type": [ "string", "null" ], "format": "uuid", "description": "Original selling-price revision for an explicit discount. API reference only; never a UI label. Resulting rates, currency, category presence and context thresholds are checked against the original. Existing requests retain their pinned revision." } } } } } }, "responses": { "200": { "description": "Published immutable customer tariff revision", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "description": "Invalid rates, currency or unavailable model alias" }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Installation administration or explicit platform grant required" }, "409": { "description": "Stale expected revision" }, "422": { "description": "Request fields do not match the JSON schema; context_tiers must be an array, never null." } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/projects/{project}/billing/invoices": { "get": { "operationId": "listCustomerInvoices", "summary": "Page complete workspace customer invoice history", "description": "Requires administrative read permission for this workspace. Returns customer billing only, with exact amount strings. Records are ordered by creation time then id descending. Posted customer balance debits, including approved-credit debits, settle the invoice; they are not a new unpaid invoice debt. Refunds do not reopen the original invoice obligation. Reads do not create payment receipts, move funds or disclose Provider purchase prices. A cursor missing from this workspace or filter scope returns 409. Newer inserts do not shift later pages; separate reads are not a frozen snapshot. Cache-Control is no-store. Existing invoice issuance and line reads are unchanged.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Prior next_cursor. Keep filters fixed across pages." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "description": "One currency; no conversion." }, { "name": "from_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799999 }, "description": "Inclusive invoice creation time, Unix milliseconds; not the billed usage interval." }, { "name": "to_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799999 }, "description": "Exclusive invoice creation time; must follow from_ms." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum page size." } ], "responses": { "200": { "description": "Customer invoice page; null next_cursor marks the end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "from_ms", "to_ms", "currency", "amount_nanos", "created_at", "status", "payment_reference" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "from_ms": { "type": "integer", "format": "int64" }, "to_ms": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "issued", "paid" ] }, "payment_reference": { "type": [ "string", "null" ] } } } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid query." }, "401": { "description": "Invalid administrative credential." }, "404": { "description": "Workspace absent or inaccessible." }, "409": { "description": "Cursor outside workspace or filters." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "post": { "security": [ { "bearerAuth": [] } ], "operationId": "issueCustomerUsageInvoice", "summary": "Issue an immutable itemized usage statement", "description": "Installation only. Half-open UTC dispatch interval [from_ms, to_ms), maximum 366 days, one currency. Includes text and media charges. Rejects unresolved priced usage, unsettled media balance debits, overlapping periods and empty periods. Exact idempotent retries return the same invoice. Does not collect money or calculate tax. Cache-Control is no-store.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "from_ms", "to_ms", "currency", "idempotency_key" ], "properties": { "from_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "to_ms": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Invoice identity, including an exact idempotent replay", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "description": "Invalid period or currency" }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Installation authority required" }, "404": { "description": "Workspace outside authorized scope." }, "409": { "description": "Unresolved usage, overlapping or empty period, or changed idempotency payload" } }, "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/billing/invoices/{invoice}": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getCustomerInvoiceLines", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "media_after", "in": "query", "description": "Opaque media_next_cursor from the preceding page. Text groups repeat on each page.", "schema": { "type": "string", "format": "uuid" } } ], "summary": "Read invoice lines grouped by model and pinned rate revision", "description": "Requires workspace read access and an existing invoice in that workspace. Unknown or out-of-scope invoice IDs return 404. Text quantities and rates are pinned to the charge revision; publishing a new tariff does not reprice historical invoice lines. Empty text or media arrays describe an existing invoice with no entries of that kind. Provider expenses are never included. Cache-Control no-store.", "responses": { "200": { "description": "Grouped immutable charge entries", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "media_lines", "media_next_cursor" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "required": [ "model_alias", "revision", "currency", "prompt_rate", "completion_rate" ], "properties": { "model_alias": { "type": "string" }, "revision": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "minimum_charge_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Minimum customer charge in currency nanounits (0 to 9223372036854775807), not a token rate. Defaults to zero for new tariffs. Replacing a nonzero minimum requires an explicit value; zero disables it. Known completed usage is charged the greater of the rounded token amount plus request_fee_nanos and this minimum. Unknown usage remains unresolved." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "request_fee_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Customer-only fixed fee in currency nanounits (0 to 9223372036854775807). Charge = max(rounded token charge + request fee, minimum charge) for known completed usage. Unknown execution/usage and confirmed rejection do not create a fee. Defaults to zero on new tariffs; replacement of a nonzero fee requires an explicit value; zero disables it." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." }, "discount_baseline_revision": { "type": [ "string", "null" ], "format": "uuid", "description": "Original selling-price revision for an explicit discount. API reference only; never a UI label. Resulting rates, currency, category presence and context thresholds are checked against the original. Existing requests retain their pinned revision." } } }, { "type": "object", "required": [ "requests", "prompt_tokens", "completion_tokens", "amount_nanos" ], "properties": { "requests": { "type": "string", "pattern": "^[0-9]+$" }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "cached_prompt_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "minimum_charge_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Minimum customer charge in currency nanounits (0 to 9223372036854775807), not a token rate. Defaults to zero for new tariffs. Replacing a nonzero minimum requires an explicit value; zero disables it. Known completed usage is charged the greater of the rounded token amount plus request_fee_nanos and this minimum. Unknown usage remains unresolved." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "request_fee_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Customer-only fixed fee in currency nanounits (0 to 9223372036854775807). Charge = max(rounded token charge + request fee, minimum charge) for known completed usage. Unknown execution/usage and confirmed rejection do not create a fee. Defaults to zero on new tariffs; replacement of a nonzero fee requires an explicit value; zero disables it." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "reasoning_completion_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning subset priced separately; null for a flat output tariff." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured rate prices it separately; missing quantity remains unresolved." }, "cache_write_prompt_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Separately priced reported cache-write tokens; null when this category has no separate rate." }, "context_minimum_input_tokens": { "type": [ "string", "null" ], "description": "Pinned inclusive input threshold; null means the base schedule." } } } ] } }, "media_next_cursor": { "type": [ "string", "null" ], "format": "uuid", "description": "Pass as media_after for the next page; null when exhausted." }, "media_lines": { "type": "array", "maxItems": 100, "description": "Per-request customer media receipts. Text groups remain in data; both arrays contribute to the invoice total.", "items": { "type": "object", "required": [ "model_alias", "currency", "amount_nanos", "tariff_revision", "meter", "measured_quantity", "billable_quantity", "discount_revisions", "bound_exceeded" ], "properties": { "model_alias": { "type": "string" }, "currency": { "type": "string" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "tariff_revision": { "type": "string" }, "meter": { "type": "string" }, "measured_quantity": { "type": "object", "required": [ "numerator", "denominator" ], "properties": { "numerator": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "billable_quantity": { "type": "object", "required": [ "numerator", "denominator" ], "properties": { "numerator": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "discount_revisions": { "type": "array", "items": { "type": "string" } }, "bound_exceeded": { "type": "boolean" } } } } } } } } }, "401": { "description": "Invalid or expired administrative credential." }, "404": { "description": "Invoice not found in the authorized workspace." } }, "x-niu-implementation": "implemented", "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/billing/invoices/{invoice}/payment": { "parameters": [ { "$ref": "#/components/parameters/billing_openapi_yaml_Organization" }, { "$ref": "#/components/parameters/billing_openapi_yaml_Project" }, { "$ref": "#/components/parameters/billing_openapi_yaml_Invoice" } ], "post": { "security": [ { "adminBearerAuth": [] } ], "operationId": "recordCustomerExternalPayment", "summary": "Record one confirmed full external invoice payment", "description": "Installation only. Records a full external payment only for a positive invoice with no balance-bound charges. Mixed invoices, balance-backed invoices and zero-value invoices conflict. Does not top up an account or accept partial payments. Existing exact retries remain idempotent. Does not charge any payment method. References cannot be reused on another invoice. Cache-Control is no-store.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "payment_reference" ], "properties": { "payment_reference": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed nonempty external payment reference; maximum 200 UTF-8 bytes and no control characters." } } } } } }, "responses": { "200": { "$ref": "#/components/responses/billing_openapi_yaml_InvoiceIdentity" }, "400": { "description": "Invalid reference" }, "403": { "description": "Installation authority required" }, "409": { "description": "Invoice missing, balance-bound or zero-value invoice, already recorded with another reference, or reference already used" } }, "tags": [ "Customer prices and statements" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/provider-memberships": { "get": { "operationId": "listProviderMemberships", "summary": "List the signed-in operator’s complete active Provider memberships", "description": "Returns every active membership for the current non-revoked operator, ordered by Provider name then internal routing ID. This compatibility directory has no cursor or silent history cap. Installation sessions return an empty list. Company membership alone grants no Provider access. Deleted Providers are excluded. IDs are routing references, not display labels.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Complete current membership directory.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "role", "slug" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "manager", "viewer" ] }, "slug": { "type": "string", "maxLength": 48, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Stable readable slug for product URLs. Renaming preserves it." } } } } } } } } }, "401": { "description": "Missing or unusable session." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/platform/payments/epay": { "get": { "operationId": "getPlatformEPayConfiguration", "summary": "Read EPay configuration with platform administrator read access", "description": "Returns enabled, merchant_id, endpoint, notify_url, return_url, methods, has_key and an exact string revision. Never returns merchant keys. Without a saved configuration, reads sanitized deployment defaults.", "responses": { "200": { "description": "Sanitized configuration in data", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_EPayConfiguration" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administrator access required" }, "502": { "description": "Encryption unavailable or stored configuration cannot be opened" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "put": { "operationId": "savePlatformEPayConfiguration", "summary": "Save encrypted EPay configuration with platform administrator write access", "description": "Validates enabled checkout configuration before persistence. An empty key retains the stored credential. Exact expected_revision prevents overwriting concurrent edits. Pending EPay orders prevent credential and checkout-field changes; enabling or disabling unchanged settings remains available and existing orders can still settle. Saves an append-only audit event and takes effect without restarting the gateway. This configures the classic EPay protocol; it does not establish merchant eligibility or live payment qualification. Supported method names and uniqueness are validated even when disabled; a disabled draft may use an empty methods list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "enabled", "merchant_id", "key", "endpoint", "notify_url", "return_url", "methods" ], "properties": { "expected_revision": { "type": "string", "pattern": "^[0-9]+$" }, "enabled": { "type": "boolean" }, "merchant_id": { "type": "string" }, "key": { "type": "string", "writeOnly": true }, "endpoint": { "type": "string", "description": "HTTPS gateway base or complete submit.php endpoint. A base path gets /submit.php appended; a supplied submit.php is preserved, including subdirectories. Trailing slashes are normalized. Query strings, fragments and URL credentials are rejected. The complete encoded checkout must fit 2048 bytes for the largest supported order and amount; invalid enabled configuration is rejected before persistence. Existing saved checkout URLs are not rewritten." }, "notify_url": { "type": "string" }, "return_url": { "type": "string" }, "methods": { "type": "array", "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "alipay", "wxpay" ] } } } } } } }, "responses": { "200": { "description": "Sanitized saved configuration in data, without key", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_EPayConfiguration" } } } } } }, "400": { "description": "Invalid configuration" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform administrator write access required" }, "409": { "description": "Revision conflict or unresolved payment orders" }, "422": { "description": "Malformed JSON shape, missing fields or unknown fields" }, "502": { "description": "Encryption unavailable or stored configuration cannot be opened" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/providers/{provider}": { "get": { "operationId": "getProviderProfile", "summary": "Read Provider business profile", "description": "Requires platform management permission. Returns business display metadata and an integer profile revision. Optional descriptive text and URLs are represented as empty strings when unset. Does not return credentials, procurement prices or qualification evidence. Internal identity is for routing, not display.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved Provider profile", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "name", "description", "website_url", "logo_url", "id", "revision", "slug" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "website_url": { "type": "string" }, "logo_url": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "format": "int64" }, "slug": { "type": "string", "maxLength": 48, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Stable readable slug for product URLs. Renaming preserves it." } } } } } } } }, "400": { "description": "Invalid identifier" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform management permission required" }, "404": { "description": "Provider missing or deleted" }, "503": { "description": "Storage unavailable" } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } }, "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" } ], "patch": { "operationId": "renameProviderBusiness", "summary": "Update Provider business profile", "description": "Requires platform write authority. Name is required. Omitted or null description/URL fields retain saved values; an empty string clears them. All text is trimmed. Supply the integer expected_revision to reject stale edits; omission or null preserves legacy unconditional updates. Every accepted update increments the profile revision and atomically records the authorized actor and resulting Provider name in its audit event, even if values are unchanged. URLs are stored metadata and are not fetched by this operation.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved Provider profile", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "name", "description", "website_url", "logo_url", "id", "revision", "slug" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "website_url": { "type": "string" }, "logo_url": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "format": "int64" }, "slug": { "type": "string", "maxLength": 48, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Stable readable slug for product URLs. Renaming preserves it." } } } } } } } }, "400": { "description": "Invalid profile fields or identifier" }, "401": { "description": "Authentication required" }, "403": { "description": "Platform write authority required" }, "409": { "description": "Stale revision, missing or deleted Provider" }, "422": { "description": "Invalid body shape or unknown field" }, "503": { "description": "Storage unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Nonblank, at most 100 UTF-8 bytes, with no control characters." }, "description": { "type": [ "string", "null" ], "description": "Up to 2,000 characters after trimming; newline, carriage return and tab are permitted." }, "expected_revision": { "type": [ "integer", "null" ], "format": "int64", "minimum": 1, "description": "Send the last read integer revision for conflict protection." }, "website_url": { "type": [ "string", "null" ], "description": "Empty to clear, null/omitted to preserve. Nonempty values must be HTTP(S) URLs with a host, no credentials or control characters and at most 2,048 UTF-8 bytes after trimming." }, "logo_url": { "type": [ "string", "null" ], "description": "Empty to clear, null/omitted to preserve. Nonempty values must be HTTP(S) URLs with a host, no credentials or control characters and at most 2,048 UTF-8 bytes after trimming." } } } } } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } }, "delete": { "operationId": "deleteProviderBusiness", "summary": "Remove an unconfigured Provider from the directory", "description": "Platform administration required. Soft-deletes only a live Provider with no owned API configurations, offers or memberships; disabled configurations and inactive memberships still count as dependencies. Audit history is retained. Concurrent configuration association serializes with deletion. This is not a credential revocation or financial-history deletion operation. Repeating deletion returns 409.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Provider removed from the active directory.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "const": true } } } } } } } }, "401": { "description": "Missing or invalid administrative credential." }, "403": { "description": "Platform administration required." }, "409": { "description": "Unknown or already deleted Provider, or existing configuration, offer or membership dependency." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers": { "post": { "operationId": "createProviderBusiness", "summary": "Create a Provider business identity", "description": "Requires platform administration. Creation grants no membership, qualification, offer or permission to resell supply. Atomically stores the trimmed name, optional description, website and logo URLs with an immutable creation audit. Optional profile fields default to empty strings. Saving URLs does not fetch them.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonblank after trimming; at most 100 UTF-8 bytes before trimming; no control characters. Saved value is trimmed." }, "description": { "type": "string", "maxLength": 2000, "description": "Optional business description, trimmed before saving. Newlines and tabs are allowed; other control characters are rejected." }, "website_url": { "type": "string", "maxLength": 2048, "description": "Optional HTTP or HTTPS website URL without embedded credentials. Trimmed before saving; empty string leaves the website unset." }, "logo_url": { "type": "string", "maxLength": 2048, "description": "Optional HTTP or HTTPS image URL without embedded credentials. Trimmed before saving; empty string uses the default logo." } } } } } }, "responses": { "200": { "description": "Created identity", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "slug" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "maxLength": 48, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Stable readable slug for product URLs. Renaming preserves it." } } } } } } } }, "400": { "description": "Invalid Provider name or profile metadata" }, "401": { "description": "Missing, expired or revoked administrative credential" }, "403": { "description": "Platform administration required" }, "422": { "description": "Malformed body or unknown field" }, "503": { "description": "Storage unavailable" } }, "tags": [ "Providers" ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } }, "get": { "operationId": "listProviderBusinesses", "summary": "List active Provider business identities", "description": "Requires platform administration. Complete compatibility directory with no pagination or silent truncation, ordered by name and internal ID. Total counts retain disabled credential configurations and models. enabled_api_keys counts enabled saved configurations; enabled_model_routes counts enabled model mappings on enabled configurations. These counts do not verify credentials, upstream availability, customer pricing or request authorization. Member counts include active memberships for non-revoked operators. Deleted Providers are excluded. Qualification is explicit and never inferred from configuration counts.", "responses": { "200": { "description": "Active directory", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "logo_url", "api_keys", "models", "members", "qualification_status", "slug" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "logo_url": { "type": "string", "description": "Saved Provider logo URL; empty uses the default logo." }, "api_keys": { "type": "integer", "minimum": 0 }, "models": { "type": "integer", "minimum": 0 }, "members": { "type": "integer", "minimum": 0 }, "offers": { "type": "integer", "minimum": 0, "description": "Saved model offers with agreed Provider rates." }, "ready_offers": { "type": "integer", "minimum": 0, "description": "Active offers with current Provider and exact offer/rate qualification, enabled matching routes and saved credentials. Customer selling prices and authorization remain workspace-specific; this is not a live health check." }, "enabled_api_keys": { "type": "integer", "minimum": 0 }, "enabled_model_routes": { "type": "integer", "minimum": 0 }, "qualification_status": { "type": "string", "enum": [ "qualified", "unqualified" ] }, "slug": { "type": "string", "maxLength": 48, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Stable readable slug for product URLs. Renaming preserves it." } } } } } } } } }, "401": { "description": "Missing, expired or revoked administrative credential" }, "403": { "description": "Platform administration required" }, "503": { "description": "Storage unavailable" } }, "tags": [ "Providers" ], "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/providers/{provider}/members/{operator}": { "put": { "operationId": "setProviderMembership", "summary": "Grant, change or disable a Provider membership", "description": "Requires platform administration. Grants viewer or manager membership to a non-revoked operator. Provider membership grants no platform configuration authority. Membership state and immutable audit are recorded atomically, including the authorized actor, Provider and affected-member names, and active roles before and after the change. Repeated accepted writes can add audit events. Individual transaction lock waits are bounded to 250 ms and statements to 2 seconds; pool acquisition and whole HTTP duration are not bounded by these settings.", "tags": [ "Providers" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operator", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "role", "active" ], "properties": { "role": { "type": "string", "enum": [ "manager", "viewer" ] }, "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Membership saved and audited", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean" } } } } } } } }, "400": { "description": "Invalid membership role" }, "401": { "description": "Missing, expired or revoked administrative credential" }, "403": { "description": "Platform administration required" }, "409": { "description": "Missing/deleted Provider or missing/revoked operator" }, "422": { "description": "Malformed membership input" }, "503": { "description": "Storage unavailable or transaction lock/statement timeout" } }, "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/media-rates/{revision}/retire": { "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "post": { "operationId": "retireSupplierMediaRate", "summary": "End a Provider purchase schedule's eligibility", "description": "Installation write permission only. Appends an immutable eligibility cutoff within the original interval; the cutoff is exclusive for original-card selection. Publish the replacement with a matching effective start before the cutoff. Exact replay is idempotent; changed cutoff or missing Provider/revision conflicts. Historical purchase snapshots, earnings and payments are unchanged. Incomplete or overlapping schedules fail closed. Retirement is not cancellation or a refund.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "effective_until" ], "properties": { "effective_until": { "type": "integer", "format": "int64", "description": "Unix seconds" } } } } } }, "responses": { "200": { "description": "Cutoff saved or exact replay accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "revision", "effective_until" ], "properties": { "revision": { "type": "string" }, "effective_until": { "type": "string", "pattern": "^-?[0-9]+$" } } } } } } } }, "400": { "description": "Invalid cutoff or revision" }, "401": { "description": "Installation authentication required" }, "403": { "description": "Installation write permission required" }, "409": { "description": "Missing scoped revision or conflicting saved cutoff" }, "413": { "description": "Body exceeds 1 KiB" }, "422": { "description": "Malformed typed JSON" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/media-rates": { "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" } ], "get": { "operationId": "listSupplierMediaRates", "summary": "Read this Provider's agreed media purchase schedules", "description": "Installation read access or active membership of this exact Provider only. Returns published terms and separate retirement cutoffs without customer prices, margins or credentials. Publication times not originally recorded remain null. Amounts, route revisions and effective times are exact strings on reads. The cursor is the last returned revision; page size is bounded and retirement never rewrites the original document.", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Bounded purchase history", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_after" ], "properties": { "has_more": { "type": "boolean" }, "next_after": { "type": [ "string", "null" ] }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "card", "retirement_effective_until", "created_at" ], "properties": { "card": { "$ref": "#/components/schemas/provider_business_openapi_yaml_SupplierMediaRateRead" }, "retirement_effective_until": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+$" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } }, "400": { "description": "Invalid page range or cursor" }, "401": { "description": "Valid management session required" }, "404": { "description": "No active membership for this Provider" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } }, "post": { "operationId": "publishSupplierMediaRate", "summary": "Publish confidential agreed Provider media purchase terms", "description": "Installation write permission only; Provider membership and company roles do not authorize procurement configuration. Pins the Provider's current qualified offer and exact credential/model/schema revisions. Publication is immutable and exact replay is idempotent. Missing, ambiguous, stale or differently metered purchase rates block commercial video dispatch before egress. Customer selling rates are independent. No customer charge or platform margin belongs in this body; owner-funded personal use does not acquire a Provider earning. Maximum JSON body is 128 KiB.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provider_business_openapi_yaml_SupplierMediaRateCard" } } } }, "responses": { "200": { "description": "Saved revision or identical replay", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "revision" ], "additionalProperties": false, "properties": { "revision": { "type": "string" } } } } } } } }, "400": { "description": "Invalid tariff or discount" }, "401": { "description": "Installation authentication required" }, "403": { "description": "Installation write permission required" }, "409": { "description": "Changed revision or mismatched/unqualified Provider route" }, "413": { "description": "Body exceeds 128 KiB" }, "422": { "description": "Malformed typed JSON" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/media-offer-models": { "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" } ], "get": { "operationId": "listSupplierMediaOfferModels", "summary": "List named draft media offer bindings", "description": "Installation read authority only. Bounded canonical alias traversal includes configured video schemas on explicitly owned Provider credentials, regardless of activation or qualification. Invalid schemas, personal credentials and aliases owned by another Provider are excluded. No credential, endpoint, upstream model or prices are returned. Exact revision strings and internal binding identifiers must remain out of product UI. Cursor progression includes invalid rows skipped after validation. A page may have empty data with has_more true; clients must continue with next_after until has_more is false. Multiple credentials belonging to the same Provider retain their independent model bindings.", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Draft configuration choices, not dispatch qualification", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_after" ], "properties": { "has_more": { "type": "boolean" }, "next_after": { "type": [ "string", "null" ] }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "model_alias", "api_key_name", "vendor_id", "vendor_revision", "model_revision", "schema_revision", "channel", "offer_revision" ], "properties": { "model_alias": { "type": "string" }, "api_key_name": { "type": "string" }, "vendor_id": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "model_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "schema_revision": { "type": "string" }, "channel": { "type": "string" }, "offer_revision": { "type": [ "string", "null" ], "format": "uuid" } } } } } } } } }, "400": { "description": "Invalid cursor or page size" }, "401": { "description": "Valid management session required" }, "403": { "description": "Installation administration required" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/providers/{provider}/media-offers": { "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" } ], "post": { "operationId": "publishSupplierMediaOffer", "summary": "Save an inactive versioned media offer without text-token prices", "description": "Installation write authority only. Requires exact current credential, model and syntactically validated video schema revisions plus explicit Provider ownership. Personal credentials and foreign aliases are rejected. Publication clears activation and offer qualification. Separate specification-selected purchase and customer selling cards are required for paid video dispatch. Exact receipt replay returns the saved revision without replacing a newer offer, including after configuration changes; a changed document or another Provider's receipt conflicts. Rebinding is allowed only to another credential explicitly owned by the same Provider, and original job routes/prices remain pinned. Neither a saved offer nor reviewed digests establish live protocol qualification.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "model_alias", "vendor_id", "vendor_revision", "model_revision", "schema_revision" ], "properties": { "revision": { "type": "string", "format": "uuid", "description": "Client-owned immutable publication receipt. Reuse only for identical explicit replay." }, "model_alias": { "type": "string", "minLength": 1, "maxLength": 256 }, "vendor_id": { "type": "string", "format": "uuid" }, "vendor_revision": { "description": "Exact positive signed 64-bit revision; decimal strings preserve browser precision.", "oneOf": [ { "type": "integer", "format": "int64", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "maxLength": 19 } ] }, "model_revision": { "description": "Exact positive signed 64-bit revision; decimal strings preserve browser precision.", "oneOf": [ { "type": "integer", "format": "int64", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "maxLength": 19 } ] }, "schema_revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "expected_revision": { "type": [ "string", "null" ], "format": "uuid", "description": "Current offer revision, or null for a new offer." } } } } } }, "responses": { "200": { "description": "Inactive media offer saved or identical receipt replayed", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "description": "Invalid model binding" }, "401": { "description": "Valid management session required" }, "403": { "description": "Installation write administration required" }, "409": { "description": "Changed receipt, stale binding, foreign ownership or offer revision conflict" }, "413": { "description": "Publication exceeds 4 KiB" }, "422": { "description": "Malformed JSON document or unexpected fields" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/media-rate-models": { "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" } ], "get": { "operationId": "listSupplierMediaRateModels", "summary": "List current media pricing configuration choices", "description": "Installation read authority only. Named model and API-key choices include current qualified active offer bindings and syntactically validated media-schema constraints. This does not qualify dispatch protocols or provide prices. Disabled routes, personal credentials, invalid schemas and foreign Providers are excluded. Revisions remain exact strings; clients keep binding identifiers out of product UI and publication rechecks current state. Cursor ordering uses model alias, including rows skipped for invalid schemas.", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Bounded configuration choices", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_after" ], "properties": { "has_more": { "type": "boolean" }, "next_after": { "type": [ "string", "null" ] }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "model_alias", "api_key_name", "offer_revision", "vendor_revision", "model_revision", "schema_revision", "channel", "resolutions", "reference_video" ], "properties": { "model_alias": { "type": "string" }, "api_key_name": { "type": "string" }, "offer_revision": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "model_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "schema_revision": { "type": "string" }, "channel": { "type": "string" }, "resolutions": { "type": "array", "maxItems": 64, "items": { "type": "string" } }, "reference_video": { "type": "boolean" } } } } } } } } }, "400": { "description": "Invalid cursor or page size" }, "401": { "description": "Valid management session required" }, "403": { "description": "Installation administration required" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/providers/{provider}/media-rates/replace": { "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" } ], "post": { "operationId": "replaceSupplierMediaRate", "summary": "Atomically replace agreed media purchase terms", "description": "Installation write authority only. Publishes an immutable replacement and ends the original schedule at the replacement's effective_from in one transaction. Dimensions and meter must match the original; current offer, credential, model and schema bindings are rechecked. Original terms, pinned job prices and earnings remain unchanged. Exact replay is idempotent while the configuration remains eligible. Conflicting cutoff, changed replay or stale binding rejects the whole transaction. No transfers, job cancellations, refunds or automatic retries occur.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "previous_revision", "rate" ], "properties": { "previous_revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "rate": { "$ref": "#/components/schemas/provider_business_openapi_yaml_SupplierMediaRateCard" } } } } } }, "responses": { "200": { "description": "Complete transition saved", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision", "effective_from" ], "properties": { "revision": { "type": "string" }, "effective_from": { "type": "string", "pattern": "^-?[0-9]+$" } } } } } } } }, "400": { "description": "Invalid rate, dimensions, meter or effective period" }, "401": { "description": "Valid management session required" }, "403": { "description": "Installation administration required" }, "409": { "description": "Original or current binding unavailable, cutoff conflict or changed replay" }, "413": { "description": "Configuration exceeds 128 KiB" }, "503": { "description": "Durable storage unavailable" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/offers": { "get": { "operationId": "listProviderOffersPage", "summary": "Page current Provider offers and rate revisions", "description": "Platform administration or active membership of this Provider required. Canonical model-alias keyset order, 1–100 entries per page. Includes paused and unqualified drafts; does not activate an offer or establish commercial qualification. after must identify an existing offer of this Provider or returns 409. Follow next_after until null. Each page has one statement snapshot; multiple pages are not a frozen snapshot. No customer identities, requests, credentials or endpoint data. Dashboard offers remain a 1000-row preview with offers_has_more.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "Current scoped offers and continuation.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_after" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "model_alias", "active", "qualified", "revision", "rate_kind", "currency", "prompt_rate", "completion_rate", "cached_prompt_rate", "route_ready", "reasoning_completion_rate", "cache_write_prompt_rate" ], "properties": { "id": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "active": { "type": "boolean" }, "qualified": { "type": "boolean" }, "revision": { "type": "string", "format": "uuid" }, "rate_kind": { "type": "string", "enum": [ "text", "media" ] }, "currency": { "type": [ "string", "null" ] }, "prompt_rate": { "type": [ "string", "null" ] }, "completion_rate": { "type": [ "string", "null" ] }, "cached_prompt_rate": { "type": [ "string", "null" ] }, "route_ready": { "type": "boolean" }, "reasoning_completion_rate": { "type": [ "string", "null" ], "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured Provider rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." } } } }, "next_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid pagination query." }, "401": { "description": "Invalid session." }, "404": { "description": "Provider missing or unauthorized." }, "409": { "description": "Missing or foreign continuation alias." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } }, "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" } ], "post": { "operationId": "publishProviderPayoutRates", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "summary": "Publish an immutable agreed Provider payout schedule", "description": "Installation-only publication binds an existing vendor model alias to one Provider. Decimal prices are currency nanounits per million tokens. Existing attempts retain the revision pinned before dispatch. Stale expected_revision and incompatible vendor ownership conflict. Initial creation requires null expected_revision. Optional category rates price reported subsets separately; null uses ordinary rates. Omitting an existing category rate or tier schedule conflicts. Empty context_tiers clears the schedule; null is rejected. The highest inclusive threshold on aggregate input (including cache reads/writes) selects a complete schedule; category null within a tier does not inherit its base category rate. Missing required quantities leave earnings unresolved. Every publication pauses the offer and requires renewed qualification. Procurement budgets and customer charges remain independent.", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model_alias", "currency", "prompt_rate", "completion_rate", "expected_revision" ], "properties": { "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Currency nanounits per million tokens; maximum 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Currency nanounits per million tokens; maximum 1000000000000000." }, "expected_revision": { "type": [ "string", "null" ], "format": "uuid" }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Currency nanounits per million tokens; maximum 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Currency nanounits per million tokens; maximum 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Currency nanounits per million tokens; maximum 1000000000000000." } } } } } }, "responses": { "200": { "description": "New immutable revision", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "description": "Invalid prices or tier thresholds" }, "403": { "description": "Installation administration required" }, "409": { "description": "Ownership, expected revision, or omitted current schedule conflict" }, "422": { "description": "JSON schema mismatch; context_tiers must be an array, never null" } }, "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/offers/{offer}": { "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" }, { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "patch": { "operationId": "setProviderOfferAvailability", "summary": "A Provider manager can pause or resume an owned offer", "description": "Pausing prevents new admissions. Already dispatched requests may complete and accrue earnings. Viewers and unrelated operators cannot mutate offers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "active" ], "properties": { "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Availability saved and audited" }, "404": { "description": "No eligible Provider membership" }, "409": { "description": "Offer unavailable in Provider scope" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/api/v1/providers/{provider}/dashboard": { "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" }, { "$ref": "#/components/parameters/provider_business_openapi_yaml_days" } ], "get": { "operationId": "getProviderDashboard", "summary": "Provider-scoped earnings and operations; active explicit membership required", "description": "Returns one repeatable-read snapshot in data. Balances group by currency and include all-time earned_nanos, unpaid_nanos, paid_nanos and period_nanos. All amounts and usage totals are decimal integer strings. Traffic includes admitted requests, completed requests, reported tokens and unresolved earnings in the selected rolling period. Daily earnings use UTC. Offers include rate_kind (text or media), model identity and availability (up to 1000); offers_has_more explicitly identifies truncation, and GET /api/v1/providers/{provider}/offers traverses the complete current directory. Text offers retain agreed currency, prompt_rate and completion_rate strings plus nullable cached_prompt_rate, cache_write_prompt_rate and reasoning_completion_rate. Consumption includes nullable cached_prompt_tokens, cache_write_prompt_tokens and reasoning_completion_tokens for separately priced categories. Media offers return null for text-price fields; their independent specification-selected purchase cards are available through media-rates. Consumption groups verified text tokens, request counts, agreed rates, earnings and unpaid amounts by model, payout revision and selected context_minimum_input_tokens (null for base rates); media_consumption separately groups media meter quantities, specifications, agreed purchase prices and earnings. Media earnings have null text-token categories and use the same exact external-payment settlement ledger; no request identifiers, customer identities, workspaces or task references are returned; settlements contain the latest 100 all-time external payment records; GET /api/v1/providers/{provider}/settlements provides filtered keyset pagination beyond this preview. No customer identity, prompt, credential, endpoint or customer charges are returned. This is an accrual ledger, not a guarantee of payment eligibility or schedule.", "responses": { "200": { "description": "Provider dashboard in data" }, "400": { "description": "Period must be 7, 30, or 90 days" }, "403": { "description": "Installation sessions do not imply Provider membership" }, "404": { "description": "No active membership for this provider" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/providers/{provider}/administration": { "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" }, { "$ref": "#/components/parameters/provider_business_openapi_yaml_days" } ], "get": { "operationId": "getProviderAdministrationDashboard", "summary": "Explicit installation oversight of the Provider dashboard", "description": "Only an active Provider is readable. Soft-deleted and missing Providers return the existing unavailable-resource conflict; audit history is retained.", "responses": { "200": { "description": "Same dashboard snapshot as the Provider endpoint" }, "403": { "description": "Installation access required" }, "409": { "description": "Provider is missing or deleted" } }, "security": [ { "operatorBearer": [] } ], "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/providers/{provider}/earnings": { "get": { "operationId": "listProviderEarnings", "summary": "Page platform Provider accrued and paid obligations", "description": "Platform administration required; Provider membership and company ownership do not grant access. Full retained earning history, creation time descending then attempt ID ascending, using the existing ledger index. Exact amount strings; no customer identity, workspace, credential or customer selling price. The id is an internal selection value for the existing settlement POST, never a display label. A page is one database snapshot; settlement status may change between requests and settlement writes revalidate unpaid selections. Reads do not create earnings or payments. Missing or out-of-filter cursors return 409. Cache-Control no-store.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Prior next_cursor; omit for the first page." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "description": "Filter one currency without conversion." }, { "name": "from_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799999 }, "description": "Inclusive payment-record creation time. Unix milliseconds." }, { "name": "to_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799999 }, "description": "Exclusive payment-record creation time; must follow from. Unix milliseconds." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum page size." } ], "responses": { "200": { "description": "Provider earning page; next_cursor null ends traversal.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "model_alias", "currency", "amount_nanos", "billing_meter", "created_at", "status", "revision", "offer_id", "context_minimum_input_tokens", "prompt_tokens", "completion_tokens", "cached_prompt_tokens", "cache_write_prompt_tokens", "reasoning_completion_tokens" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "created_at": { "type": "string", "format": "date-time" }, "model_alias": { "type": "string" }, "billing_meter": { "type": "string" }, "status": { "type": "string", "enum": [ "accrued", "paid" ] }, "revision": { "type": "string", "format": "uuid" }, "offer_id": { "type": "string", "format": "uuid" }, "context_minimum_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "prompt_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "completion_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cached_prompt_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_prompt_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_completion_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } } } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid filters, range or page size." }, "401": { "description": "Invalid credential." }, "403": { "description": "Platform administration required, including for Provider members." }, "404": { "description": "Provider does not exist or is deleted." }, "409": { "description": "Cursor not in this Provider and filter scope." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } } }, "/api/v1/providers/{provider}/settlements": { "get": { "operationId": "listProviderSettlements", "summary": "Page Provider settlement history", "description": "Platform administration or active membership of this Provider required. Lists immutable records of externally confirmed payments; does not initiate payment or claim a bank balance. Ordered by created_at then id descending, with 1–100 rows per page. All amounts are exact currency nanounit strings. No customer, workspace, request, attempt, credential, or procurement detail is included. Time range is from_ms-inclusive and to_ms-exclusive (Unix milliseconds). Keep filters fixed while following next_cursor; a cursor outside this Provider or the filters returns 409. Inserts newer than the cursor do not shift later pages; pages do not constitute a frozen multi-request snapshot. All responses are no-store. Existing POST recording semantics are unchanged.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Prior next_cursor; omit for the first page." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "description": "Filter one currency without conversion." }, { "name": "from_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799999 }, "description": "Inclusive payment-record creation time. Unix milliseconds." }, { "name": "to_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799999 }, "description": "Exclusive payment-record creation time; must follow from. Unix milliseconds." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum page size." } ], "responses": { "200": { "description": "Settlement page; null next_cursor means the end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "currency", "amount_nanos", "payment_reference", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "payment_reference": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid filters, range or page size." }, "401": { "description": "Invalid credential." }, "403": { "description": "Unsupported administrative authority." }, "404": { "description": "Provider not found or membership unavailable." }, "409": { "description": "Cursor not in this Provider and filter scope." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "provider" } }, "parameters": [ { "$ref": "#/components/parameters/provider_business_openapi_yaml_provider" } ], "post": { "operationId": "recordExternalProviderPayment", "summary": "Record an already completed external Provider payment", "description": "Platform administration required; Provider membership does not grant this write. Does not transfer funds. Selected earnings must belong to this Provider, share one currency, remain unpaid and have a positive exact total. The server computes the amount. Reuse the supplied idempotency key with the identical reference and entry set for retries; entry order is irrelevant. Changed replay, duplicate payment reference or unavailable selections return 409. No customer balance credit or Provider qualification is created.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "idempotency_key", "payment_reference", "attempt_ids" ], "properties": { "idempotency_key": { "type": "string", "format": "uuid" }, "payment_reference": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Nonblank reference, at most 200 UTF-8 bytes, no control characters. Preserve the exact value on retry." }, "attempt_ids": { "type": "array", "minItems": 1, "maxItems": 1000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" }, "description": "Internal selection IDs from the platform earning history; never display IDs or require users to paste them." } } } } } }, "responses": { "200": { "description": "Recorded or replayed settlement identity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "description": "Invalid reference, entry set, or currency mix." }, "401": { "description": "Invalid administrative credential." }, "403": { "description": "Platform administration required." }, "409": { "description": "Provider or earnings unavailable, changed replay, or duplicate payment reference." }, "503": { "description": "Storage unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Providers" ], "x-niu-authority": { "audience": "provider", "principals": [ "provider_member", "platform_admin", "installation_admin" ], "required_capability": "provider_manage", "scope": "provider" } } }, "/healthz": { "get": { "operationId": "getHealth", "summary": "Check process health", "responses": { "200": { "description": "The Niu process is serving requests." } }, "security": [], "tags": [ "Service health" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/readyz": { "get": { "operationId": "getReadiness", "summary": "Check gateway readiness", "description": "Reports Niu core readiness only. Private Enterprise module failures are reported by /enterprise/readyz and do not make healthy core routes unready.", "responses": { "200": { "description": "The gateway loaded its configuration and can accept requests." } }, "security": [], "tags": [ "Service health" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/enterprise/readyz": { "get": { "operationId": "getEnterpriseReadiness", "summary": "Check Enterprise module readiness", "description": "In an Enterprise distribution, reports whether the core database and all required private modules are healthy within a three-second deadline. Community builds without a release manifest report disabled readiness. This endpoint does not affect Niu core readiness.", "responses": { "200": { "description": "Enterprise modules are ready, or no Enterprise modules are configured." }, "503": { "description": "At least one required Enterprise module is unavailable or incompatible." } }, "security": [], "tags": [ "Service health" ], "x-niu-authority": { "audience": "public", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/v1/models": { "get": { "operationId": "listModels", "summary": "List key-accessible model aliases and workspace customer prices", "description": "Requires a current workspace API key and filters aliases by its model grants and organization access. customer_pricing is the current workspace selling tariff or null; personal credential routes omit customer prices. Token rates use currency nanounits per million tokens. request_fee_nanos and minimum_charge_nanos use currency nanounits per known completed request. Amounts are exact strings. Listing a model or tariff does not qualify generation or guarantee admission, balance or upstream availability. No Provider procurement rates, internal revision identifiers, upstream credentials, endpoints or private model mappings are exposed. Enrolled text models resolve the own-customer promotion, then global promotion, then standard price at server time; this is advisory until admission pins a concrete revision. No other-customer rules are exposed.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "responses": { "200": { "description": "Current key-visible aliases and customer-only prices.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "owned_by", "customer_pricing" ], "properties": { "id": { "type": "string", "description": "Public model alias." }, "object": { "type": "string", "const": "model" }, "owned_by": { "type": "string", "const": "niu" }, "customer_pricing": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_WorkspaceCustomerModelPrice" }, { "type": "null" } ] }, "customer_unit_pricing": { "type": [ "object", "null" ] } } } } } } } } }, "401": { "description": "Missing, revoked, expired or invalid key." }, "403": { "description": "Current credential access policy denies the request." }, "503": { "description": "Storage or route configuration unavailable." } }, "x-niu-implementation": "implemented", "tags": [ "Model discovery" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/catalog/v1/models": { "get": { "operationId": "listPublicCatalogModels", "summary": "List model aliases explicitly published by the gateway operator", "description": "Returns only aliases with public_catalog enabled. Provider names, upstream identifiers, endpoints and credentials are omitted. Public catalog metadata includes provider-advertised prices, which do not configure billing.", "responses": { "200": { "description": "Public model aliases and declared capabilities. generation_capabilities reports configured Chat/Video preview support, with null Chat for unresolved legacy metadata; it never grants inference authority." } }, "security": [], "tags": [ "Model discovery" ], "x-niu-authority": { "audience": "model", "principals": [ "anonymous" ], "required_capability": "public", "scope": "installation" } } }, "/v1/chat/completions": { "post": { "operationId": "createChatCompletion", "summary": "Create an OpenAI-compatible chat completion", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "x-niu-log-payloads", "in": "header", "required": false, "description": "Request and sanitized customer response content is retained until 24 hours after the original request creation time by default. Send false (case-insensitive) to disable capture for this request; true or an omitted header retains content. Invalid values or repeated headers are rejected before inference. Requests exceeding the 1 MB capture limit are rejected; response capture is truncated at 1 MB. Does not backfill earlier requests.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" } }, { "name": "X-Niu-Task-ID", "in": "header", "required": false, "description": "Optional opaque task correlation key. Requests with the same value can be grouped in workspace activity. Niu stores the value as metadata and does not forward it to the provider.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]{1,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ChatCompletionRequest" } } } }, "responses": { "200": { "description": "A normalized chat completion or compatible event stream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Chat completion SSE chunks. HTTP 200 starts the stream; preserve terminal evidence and optional usage rather than treating a disconnected stream as complete." } } }, "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid request, generation-parameter type or range, or unsupported operation; rejected before admission and Provider dispatch.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Missing or invalid gateway credentials.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "402": { "description": "Insufficient balance or spending limit exceeded.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Source IP or enforced policy denies the request. Recorded preparation-policy refusals use error.type guardrail_denied before model dispatch; post-dispatch output withholding uses guardrail_output_withheld and generation charges may apply. Do not classify every 403 as a Guardrail refusal.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "description": "Admission conflict before dispatch. Type route_configuration_changed identifies a changed managed credential/model configuration; that request was not sent upstream. Other conflicts retain their own error type.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "413": { "description": "Request body exceeds 1 MiB; rejected before inference whether payload capture is enabled or disabled. Framework responses may use a plain-text body.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "description": "Configured pricing requires an unavailable token category (unsupported_token_pricing), or a token admission bound is unavailable. Chat reads explicit prompt_tokens_details.cache_write_tokens as a subset of total input, alongside cache reads and reasoning output; missing categories remain unknown. Priced text content blocks accept bounded ephemeral cache_control metadata.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "API key request, concurrency or token rate limit exceeded.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "501": { "description": "Tool or structured-output capability is disabled, or the requested combination is unsupported. The unsupported_operation_error message identifies the feature and a supported request alternative; rejection occurs before admission or upstream dispatch.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "502": { "description": "Provider request failed.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "503": { "description": "Durable storage or configured route unavailable. guardrail_output_busy identifies exhausted full-output collection capacity before admission or dispatch.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } } }, "x-niu-status": "Basic chat is implemented for configured native provider routes. Local buffered_full output rules support single-choice plain text streaming: retain the real upstream stream until terminal evidence, inspect the complete bounded output, then emit compatible sanitized chunks. Required output withholding emits a guardrail_output_withheld SSE error without [DONE]; known executed usage remains billable. Text buffering is limited to 1 MiB and total stream bytes to 2 MiB, with four concurrent collectors per process. Output rules with tools or structured format remain unsupported. Observation-only plain-text streams preserve delivery and asynchronously record clear, matched or indeterminate without transforming output. Mandatory and observation rules compose across workspace/key scopes. Optional collection and inspection have separate bounded capacity; observation overload does not deny the request. Function tools, streaming tool deltas, and structured JSON are opt-in on OpenAI-compatible routes only. Niu validates tool-call shape and structured JSON against a valid self-contained schema; json_object output must be an object. Schema compilation is offline and limited to 64 KiB, 4096 JSON nodes and depth 32, with bounded regular expressions. Niu does not execute tools. Structured JSON streaming validates assembled output before releasing [DONE], with a 1 MiB total content/refusal bound and at most 128 choices. Partial deltas are provisional; invalid final output sends an upstream_invalid_response SSE error without [DONE], while reported terminal usage remains accounting evidence. Token-priced routes support function calls and text-only tool-result conversations under the same input/output rates. Serialized messages, tool definitions, tool choices and response-format instructions count toward the configured input byte guard. Hosted tools and additional billable modalities remain unsupported. Chat pools allow at most one different-credential successor after a canonical OpenRouter immediate HTTP 401 with durable nonexecution and released holds, preserving operation price and funding under one deadline. Other errors and streams already returned to the client are not retried.", "x-niu-implementation": "implemented", "description": "Uses the workspace API key and its model grants, source policy, rate/concurrency/token limits and configured billing. Streaming HTTP 200 starts delivery; completion and reported usage require the terminal stream evidence. Niu does not execute function tools. See the supported scope below for structured output and modality restrictions.", "tags": [ "Chat completions" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/embeddings": { "post": { "operationId": "createEmbedding", "summary": "Create OpenAI-compatible text embeddings", "description": "The configured route must use an OpenAI-compatible protocol and explicitly declare embedding support. Optional dimensions and base64 output require separate route capabilities. These declarations are operator assertions, not provider conformance evidence. Unsupported providers or capabilities are rejected before durable operation and attempt creation. Workspace model grants, IP policy, rate/concurrency/token limits and configured customer billing apply before dispatch.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "x-niu-log-payloads", "in": "header", "required": false, "description": "Request and sanitized customer response content is retained until 24 hours after the original request creation time by default. Send false (case-insensitive) to disable capture for this request; true or an omitted header retains content. Invalid values or repeated headers are rejected before inference. Requests exceeding the 1 MB capture limit are rejected; response capture is truncated at 1 MB. Does not backfill earlier requests.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" } }, { "name": "X-Niu-Task-ID", "in": "header", "required": false, "description": "Optional opaque task correlation key. Requests with the same value can be grouped in workspace activity. Niu stores the value as metadata and does not forward it to the provider.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]{1,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "input" ], "properties": { "model": { "type": "string", "minLength": 1 }, "input": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "maxItems": 2048, "items": { "type": "string", "minLength": 1 } } ] }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "default": "float" }, "dimensions": { "type": "integer", "minimum": 1, "maximum": 65536 }, "user": { "type": "string", "maxLength": 512 } } } } } }, "responses": { "200": { "description": "One validated embedding per input item; the configured upstream model is replaced with the public model alias.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "model" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "required": [ "embedding" ], "properties": { "object": { "type": "string", "const": "embedding" }, "index": { "type": "integer", "minimum": 0 }, "embedding": { "oneOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] } }, "additionalProperties": true } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid body, unsupported field, or invalid input shape." }, "401": { "description": "Missing or invalid gateway credentials." }, "402": { "description": "Insufficient balance or configured spending limit exceeded." }, "403": { "description": "Source IP or enforced policy denies the request. Recorded preparation-policy refusals use error.type guardrail_denied before model dispatch; do not classify every 403 as a Guardrail refusal." }, "404": { "description": "Model alias does not exist or is unavailable to this key." }, "409": { "description": "Admission conflict before dispatch. Type route_configuration_changed identifies a changed managed credential/model configuration; that request was not sent upstream. Other conflicts retain their own error type." }, "413": { "description": "Request body exceeds 1 MiB; rejected before inference whether payload capture is enabled or disabled. Framework responses may use a plain-text body." }, "422": { "description": "Invalid JSON or unsupported token admission/pricing requirements. Embeddings does not report cache-read, cache-write or reasoning subsets. Separate rates for unavailable categories in a bound base or reachable tier schedule return unsupported_token_pricing before dispatch or reservation commits." }, "429": { "description": "API key request, concurrency or token rate limit exceeded." }, "501": { "description": "The model route lacks the required embedding, configurable-dimension or base64 capability, or uses an unsupported protocol. The unsupported_operation_error message identifies the limitation and request alternative before admission." }, "502": { "description": "Provider request failed or returned an invalid embedding response." }, "503": { "description": "Durable storage or configured route unavailable." } }, "x-niu-status": "OpenAI-compatible text inputs and float/base64 response vectors; no token-ID arrays, multimodal inputs, or streaming.", "x-niu-implementation": "implemented", "tags": [ "Embeddings" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1beta/models/{model_action}": { "post": { "operationId": "generateContent", "summary": "Generate native buffered Gemini text", "x-niu-implementation": "implemented", "x-niu-status": "Static or managed gemini routes only; successful native upstream completion remains unverified.", "description": "Set provider gemini and supports_generate_content true on a static route, or create a managed gemini credential and opt its model mapping into supports_generate_content. model_action is the URL-encoded public alias followed by :generateContent; encode slashes inside aliases. Niu bearer or x-niu-api-key authentication is required. Only bounded nonstreaming text with generationConfig.maxOutputTokens is supported; tools, media, cachedContent, thinking configuration and other actions are rejected before dispatch. Uses shared grants, key limits, prepaid reservations, guardrails, diagnostics and settlement; no Chat translation or automatic retry. Total output is totalTokenCount minus promptTokenCount, which includes reported thoughts under the native contract. Missing category counts remain unknown; cache-write rates are unsupported and rejected before dispatch. Unknown aggregate usage retains priced liabilities. Client response fields are projected; modelVersion uses the public alias and thought signatures are not exposed. Native SDK compatibility and successful end-to-end billing remain unverified as documented.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "model_action", "in": "path", "required": true, "schema": { "type": "string", "example": "fast:generateContent" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "contents", "generationConfig" ], "properties": { "contents": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": [ "parts" ], "properties": { "role": { "type": "string", "enum": [ "user", "model" ] }, "parts": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string" } } } } } } }, "systemInstruction": { "type": "object", "additionalProperties": false, "required": [ "parts" ], "properties": { "role": { "type": "string", "enum": [ "user", "model", "system" ] }, "parts": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string" } } } } } }, "generationConfig": { "type": "object", "additionalProperties": false, "required": [ "maxOutputTokens" ], "properties": { "maxOutputTokens": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "candidateCount": { "type": "integer", "enum": [ 1 ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "topP": { "type": "number", "minimum": 0, "maximum": 1 }, "topK": { "type": "integer", "minimum": 1, "maximum": 10000 }, "stopSequences": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 512 } } } } } } } } }, "responses": { "200": { "description": "Projected native text result. Reported usage does not prove a settled charge.", "content": { "application/json": { "schema": { "type": "object", "required": [ "candidates", "usageMetadata", "modelVersion" ], "properties": { "modelVersion": { "type": "string", "description": "Niu public model alias, not an upstream version guarantee." }, "responseId": { "type": "string" }, "candidates": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "index", "content", "finishReason" ], "properties": { "index": { "type": "integer", "enum": [ 0 ] }, "content": { "type": "object", "required": [ "role", "parts" ], "properties": { "role": { "type": "string", "enum": [ "model" ] }, "parts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string" } } } } } }, "finishReason": { "type": "string", "enum": [ "STOP", "MAX_TOKENS" ] } } } }, "usageMetadata": { "type": "object", "properties": { "promptTokenCount": { "type": [ "integer", "null" ], "minimum": 0 }, "candidatesTokenCount": { "type": [ "integer", "null" ], "minimum": 0 }, "totalTokenCount": { "type": [ "integer", "null" ], "minimum": 0 }, "cachedContentTokenCount": { "type": [ "integer", "null" ], "minimum": 0 }, "thoughtsTokenCount": { "type": [ "integer", "null" ], "minimum": 0 } } } } } } } }, "400": { "description": "Invalid or unsupported text document", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Niu authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "402": { "description": "Insufficient capacity", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Scope or policy denial", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Unavailable model", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "413": { "description": "Body exceeds 1 MiB", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Unsupported configured token category pricing", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Key or workspace limit", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "501": { "description": "Unsupported action or undeclared native route", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "502": { "description": "Sanitized upstream or output failure", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Unavailable service", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "integer" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "tags": [ "Messages and GenerateContent" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/messages": { "post": { "operationId": "createMessage", "x-niu-implementation": "implemented", "x-niu-status": "Native text and client tools with separately enabled text/tool streaming. Media and extended thinking remain unsupported.", "summary": "Create a native text Message, optionally streamed", "description": "Requires supports_messages on an OpenRouter or Anthropic route. Uses Niu bearer or x-niu-api-key credentials, workspace grants, source policy, limits, guardrails and billing. Requests are limited to 1 MiB and conservative configured pricing bounds. No Chat translation. Media, beta headers and unsupported fields are rejected before dispatch. Buffered client tools require supports_messages_tools; route pools filter this capability. Tool definitions are limited to name, description and bounded offline object input_schema. tool_choice supports auto/any/none/tool and optional disable_parallel_tool_use. History requires uniquely identified assistant tool_use blocks followed immediately by matching user tool_result blocks with string content, before ordinary user text. Tools must remain declared for tool history. Streaming tools additionally require supports_messages_streaming_tools, supports_messages_tools and supports_messages_streaming; pools filter all required capabilities. Only sequential content blocks are supported; interleaved tool blocks fail safely. Native input_json_delta fragments are bounded to 64 KiB per tool and 256 KiB per message, parsed and schema-validated before content_block_stop is emitted. Tool IDs must be unique. Consumers must wait for message_stop before executing tool calls; error events and incomplete streams do not establish valid completion. Tool names, IDs and arguments are validated and projected; Niu does not execute tools. Required text input/output inspection rejects tool requests before dispatch rather than silently skipping tool content. A tool_use stop is a completed provider turn, not completion of a client task. Only version 2023-06-01 is supported (also used when omitted). Native input_tokens excludes cache reads/writes; total input accounting requires all three input categories plus output_tokens. Missing or null categories leave usage unresolved and reservations retained. Separate reasoning rates in the bound base price or a reachable context tier are rejected atomically before dispatch with 422 and x-niu-error-code unsupported_token_pricing; this adapter cannot report reasoning usage. Returned usage is not proof of a settled charge. Upstream commercial metadata is never forwarded. Native SDK and Claude Code compatibility are unverified. Streaming additionally requires supports_messages_streaming. Route pools filter this capability before priority/weight selection; no eligible candidate returns 503 before dispatch. Native SSE validates ordered text and opted-in tool events and projects customer-safe fields with a 64 KiB per-event limit. Completion requires message_stop; missing terminal evidence, upstream interruption and client cancellation retain uncertainty and reservations. Cumulative usage updates replace earlier counts; never sum deltas or infer missing categories. HTTP 200 alone is not completed usage. No credential switch or inference retry after headers. Required output inspection rejects streaming before dispatch. SDK messages.stream() stops at message_stop; an upstream extra [DONE] is not forwarded.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "anthropic-version", "in": "header", "schema": { "type": "string", "enum": [ "2023-06-01" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "max_tokens", "messages" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } } } } } } ] }, "stream": { "type": "boolean", "default": false }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "stop_sequences": { "type": "array", "maxItems": 4, "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "messages": { "type": "array", "minItems": 1, "maxItems": 1024, "items": { "type": "object", "additionalProperties": false, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "minItems": 1, "maxItems": 128, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "id", "name", "input" ], "properties": { "type": { "const": "tool_use" }, "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "input": { "type": "object" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "tool_use_id", "content" ], "properties": { "type": { "const": "tool_result" }, "tool_use_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "content": { "type": "string" }, "is_error": { "type": "boolean" } } } ] } } ] } } } }, "tools": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "input_schema" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "description": { "type": "string" }, "input_schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "object" } }, "additionalProperties": true } } } }, "tool_choice": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "enum": [ "auto", "any", "none", "tool" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "disable_parallel_tool_use": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Native sanitized Message or opted-in text SSE. Tool turns may require a client continuation. Inspect usage and billing diagnostics separately.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "role", "model", "content", "stop_reason", "stop_sequence", "usage" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "model": { "type": "string" }, "content": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "id", "name", "input" ], "properties": { "type": { "const": "tool_use" }, "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "input": { "type": "object" } } } ] } }, "stop_reason": { "type": "string", "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use" ] }, "stop_sequence": { "type": [ "string", "null" ] }, "usage": { "type": "object", "additionalProperties": false, "required": [ "input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens" ], "properties": { "input_tokens": { "type": [ "integer", "null" ], "minimum": 0 }, "output_tokens": { "type": [ "integer", "null" ], "minimum": 0 }, "cache_creation_input_tokens": { "type": [ "integer", "null" ], "minimum": 0 }, "cache_read_input_tokens": { "type": [ "integer", "null" ], "minimum": 0 } } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "Native message_start, text content block events, cumulative message_delta and message_stop. Sanitized error events terminate failed streams." } } }, "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid or unsupported input.", "headers": { "x-niu-error-code": { "description": "Niu-specific machine-readable reason, such as key_spending_limit_exceeded or budget_exceeded. Native error.type remains the native category. Shared middleware errors may omit this header.", "schema": { "type": "string" } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Invalid Niu key.", "headers": { "x-niu-error-code": { "description": "Niu-specific machine-readable reason, such as key_spending_limit_exceeded or budget_exceeded. Native error.type remains the native category. Shared middleware errors may omit this header.", "schema": { "type": "string" } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "402": { "description": "Insufficient spending capacity.", "headers": { "x-niu-error-code": { "description": "Niu-specific machine-readable reason, such as key_spending_limit_exceeded or budget_exceeded. Native error.type remains the native category. Shared middleware errors may omit this header.", "schema": { "type": "string" } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Input or output policy denial.", "headers": { "x-niu-error-code": { "description": "Niu-specific machine-readable reason, such as key_spending_limit_exceeded or budget_exceeded. Native error.type remains the native category. Shared middleware errors may omit this header.", "schema": { "type": "string" } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Model unavailable or outside key grants.", "headers": { "x-niu-error-code": { "description": "Niu-specific machine-readable reason, such as key_spending_limit_exceeded or budget_exceeded. Native error.type remains the native category. Shared middleware errors may omit this header.", "schema": { "type": "string" } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "description": "Bound pricing requires unsupported token usage categories. No upstream dispatch or balance reservation is committed.", "headers": { "x-niu-error-code": { "schema": { "type": "string", "enum": [ "unsupported_token_pricing" ] } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Key rate, concurrency or token limit.", "headers": { "x-niu-error-code": { "description": "Niu-specific machine-readable reason, such as key_spending_limit_exceeded or budget_exceeded. Native error.type remains the native category. Shared middleware errors may omit this header.", "schema": { "type": "string" } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "501": { "description": "Unsupported streaming, version or capability.", "headers": { "x-niu-error-code": { "description": "Niu-specific machine-readable reason, such as key_spending_limit_exceeded or budget_exceeded. Native error.type remains the native category. Shared middleware errors may omit this header.", "schema": { "type": "string" } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "502": { "description": "Upstream failure or invalid response; execution may be uncertain.", "headers": { "x-niu-error-code": { "description": "Niu-specific machine-readable reason, such as key_spending_limit_exceeded or budget_exceeded. Native error.type remains the native category. Shared middleware errors may omit this header.", "schema": { "type": "string" } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "503": { "description": "Service unavailable.", "headers": { "x-niu-error-code": { "description": "Niu-specific machine-readable reason, such as key_spending_limit_exceeded or budget_exceeded. Native error.type remains the native category. Shared middleware errors may omit this header.", "schema": { "type": "string" } }, "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } } }, "tags": [ "Messages and GenerateContent" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/v1/responses": { "post": { "operationId": "createResponse", "summary": "Create a text response", "description": "The route must be an OpenAI-compatible provider route with supports_responses enabled. This public subset accepts a single text input and optional text instructions, output limit, sampling values, metadata and user identifier. Text streaming returns Responses SSE events and preserves terminal reported usage. Local buffered_full output rules retain real text streams until a validated terminal response and complete inspection, then emit compatible filtered lifecycle events. Withheld output emits a safe guardrail_output_withheld SSE error without a successful terminal event; known execution is still charged. Complete text and total input stream bounds are 1 MiB and 2 MiB, with four concurrent collectors per process. Observation-only text streaming preserves delivery and asynchronously records clear, matched or indeterminate without transforming output. Required and observation rules can compose across workspace/key policies; optional collection/inspection pressure does not block the request. Each Responses event is bounded to 16 MiB of UTF-8 bytes because terminal events repeat the full output; Chat events retain their separate 64 KiB bound. Oversized or malformed events fail the stream without inventing usage. Multimodal input, tools, prior-response state and other fields are rejected. HTTP 200 at stream start does not establish completion; inspect the terminal response event. Workspace model grants, source policy, rate/concurrency/token limits and configured billing apply. Canonical OpenRouter pools permit at most one different-credential successor after an immediate authentication refusal with durable nonexecution, released holds and no prior charge. The operation retains its original tariff, funding and shared deadline under a Responses-specific retry policy. No retry follows uncertainty or a stream already returned to the client.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "x-niu-log-payloads", "in": "header", "required": false, "description": "Request and sanitized customer response content is retained until 24 hours after the original request creation time by default. Send false (case-insensitive) to disable capture for this request; true or an omitted header retains content. Invalid values or repeated headers are rejected before inference. Requests exceeding the 1 MB capture limit are rejected; response capture is truncated at 1 MB. Does not backfill earlier requests.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" } }, { "name": "X-Niu-Task-ID", "in": "header", "required": false, "description": "Optional opaque task correlation key. Requests with the same value can be grouped in workspace activity. Niu stores the value as metadata and does not forward it to the provider.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]{1,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "input" ], "properties": { "model": { "type": "string", "minLength": 1 }, "input": { "type": "string", "minLength": 1 }, "instructions": { "type": "string" }, "max_output_tokens": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "metadata": { "type": "object", "maxProperties": 16, "additionalProperties": { "type": "string", "maxLength": 512 } }, "user": { "type": "string", "maxLength": 512 }, "stream": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "A validated Responses API text response with the public model alias.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "status", "model", "output" ], "properties": { "id": { "type": "string", "minLength": 1 }, "object": { "type": "string", "const": "response" }, "status": { "type": "string", "enum": [ "completed", "incomplete" ] }, "model": { "type": "string" }, "output": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "required": [ "type", "role", "content" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "message" }, "role": { "type": "string", "const": "assistant" }, "status": { "type": "string" }, "content": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "output_text" }, "text": { "type": "string" }, "annotations": { "type": "array", "items": { "type": "object" } } }, "additionalProperties": true }, { "type": "object", "required": [ "type", "refusal" ], "properties": { "type": { "type": "string", "const": "refusal" }, "refusal": { "type": "string" } }, "additionalProperties": true } ] } } }, "additionalProperties": true }, { "type": "object", "required": [ "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "reasoning" }, "summary": { "type": "array" }, "encrypted_content": { "type": "string" } }, "additionalProperties": true } ] } }, "usage": { "type": "object", "required": [ "input_tokens", "output_tokens" ], "properties": { "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } }, "additionalProperties": true } }, "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid body, unsupported field or invalid request shape.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Missing or invalid gateway credentials.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "402": { "description": "Insufficient balance or spending limit exceeded.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "Source IP or enforced policy denies the request. Recorded preparation-policy refusals use error.type guardrail_denied before model dispatch; post-dispatch output withholding uses guardrail_output_withheld and generation charges may apply. Do not classify every 403 as a Guardrail refusal.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "Model alias does not exist or is unavailable to this key.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "description": "Admission conflict before dispatch. Type route_configuration_changed identifies a changed managed credential/model configuration; that request was not sent upstream. Other conflicts retain their own error type.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "413": { "description": "Request body exceeds 1 MiB; rejected before inference whether payload capture is enabled or disabled. Framework responses may use a plain-text body.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "description": "Invalid JSON or unsupported token admission/pricing requirements. Responses reads explicit input_tokens_details.cache_write_tokens alongside cache reads and reasoning output; missing categories remain unknown. Separate rates for unavailable categories in a bound base or reachable tier schedule return unsupported_token_pricing before dispatch or reservation commits.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "API key request, concurrency or token rate limit exceeded.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "501": { "description": "Responses support is disabled, the route protocol is unsupported, or the requested feature is unsupported. The unsupported_operation_error message identifies the limitation and supported alternative before admission.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "502": { "description": "Provider request failed or returned an invalid text response. Valid terminal usage is retained for accounting even when output delivery is rejected; an HTTP error alone does not prove nonexecution or authorize a safe retry.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } }, "503": { "description": "Durable storage or configured route unavailable.", "headers": { "x-niu-attempt-id": { "description": "Niu attempt UUID, available once an attempt has been dispatched. Use this reference with GET /v1/generations/{id}; it is distinct from an upstream response ID. May be absent on early rejection.", "schema": { "type": "string", "format": "uuid" } }, "x-niu-operation-id": { "description": "Niu operation UUID grouping the request execution. Distinct from the attempt UUID; may be absent before dispatch.", "schema": { "type": "string", "format": "uuid" } } } } }, "x-niu-status": "Text-only subset on explicitly configured OpenAI-compatible routes. Streaming requires a completed or incomplete response terminal event; disconnects retain uncertainty. Tool, multimodal and stateful conversation semantics are not implemented.", "x-niu-implementation": "implemented", "tags": [ "Responses" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/media/asset-operation-models": { "get": { "operationId": "listHistoricalWorkspaceProviderAssetModels", "summary": "Discover saved native-operation model contexts", "description": "Requires current workspace Read permission. Lists distinct recorded public model aliases for the original scoped key, including expired or revoked keys and deleted resources. Never consults current model grants, restores inference authority, selects a Provider account or calls upstream. Each alias may have several saved account bindings; it grants historical inspection only. Alias pagination is lexical and includes all recorded operation statuses.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "description": "Workspace under the legacy API field name.", "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Recorded aliases and exclusive lexical continuation cursor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "string" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid filters." }, "401": { "description": "Authentication required." }, "403": { "description": "Workspace Read permission required." }, "409": { "description": "Original key does not belong to this workspace." } }, "x-niu-implementation": "implemented", "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/models": { "get": { "operationId": "adminListModels", "summary": "List configured model routes", "description": "Company-scoped member sessions automatically include their own enabled personal models. Installation administrators may select a company with organization_id; without it only shared models are returned. Supply project_id to select an authorized workspace and resolve its effective customer selling prices. Without workspace scope customer_pricing is null; null is not a zero price and does not establish whether a workspace has a configured tariff. Personal routes also have null customer_pricing because they do not incur a Niu customer tariff. Model metadata and prices are advisory and do not qualify paid execution. Member responses omit Provider mappings, upstream names, procurement prices and credentials. Installation responses additionally include configured Provider and upstream model mappings and expose capability flags at the row root.", "parameters": [ { "name": "organization_id", "in": "query", "required": false, "description": "Company scope. Member sessions default to their own company; installation administrators must provide this when selecting a workspace.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": false, "description": "Workspace scope under the legacy API field name. Must belong to the selected company and authenticated member scope. Enables effective workspace customer pricing; it does not grant access to that workspace.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Authorized model metadata. Member and installation projections differ; customer_pricing contains customer selling rates only.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/MemberModelMetadata" }, { "$ref": "#/components/schemas/InstallationModelMetadata" } ] } } } } } } }, "401": { "description": "Missing or invalid administrator credentials." }, "404": { "description": "Selected account is outside the authenticated scope." } }, "tags": [ "Model discovery" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/routing-registry": { "get": { "operationId": "getRoutingRegistryStatus", "summary": "Read the active routing generation", "description": "Platform administrators can read the active immutable routing generation for diagnostics and an explicit static-configuration replacement. No definitions, endpoints, credential references, secrets or purchase prices are returned. local_static_configuration_matches is false on a Gateway whose local static configuration has been superseded; new inference on that instance fails closed until it restarts with matching configuration. The response is not cached.", "tags": [ "Model routing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Active publication status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "generation", "format_version", "local_static_configuration_matches" ], "properties": { "generation": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "format_version": { "type": "integer", "enum": [ 1 ] }, "local_static_configuration_matches": { "type": "boolean" } } } } } } } }, "401": { "description": "Missing or invalid authorization" }, "403": { "description": "Platform administration is required" }, "503": { "description": "Publication is unavailable or its format is unsupported" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/vendors": { "get": { "operationId": "listVendors", "parameters": [ { "name": "supplier", "in": "query", "required": false, "description": "Filter by explicit Provider business ownership; no name matching or unassociated fallback. Platform administration is required. A missing or deleted Provider returns 404; an active Provider without configurations returns an empty data array.", "schema": { "type": "string", "format": "uuid" } } ], "summary": "List Provider API-key configurations without credentials", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Vendor metadata. All management responses use Cache-Control no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_Vendor" } } } } } } }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Platform administration permission required." }, "404": { "description": "Selected Provider does not exist or has been deleted." } }, "x-niu-implementation": "implemented", "description": "Returns every matching configuration, including disabled configurations, in one data array. Optional Provider filtering uses explicit business ownership. No pagination or silent row cap; response memory grows with list size. Requires installation administration or an explicitly granted platform administrator. Each configuration has independent credentials and model bindings. Credentials are write-only and never returned.", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "operationId": "createVendor", "summary": "Create an encrypted Provider API-key configuration", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VendorCreate" } } } }, "responses": { "201": { "description": "Created vendor metadata wrapped in data. The credential is never returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_Vendor" } } } } } }, "400": { "description": "Invalid vendor configuration." }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Platform administration permission required." }, "409": { "description": "Vendor name already exists." }, "503": { "description": "Storage or credential encryption unavailable." } }, "parameters": [], "x-niu-implementation": "implemented", "description": " Requires installation administration or an explicitly granted platform administrator. Each configuration has independent credentials and model bindings. Credentials are write-only and never returned.", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}": { "put": { "operationId": "updateVendor", "summary": "Update one Provider API-key configuration or rotate its credential", "description": "Adapter is immutable. Changes affect new requests; already dispatched work can finish using its original configuration. Requires installation administration or an explicitly granted platform administrator. Each configuration has independent credentials and model bindings. Credentials are write-only and never returned.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VendorUpdate" } } } }, "responses": { "200": { "description": "Updated vendor metadata wrapped in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_Vendor" } } } } } }, "400": { "description": "Invalid configuration or credential." }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Platform administration permission required." }, "404": { "description": "Vendor does not exist." }, "409": { "description": "Stale revision or conflicting name." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getAssetManagementConfiguration", "summary": "Read installation asset-management configuration metadata", "description": "Installation administrator only. Returns no Access Key, secret or ciphertext. Configuration does not enable asset dispatch.", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Latest metadata, or null before setup. Cache-Control no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/AssetManagementConfiguration" }, { "type": "null" } ] } } } } } }, "403": { "description": "Installation administrator required." }, "404": { "description": "Credential configuration not found." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "put": { "operationId": "configureAssetManagement", "summary": "Save an encrypted asset-management credential revision", "description": "Installation administrator only. Direct Beijing Ark account required. Separate encryption binds the exact configuration, management revision and upstream project. Stale management or concurrently changed vendor revisions conflict. No upstream call, entitlement verification or dispatch activation occurs. Request body is limited to 16 KiB. Retention, revocation and lifecycle activation remain unqualified.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "upstream_project", "access_key", "secret_key" ], "properties": { "expected_revision": { "type": "integer", "minimum": 0, "maximum": 9223372036854776000 }, "upstream_project": { "type": "string", "minLength": 1, "maxLength": 1024 }, "access_key": { "type": "string", "minLength": 1, "maxLength": 256, "writeOnly": true }, "secret_key": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true } } } } } }, "responses": { "200": { "description": "Saved configuration metadata only; no dispatch activation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssetManagementConfiguration" } } } } } }, "400": { "description": "Invalid configuration or unavailable encryption." }, "403": { "description": "Installation administrator required." }, "404": { "description": "Credential configuration not found." }, "409": { "description": "Stale management or changed vendor revision." }, "413": { "description": "Request exceeds the configured body limit." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "delete": { "operationId": "revokeAssetManagement", "summary": "Revoke locally saved asset-management credentials", "description": "Installation administrator only. The expected management revision must match the latest configuration. Revocation blocks internal reads through that revision. Optional erasure removes ciphertext from the active database only and requires confirm_erase=true; immutable metadata and audit events remain. Exact repeat requests do not duplicate audit events. This does not revoke Access Keys at Ark or erase backups, and does not affect inference bearer credentials.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "erase_history": { "type": "boolean", "default": false }, "confirm_erase": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Local revocation applied. erased_revisions counts ciphertext rows erased by this call, and is zero on a repeat.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision", "configured", "dispatch_available", "erased_revisions" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "configured": { "type": "boolean", "const": false }, "dispatch_available": { "type": "boolean", "const": false }, "erased_revisions": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid input or missing erasure confirmation." }, "403": { "description": "Installation administrator required." }, "409": { "description": "Missing configuration or stale revision." }, "413": { "description": "Request body exceeds 16 KiB." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/lookups": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "summary": "Look up one asset from a retained original-group listing", "description": "Platform administrator only. Requires current original ListAssets and separate GetAsset grants. Accepts a retained listing and zero-based item position, never an upstream identity or URL. Claims lookup_id once before egress. Four lookups execute concurrently without a queue; claimed work persists after caller disconnect. Fixed signed transport is bounded to 1 MiB and 30 seconds, with a 35-second outer deadline. No retries or billing mutation. Returns operational status only; a validated snapshot is separately encrypted for 24 hours and recovered through the saved-result endpoint. Successful transport may observe a Failed or Processing asset and never grants readiness or reuse rights.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id", "listing_id", "lookup_id", "item_index" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "listing_id": { "type": "string", "format": "uuid" }, "lookup_id": { "type": "string", "format": "uuid" }, "item_index": { "type": "integer", "minimum": 0, "maximum": 99 } } } } } }, "responses": { "200": { "description": "Safe observed status; Cache-Control no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "lookup_id", "status", "asset_status" ], "properties": { "lookup_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded" ] }, "asset_status": { "type": "string", "enum": [ "Active", "Processing", "Failed" ] } } } } } } } }, "400": { "description": "Invalid item position." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "409": { "description": "Scope, grant, retained page or item unavailable, or lookup identity already claimed." }, "422": { "description": "Unsupported request fields or shape." }, "503": { "description": "Capacity exhausted or safe transport/persistence failure." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "summary": "List durable asset lookup audit history", "description": "Platform administrator only. Safe operational metadata survives grant revocation and source erasure. Missing completion remains unresolved. No asset content, upstream identities, credentials or commercial amounts. Scoped cursor and newest-first ordering; no upstream call.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Operational history; Cache-Control no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/OrdinaryAssetLookupAudit" } } } } } } }, "400": { "description": "Invalid limit or query." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/lookups/{lookup}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lookup", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Recover one encrypted asset lookup result", "description": "Platform administrator only. Requires exact original grants/account/credentials and unexpired retained content. Authenticated workspace/lookup context; safe validated asset fields only. No upstream request, URL, upstream identity, raw error or billing mutation. Cache-Control no-store. Source listing and lookup results have independent retention domains.", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Safe retained lookup details.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrdinaryAssetLookupResult" } } } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Missing, expired, erased, revoked or out-of-scope result." }, "503": { "description": "Safe decryption or validation failure." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "delete": { "summary": "Erase retained asset lookup content", "description": "Platform administrator only. Scoped erasure remains available after grant revocation. An in-flight completion cannot resurrect content. Immutable operational audit survives. No upstream request or billing mutation.", "security": [ { "adminBearerAuth": [] } ], "responses": { "204": { "description": "Erasure applied idempotently for this scope." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/listings": { "get": { "summary": "List scoped ordinary asset-listing outcomes and timing", "description": "Platform administrator only. Durable audit metadata survives page-content deletion and grant revocation. No upstream request, credential release or billing mutation. Unresolved means no durable outcome, not running work or replay permission. Durations measure gateway execution; no Provider queue/run intervals or complete inventory are inferred. Upstream identities, cursors, descriptive content and procurement data are excluded. Stable newest-first cursor pagination, Cache-Control no-store.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Previous next_cursor; unknown or out-of-scope cursors return an empty page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Bounded operational audit history.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/OrdinaryAssetListingAudit" } } } } } } }, "400": { "description": "Invalid limit or query." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "summary": "List one bounded page of assets in a saved ordinary group", "description": "Platform administrator only. Requires a separate current ListAssets grant and the successful group's original workspace/account/credential binding. Claims listing_id once before dispatch; duplicates never replay. Four listings can execute concurrently, with 30-second transport and 35-second outer transport deadlines. Claimed work persists after caller disconnect. Validated snapshots are encrypted for 24 hours and recovered without another upstream call. Responses omit upstream identities, URLs, cursors and raw errors; Active is an observation, not reuse authorization. Optional previous_listing_id continues a retained parent through its exact original grant, with unchanged scope and page size. Each parent permits one child; chains are bounded to 100 pages. Raw cursors are never accepted. has_more never proves a complete inventory. No billing mutation.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id", "intent_id", "listing_id", "maximum_items" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" }, "listing_id": { "type": "string", "format": "uuid" }, "maximum_items": { "type": "integer", "minimum": 1, "maximum": 100 }, "previous_listing_id": { "type": "string", "format": "uuid", "description": "Retained parent listing to continue; omit for the first page." } } } } } }, "responses": { "200": { "description": "Retained validated page; Cache-Control no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrdinaryAssetListingResponse" } } } }, "400": { "description": "Invalid or changed page size." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required or current access revoked." }, "404": { "description": "Group missing or outside the exact scope." }, "409": { "description": "Qualification missing, identity already claimed, parent already continued or terminal, scope mismatch, or 100-page chain exhausted." }, "422": { "description": "Invalid or unsupported request fields." }, "503": { "description": "Capacity exhausted or safe transport/persistence failure." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/listings/{listing}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "listing", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Recover a retained ordinary asset listing locally", "description": "Platform administrator only; exact original qualification and account/credential binding must remain current. No upstream call. Pending, failed, missing, deleted, expired and revoked results are unavailable. Successful response is no-store.", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Retained validated page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrdinaryAssetListingResponse" } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Retained page unavailable." }, "503": { "description": "Retained page cannot be decoded." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "delete": { "summary": "Erase retained ordinary asset listing content", "description": "Platform administrator only. Local idempotent erasure and immutable tombstone; preserves audit and upstream assets. Also prevents in-flight work from retaining late content. Does not require a still-valid operation grant.", "security": [ { "adminBearerAuth": [] } ], "responses": { "204": { "description": "Scoped content absent or erased." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/group-reads": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "List scoped ordinary group-read outcomes and timing", "description": "Platform administrator only. Audit metadata without descriptive content or upstream identities. Newest claim first, stable chronological cursor pagination. Unresolved means no durable outcome, not proof that work is still running. Duration is measured gateway execution time; no Provider queue or processing intervals are inferred. Audit remains after result deletion or grant revocation. No upstream request or automatic retry occurs. Responses use Cache-Control no-store.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Previous page next_cursor; missing or out-of-scope cursors produce an empty page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Bounded outcome history.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "items": { "type": "object", "required": [ "read_id", "status", "started_at", "completed_at", "duration_ms", "reason" ], "properties": { "read_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "unresolved", "succeeded", "failed" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "reason": { "type": [ "string", "null" ], "enum": [ null, "invalid_configuration", "destination_rejected", "unavailable", "transport", "timeout", "response_limit", "invalid_response" ] } } } } } } } } }, "400": { "description": "Invalid limit." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "summary": "Read a saved ordinary asset group using its original account", "description": "Platform administrator only. Requires a successful saved group and a separate current GetAssetGroup grant bound to its original workspace, account and credential revisions. Commits a one-shot read claim before dispatch. Four reads may execute concurrently, with a 30-second transport deadline and 35-second outer deadline. Caller disconnection does not cancel claimed work or its durable outcome audit. Reusing a read_id conflicts and never resends. This does not establish asset readiness or change billing. Descriptive results are returned only after outcome persistence and a fresh platform-access and operation-qualification check; successful descriptive results are encrypted for 24 hours and can be recovered through the scoped GET endpoint until expiry, deletion or access revocation. No upstream identities or signed URLs are returned.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id", "intent_id", "read_id" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "description": "Workspace routing identifier." }, "intent_id": { "type": "string", "format": "uuid", "description": "Saved successful group creation identifier." }, "read_id": { "type": "string", "format": "uuid", "description": "Fresh one-shot read identifier." } } } } } }, "responses": { "200": { "description": "Validated descriptive result; Cache-Control is no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "read_id", "name", "description", "created_at", "updated_at" ], "properties": { "read_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Saved group absent from the specified workspace or account." }, "409": { "description": "Read already claimed or original operation qualification unavailable." }, "503": { "description": "Read capacity, credentials, transport or outcome persistence unavailable; no automatic retry." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/group-reads/{read}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "read", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace routing identifier." } ], "get": { "summary": "Recover an encrypted ordinary group read result", "description": "Platform administrator only. No upstream request. Requires the original read grant, account and credential revisions to remain current. Returns only retained descriptive fields, with Cache-Control no-store; absent, pending, failed, expired, deleted or revoked results return 404. Retention is 24 hours from completion. Backup retention remains an operational responsibility.", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Retained descriptive result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "read_id", "name", "description", "created_at", "updated_at" ], "properties": { "read_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "No currently authorized retained result." }, "503": { "description": "Decryption or storage unavailable." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "delete": { "summary": "Erase retained group-read content", "description": "Platform administrator only. Idempotent scoped erasure. Records a deletion even during an in-flight read so later completion cannot restore content. Does not delete the upstream group or immutable audit. Content erasure remains available after read grant revocation.", "security": [ { "adminBearerAuth": [] } ], "responses": { "204": { "description": "Content erased, already absent or outside the supplied scope." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/group-updates/{update}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "update", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "summary": "Erase retained metadata-update patch", "description": "Platform administrator only, exact saved workspace/account binding. Idempotent erasure, including after grant revocation. Preserves immutable audit, claims, holds and reconciliation. Does not cancel an already claimed mutation, release a hold or restore replay permission. Responses are no-store.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Patch erased or already absent." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Update unavailable in this account and workspace." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/group-updates/{update}/reconcile": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "update", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "summary": "Read back and reconcile an acknowledged ordinary-group update", "description": "Platform administrator only. Requires an acknowledged held update, retained patch and distinct current GetAssetGroup permission for the original account. First attempts reconciliation from the retained successful bound read with the supplied read_id, without another upstream call. Otherwise claims a fresh one-shot read, uses the bounded group-read worker and persists its encrypted result. Authenticates both snapshots and compares the exact patch before atomically recording reconciliation and releasing the hold. Mismatch preserves the hold; uncertain or already reconciled updates never dispatch a read. No mutation replay or inference charge. Caller disconnect leaves tracked work running. Process recovery remains separately qualified.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id", "read_id" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "read_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "data contains update_id, status reconciled and reconciliation_required false." }, "400": { "description": "Snapshot invalid or requested metadata does not match; hold preserved." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform access or read permission unavailable." }, "404": { "description": "Update unavailable in this account and workspace." }, "409": { "description": "Read identity consumed, content unavailable, update not acknowledged/held or original qualification unavailable." }, "422": { "description": "Malformed request." }, "503": { "description": "Read capacity, encryption, transport or durable persistence unavailable." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/group-updates/{update}/dispatch": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "update", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "summary": "Dispatch a prepared ordinary-group metadata update once", "description": "Platform administrator only. Requires the exact saved workspace/account binding, retained authenticated patch and current original update qualification. Commits claim and group hold before credential release. Four execution slots, 30-second transport and 35-second outer deadline. Caller disconnect does not cancel the tracked worker. No replay or automatic retries; process loss leaves unresolved work. Acknowledgement is not read-back verification. Unacknowledged attempts remain uncertain and held, never falsely failed. No inference charge or automatic hold release.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "First outcome persisted. Uncertain does not prove the mutation was not applied.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "update_id", "status", "reconciliation_required" ], "properties": { "update_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "acknowledged", "uncertain" ] }, "reconciliation_required": { "const": true } } } } } } } }, "400": { "description": "Invalid authenticated patch." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Update unavailable in this account and workspace." }, "409": { "description": "Update already claimed, content unavailable, qualification revoked or group held." }, "422": { "description": "Malformed scope." }, "503": { "description": "Execution capacity, encryption or durable completion unavailable; never automatically retry a claimed update." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/group-updates": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Retrieve scoped metadata-update audit history", "description": "Platform administrator only. No patch metadata, upstream identities, credentials or commercial amounts. Newest prepared identity first with stable cursor pagination. Audit survives erasure and revocation. Unresolved is missing completion evidence, not proof of active work. Responses are no-store.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Safe history and next_cursor; out-of-scope cursors return an empty page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "items": { "type": "object", "required": [ "update_id", "intent_id", "status", "created_at", "completed_at", "duration_ms", "reason", "patch_status", "reconciliation_required" ], "properties": { "update_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "prepared", "unresolved", "acknowledged", "uncertain", "reconciled" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "reason": { "type": [ "string", "null" ] }, "patch_status": { "type": "string", "enum": [ "retained", "erased", "expired" ] }, "reconciliation_required": { "type": "boolean" } } } } } } } } }, "400": { "description": "Invalid limit." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "summary": "Prepare an encrypted metadata patch for a saved ordinary group", "description": "Platform administrator only. Requires a successful saved group and current distinct UpdateAssetGroup qualification. Derives the original upstream identity from storage. Saves immutable update identity and digest with an encrypted 24-hour patch. Same update identity and patch is idempotent; changed patch conflicts. Does not dispatch, claim completion, release a hold or charge inference. Explicit empty description is retained; omit a field to leave it unchanged.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id", "intent_id", "update_id" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" }, "update_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "maxLength": 300 } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "description" ] } ] } } } }, "responses": { "200": { "description": "Identical preparation already exists; no overwrite or upstream dispatch." }, "201": { "description": "Encrypted patch prepared; data contains update_id, prepared true and dispatch_available." }, "400": { "description": "Invalid metadata or empty patch." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Saved original group is unavailable in this scope." }, "409": { "description": "Qualification unavailable or changed patch conflicts." }, "422": { "description": "Malformed request." }, "503": { "description": "Encryption unavailable." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/groups": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "createOrdinaryAssetGroup", "summary": "Create an ordinary asset group through platform administration", "description": "Platform administrator only. Persists the ordinary AIGC request and requires exact, unexpired workspace/account qualification before releasing credentials. Uses the fixed direct Beijing Ark CreateAssetGroup operation once, with a fresh UTC signature and a 30-second transport deadline. Four sends may run concurrently. Accepted work continues independently of the HTTP response and participates in graceful drain. Exact saved dispatching, uncertain and succeeded requests return status without acquiring dispatch capacity or decrypting keys, including after credential erasure. They never replay automatically; inspect the workspace asset-group request instead. Customer asset routing, CRUD/readiness, live entitlement and free-operation qualification remain pending. The legacy dispatch_available metadata flag describes the complete customer asset workflow and remains false. Request body is limited to 16 KiB.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrdinaryAssetGroupInput" } } } }, "responses": { "202": { "description": "One-shot work accepted, or saved status for an identical previously claimed request. This is not proof the upstream group exists.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Saved request routing identifier; never a display label." }, "status": { "type": "string", "enum": [ "dispatching", "uncertain", "succeeded" ] } } } } } } } }, "400": { "description": "Invalid ordinary name, description or revisions." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Workspace does not belong to the specified organization." }, "409": { "description": "Missing or changed qualification/credentials/account, conflicting idempotency binding, or a concurrent claim. No automatic replay is permitted." }, "413": { "description": "Request body exceeds 16 KiB." }, "422": { "description": "Invalid shape or unknown fields." }, "503": { "description": "Asset management capacity or encrypted credentials unavailable. No send was admitted by this request." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/group-deletion-consents": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "prepareOrdinaryAssetGroupDeletionConsent", "summary": "Record specific cascading-deletion consent without dispatch", "description": "Platform administrator only. Requires explicit irreversible cascading confirmation for a successful saved ordinary group and its exact current DeleteAssetGroup qualification. Consent is immutable, actor-bound and limited to 900 seconds or the grant expiry, whichever is earlier. Identical replay does not renew expiry; changed, expired or revoked consent conflicts. No upstream deletion, credential release or billing mutation. Body is limited to 4096 bytes.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id", "intent_id", "consent_id", "authorization_id", "valid_for_seconds", "confirm_cascade" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "intent_id": { "type": "string", "format": "uuid" }, "consent_id": { "type": "string", "format": "uuid" }, "authorization_id": { "type": "string", "format": "uuid" }, "valid_for_seconds": { "type": "integer", "minimum": 1, "maximum": 900 }, "confirm_cascade": { "type": "boolean", "const": true } } } } } }, "responses": { "200": { "description": "Identical unexpired consent retained without renewal.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "consent_id", "prepared", "dispatch_available" ], "properties": { "consent_id": { "type": "string", "format": "uuid" }, "prepared": { "type": "boolean", "const": true }, "dispatch_available": { "type": "boolean", "const": false } } } } } } } }, "201": { "description": "Consent recorded; no upstream dispatch.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "consent_id", "prepared", "dispatch_available" ], "properties": { "consent_id": { "type": "string", "format": "uuid" }, "prepared": { "type": "boolean", "const": true }, "dispatch_available": { "type": "boolean", "const": false } } } } } } } }, "400": { "description": "Cascading confirmation missing or validity outside bounds." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Original group not found in the specified workspace and Provider configuration." }, "409": { "description": "Group or qualification unavailable, stale binding, or conflicting/expired/revoked consent." }, "413": { "description": "Request exceeds 4096 bytes." }, "422": { "description": "Invalid request shape or unknown fields." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/group-deletion-consents/{consent}/dispatch": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "consent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "dispatchOrdinaryAssetGroupDeletion", "summary": "Dispatch one irreversible ordinary-group cascading deletion", "description": "Platform administrator only. Requires separately saved explicit consent and a current exact DeleteAssetGroup grant. Rechecks original credential/configuration binding, expiry, revocation and mutation holds before committing a one-shot claim. Uses the fixed signed Ark endpoint without retries. A disconnected client does not cancel the bounded worker. Unacknowledged responses remain uncertain; neither outcome proves independent absence, releases the mutation fence or permits replay. No customer charge. Cache-Control no-store.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Durable acknowledged or uncertain outcome; independent reconciliation remains required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "consent_id", "status", "reconciliation_required" ], "properties": { "consent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "acknowledged", "uncertain" ] }, "reconciliation_required": { "type": "boolean", "const": true } } } } } } } }, "400": { "description": "Invalid scope." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Consent does not belong to this workspace and Provider configuration." }, "409": { "description": "Ineligible or consumed consent, stale qualification or outstanding mutation hold." }, "413": { "description": "Request exceeds 4096 bytes." }, "422": { "description": "Invalid shape or unknown fields." }, "503": { "description": "Execution capacity, credential decryption or durable outcome unavailable. Read saved status; do not automatically retry." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/group-deletion-consents/{consent}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "consent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "organization_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getOrdinaryAssetGroupDeletionConsent", "summary": "Read safe local consent and outcome status", "description": "Platform administrator only. Scoped to the original workspace and Provider configuration. Returns no upstream identities, credentials, grant evidence or procurement data. Consent status alone is not current dispatch authorization. Claimed/outcome state takes precedence over later consent revocation or expiry. Does not query upstream. Cache-Control no-store.", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Saved local consent status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "created_at", "expires_at", "reason", "duration_ms", "dispatch_available" ], "properties": { "status": { "type": "string", "enum": [ "consented", "revoked", "expired", "unresolved", "acknowledged", "uncertain" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "reason": { "type": [ "string", "null" ], "enum": [ "invalid_configuration", "destination_rejected", "unavailable", "transport", "timeout", "response_limit", "invalid_response", null ] }, "duration_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "dispatch_available": { "type": "boolean", "const": false } } } } } } } }, "400": { "description": "Invalid scope." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Consent not found in the specified scope." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "delete": { "operationId": "revokeOrdinaryAssetGroupDeletionConsent", "summary": "Revoke local deletion consent without erasing history", "description": "Platform administrator only. Idempotent and scoped; absent or mismatched records return 204 without changes. Does not delete an upstream group, erase claims/outcomes, cancel already dispatched work or restore consumed consent. Future claims must recheck revocation. No billing mutation.", "security": [ { "adminBearerAuth": [] } ], "responses": { "204": { "description": "Consent revoked or no matching consent." }, "400": { "description": "Invalid scope." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/authorizations": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "createAssetOperationAuthorization", "summary": "Record administrator-reviewed ordinary asset qualification", "description": "Platform administrator only. Binds the exact workspace, direct Beijing Ark configuration revision and asset credential revision. The four nonzero SHA-256 references identify reviewed rights, protocol, data-handling and free-operation evidence; they do not establish entitlement automatically. Validity is bounded to 90 days. CreateAsset requires separate ingestion review and does not establish processing consent or exact inspected-content binding. DeleteAssetGroup requires its own reviewed grant and never inherits creation/read/update rights; it does not establish destructive user consent. Does not send upstream requests or enable dispatch. Request body is limited to 16 KiB.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetOperationAuthorizationInput" } } } }, "responses": { "201": { "description": "Immutable qualification recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "operation", "dispatch_available" ], "properties": { "id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": [ "CreateAssetGroup", "GetAssetGroup", "ListAssets", "GetAsset", "UpdateAssetGroup", "DeleteAssetGroup", "CreateAsset" ] }, "dispatch_available": { "type": "boolean", "const": false } } } } } } } }, "400": { "description": "Invalid revisions, validity or evidence references." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." }, "404": { "description": "Workspace does not belong to the specified organization." }, "409": { "description": "Account revision changed, account is not direct Ark, or asset credentials are missing or revoked." }, "413": { "description": "Request body exceeds 16 KiB." }, "422": { "description": "Invalid request shape or unknown fields." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "get": { "operationId": "listAssetOperationAuthorizations", "summary": "List one account's qualification records", "description": "Platform administrator only. Administrative evidence references and account bindings must not appear in customer projections. Records remain visible after expiry or revocation; presence is not proof of current authorization. Cache-Control no-store.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Bounded records ordered by routing identifier, with a cursor when more exist.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetOperationAuthorization" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid limit or cursor." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/vendors/{id}/asset-management/authorizations/{authorization}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "authorization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "operationId": "revokeAssetOperationAuthorization", "summary": "Revoke one account's asset qualification", "description": "Platform administrator only. Appends an immutable actor-attributed revocation. Missing, already revoked, and mismatched-account identifiers return the same idempotent response; another account's record is never revoked. Does not delete audit records or contact upstream.", "security": [ { "adminBearerAuth": [] } ], "responses": { "204": { "description": "Local revocation applied or no matching active record." }, "401": { "description": "Authentication required." }, "403": { "description": "Platform administrator required." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/personal-owner": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "operationId": "assignPersonalCredentialOwner", "summary": "Assign a configured personal credential to its account", "description": "Installation administrator only. Ownership is immutable. Exact retries return success without another audit event. This does not activate Provider offers, grant funds or qualify commercial supply. Initial assignment rejects credentials with any model route pricing, including disabled mappings; explicitly clear those prices first. Ownership assignment and model publication serialize on the credential row.", "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "expected_revision" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "format": "int64", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Personal owner assigned or exact assignment already exists.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "assigned" ], "properties": { "assigned": { "type": "boolean", "const": true } } } } } }, "400": { "description": "Invalid assignment input." }, "401": { "description": "Authentication required." }, "403": { "description": "Installation administrator required." }, "409": { "description": "Stale revision, different owner, existing model route pricing, commercial qualification or unavailable account." } }, "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/models": { "get": { "operationId": "listVendorModels", "summary": "List model bindings for one Provider API-key configuration", "description": "Management reads include route eligibility in available and an owner_funded flag. Owner-funded routes are private to their recorded account and excluded from shared supply and the public catalog, regardless of their legacy configured public_catalog flag. Available does not establish upstream entitlement, service quality or commercial qualification. Requires installation administration or an explicitly granted platform administrator. These platform-only route prices are procurement configuration, not customer selling tariffs.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Model mappings wrapped in data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_VendorModel" } } }, "required": [ "data" ] } } } }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Platform administration permission required." }, "404": { "description": "Vendor does not exist." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "operationId": "upsertVendorModel", "summary": "Create or update a model mapping with optimistic revision checks", "description": "Omit expected_revision to create; provide the current revision to update. Aliases cannot be reassigned to another vendor. Disabled mappings still override static file aliases. Requires installation administration or an explicitly granted platform administrator. These platform-only route prices are procurement configuration, not customer selling tariffs. Omit pricing to preserve it on update; explicit null clears it. Changes do not rewrite previously pinned request prices.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_VendorModelInput" } } } }, "responses": { "200": { "description": "Persisted model mapping wrapped in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_VendorModel" } } } } } }, "400": { "description": "Invalid alias, capabilities or pricing." }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Platform administration permission required." }, "404": { "description": "Vendor does not exist." }, "409": { "description": "Stale revision, existing alias or different vendor ownership." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/catalog": { "get": { "operationId": "listProviderModelCatalog", "summary": "Discover upstream models for a Provider API-key configuration", "description": "Makes a bounded GET to the configured provider /models endpoint using the encrypted server-side credential. Anthropic uses x-api-key and anthropic-version 2023-06-01; Gemini uses x-goog-api-key and normalizes native model resource names. Both request at most 1000 models and reject an incomplete catalog rather than returning a truncated inventory. No inference request is sent. Redirects are blocked, the response body is capped at 2 MiB, and only allowlisted model IDs and catalog metadata (display name, description, context and output limits, modalities, and advertised USD token prices) are returned. Provider credentials and raw response data are never returned. Requires installation administration or an explicitly granted platform administrator. Explicit OpenRouter integrations first verify the saved credential with /key (64 KiB response bound, no identity or budget fields returned), then use /models/user?output_modalities=all; other integrations use /models. Discovery reports the effective integration and inventory scope. Catalog-read success does not verify inference, management authority, or prices. No fallback from denied credential-filtered discovery to public inventory is performed.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Provider model metadata wrapped in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "discovery" ], "properties": { "data": { "type": "array", "maxItems": 2000, "items": { "$ref": "#/components/schemas/handler_operations_json_ProviderCatalogModel" } }, "discovery": { "type": "object", "required": [ "integration", "inventory_scope", "credential_access", "inference_verified", "management_access", "prices" ], "properties": { "integration": { "type": "object", "description": "Effective integration identity, saved selection, source and revision." }, "inventory_scope": { "type": "string", "enum": [ "credential_filtered", "instance_reported" ] }, "credential_access": { "type": "string", "const": "catalog_read_succeeded" }, "inference_verified": { "type": "boolean", "const": false }, "management_access": { "type": "string", "const": "not_checked" }, "prices": { "type": "string", "const": "advertised_only" } } } } } } } }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Platform administration permission required." }, "404": { "description": "Vendor does not exist." }, "502": { "description": "Provider rejected the credential or returned an invalid catalog or request error." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "operationId": "refreshProviderCatalogMetadata", "summary": "Refresh descriptive metadata for existing vendor model mappings", "description": "Fetches the bounded provider catalog and updates matching upstream IDs only. Preserves aliases, routing, capability declarations and billing prices. Increments revisions when metadata changes. Missing provider models are retained. Requires installation administration or an explicitly granted platform administrator.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Number of updated mappings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "integer", "minimum": 0 } }, "required": [ "updated" ] } } } }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Platform administration permission required." }, "404": { "description": "Vendor does not exist." }, "409": { "description": "Configuration changed during catalog retrieval; no metadata was updated. Retry against the current configuration." }, "502": { "description": "Provider catalog unavailable or invalid." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/vendors/{id}/check": { "post": { "operationId": "checkVendorModel", "summary": "Check provider reachability and whether a mapped model is listed", "description": "Performs a bounded GET to the provider's /models endpoint. Anthropic and Gemini use native authentication headers and a 1000-model page; absence from an incomplete page remains unknown. It does not send an inference request. Redirects are blocked, response bodies are capped at 2 MiB, and provider response content and credentials are never returned. A listed model does not prove inference entitlement or quota. Requires installation administration or an explicitly granted platform administrator.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "alias" ], "properties": { "alias": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Sanitized provider check result wrapped in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "model", "http_status", "duration_ms", "checked_at_ms" ], "properties": { "status": { "type": "string", "enum": [ "connected", "credentials_rejected", "endpoint_unavailable", "private_endpoint_blocked", "invalid_endpoint", "redirect_blocked", "provider_rate_limited", "provider_error", "model_catalog_unavailable", "model_catalog_too_large", "invalid_model_catalog" ] }, "model": { "type": "string", "enum": [ "listed", "not_listed", "unknown" ] }, "http_status": { "type": [ "integer", "null" ] }, "duration_ms": { "type": "integer", "minimum": 0 }, "checked_at_ms": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid model alias." }, "401": { "description": "Invalid or expired administrative credential." }, "403": { "description": "Platform administration permission required." }, "404": { "description": "Model alias is not mapped to this vendor." }, "503": { "description": "Credential decryption or storage unavailable." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-niu-implementation": "implemented", "tags": [ "Provider API connections" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/session": { "get": { "operationId": "getAdminSessionIdentity", "summary": "Read the current administrator's scope and permissions", "description": "Revalidates the bearer credential on every request. Returns installation authority or the operator's current organization/workspace scope and role. Permissions are UI hints; every management operation independently enforces authorization. Responses contain no credentials and use Cache-Control no-store.", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Current identity and effective role permissions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "kind", "operator", "permissions", "provider_memberships" ], "properties": { "kind": { "type": "string", "enum": [ "installation", "operator" ] }, "provider_memberships": { "type": "array", "description": "Explicit active Provider grants only; installation identity returns an empty array.", "items": { "type": "object", "required": [ "id", "name", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "manager" ] } } } }, "operator": { "type": [ "object", "null" ], "required": [ "id", "role", "organization_id", "project_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "permissions": { "type": "object", "required": [ "read", "write", "manage_operators", "platform_admin" ], "properties": { "read": { "type": "boolean" }, "write": { "type": "boolean" }, "manage_operators": { "type": "boolean" }, "platform_admin": { "type": "boolean", "description": "Explicit platform administration capability; does not expand customer workspace scope." } } } } } } } } } }, "401": { "description": "Missing, invalid, expired or revoked administrator credential." }, "503": { "description": "Operator storage is unavailable." } }, "tags": [ "Authentication" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/operators": { "get": { "operationId": "adminListOperators", "summary": "List operator identities without session credentials", "description": "Requires an owner or installation administrator. Results are scoped before pagination. Installation callers may filter by organization_id; members cannot change their authorized company/workspace scope. Returns identities and roles, never session credentials. Pass next_cursor as after until null. A missing or foreign cursor returns 409. Pages are live observations ordered by creation time and identity.", "parameters": [ { "in": "query", "name": "organization_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } } ], "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Persistent operator identities and assigned roles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "role", "organization_id", "project_id", "revoked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "revoked": { "type": "boolean" } } } } } } } } }, "400": { "description": "Invalid page limit, cursor syntax or unknown query field." }, "401": { "description": "Missing, invalid, expired or revoked credentials." }, "403": { "description": "The authenticated operator is not an owner." }, "404": { "description": "Requested company is outside the member scope." }, "409": { "description": "Cursor is missing or outside the selected scope; refresh the directory." } }, "tags": [ "Users and sessions" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "operationId": "adminCreateOperator", "summary": "Create an operator and issue its first session token", "description": "Requires a permitted owner or installation administrator. Every user belongs to a company and may be workspace-scoped. By default a temporary session is issued once and expires_in_seconds is required. For recoverable onboarding, pass issue_session false with Idempotency-Key and omit expires_in_seconds. The identity and receipt commit together; matching retries return current metadata for the original identity with null session/token. Changed input, revoked or deleted identities return 409; replay never restores access or issues a credential. The receipt namespace is company-scoped, distinct from company/workspace creation. Authorization is checked before receipt lookup.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "description": "Required only for identity-only creation; 1–128 visible ASCII characters. Retain the same key and input after an uncertain outcome.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "security": [ { "adminBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorInput" } } } }, "responses": { "201": { "description": "User created or identity-only replay confirmed; session/token are null for identity-only creation. Cache-Control no-store." }, "400": { "description": "Invalid role, name or session lifetime." }, "401": { "description": "Missing, invalid, expired or revoked credentials." }, "403": { "description": "The authenticated operator is not an owner." } }, "tags": [ "Users and sessions" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/operators/{operator}": { "patch": { "operationId": "updateOperatorRole", "summary": "Change a scoped customer member role", "description": "Current scoped Owner management permission or installation administrator required. Admin and Viewer cannot manage user roles. Preserves the original member organization/workspace, credentials, sessions, session expiries and Provider memberships. Rejects self role changes, revoked/noncustomer/platform actors and role-update demotion of the last applicable active Owner. expected_role is a compare-and-set precondition; stale input returns 409 and requires reloading. Organization-scoped serialization and current actor/session validation protect the mutation transaction. A same-role request with a matching precondition returns unchanged metadata without an audit event. Changed roles apply to the original token on its next authenticated request; no replacement token or renewed session is issued. A future immutable role_changed journal records exact before/after roles and actor attribution; historical roles are never inferred. No credentials or commercial data returned.", "tags": [ "Users and sessions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "operator", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Scoped Niu user routing reference; never display as a product label." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_MemberRoleUpdate" } } } }, "responses": { "200": { "description": "Current scoped user metadata; no credential or session renewal", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MemberRoleChangeView" } } } } } }, "400": { "description": "Invalid role/input or protected customer actor" }, "401": { "description": "Invalid, expired or concurrently revoked management session" }, "403": { "description": "Manage-users permission denied or self role change" }, "404": { "description": "User outside the actor scope or not a customer user" }, "409": { "description": "Stale expected role, revoked user or last Owner protection" }, "413": { "description": "Body exceeds bounded request size" }, "503": { "description": "Storage unavailable" } }, "x-niu-implementation": "implemented", "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } }, "delete": { "operationId": "adminRevokeOperator", "summary": "Revoke an operator and all of its sessions", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "operator", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Operator and active sessions revoked." }, "401": { "description": "Missing, invalid, expired or revoked credentials." }, "403": { "description": "The authenticated operator is not an owner." }, "409": { "description": "Operator was already revoked or does not exist." } }, "tags": [ "Users and sessions" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/operators/{operator}/sessions": { "get": { "operationId": "adminListOperatorSessions", "summary": "List session expiry and revocation metadata", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "operator", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session identifiers and expiry metadata; credentials are never returned." }, "401": { "description": "Missing, invalid, expired or revoked credentials." }, "403": { "description": "The authenticated operator is not an owner." } }, "tags": [ "Users and sessions" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } }, "post": { "operationId": "adminIssueOperatorSession", "summary": "Issue an additional one-time operator session token", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "operator", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorSessionInput" } } } }, "responses": { "201": { "description": "Session created; response includes Cache-Control no-store and the token is shown once." }, "400": { "description": "Session lifetime is outside the supported range." }, "401": { "description": "Missing, invalid, expired or revoked credentials." }, "403": { "description": "The authenticated operator is not an owner." }, "409": { "description": "Operator is unavailable." } }, "tags": [ "Users and sessions" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/operators/{operator}/sessions/{session}": { "delete": { "operationId": "adminRevokeOperatorSession", "summary": "Revoke one operator session", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "operator", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Session revoked." }, "401": { "description": "Missing, invalid, expired or revoked credentials." }, "403": { "description": "The authenticated operator is not an owner." }, "409": { "description": "Session was already revoked or does not exist." } }, "tags": [ "Users and sessions" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/operators/{operator}/events": { "get": { "operationId": "adminListOperatorAuditEvents", "summary": "Read immutable operator and session lifecycle events", "description": "Requires a scoped owner for the target operator or an installation bootstrap credential. Cursor UUIDs are accepted only when they belong to the requested target operator. Events include actor class/identity and target tenant metadata, never session tokens, token hashes or request bodies.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "operator", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "UUID from next_cursor in the previous page for this same operator.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Events in stable descending created_at/id order and a nullable next_cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorAuditPage" } } } }, "400": { "description": "Page limit is outside 1–100 or cursor is absent from this operator's event stream." }, "401": { "description": "Missing, invalid, expired or revoked credentials." }, "403": { "description": "The authenticated operator is not an owner." }, "404": { "description": "Target operator is absent or outside the caller's scope." } }, "tags": [ "Users and sessions" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/metrics": { "get": { "operationId": "adminGetMetrics", "summary": "Read in-process request and token counters", "security": [ { "adminBearerAuth": [] } ], "responses": { "200": { "description": "Process-local counters keyed by instance_id and started_at_ms so multi-instance scrapers can distinguish replicas and detect counter resets on process restart. Token totals cover only complete provider-reported usage. Unknown attempts include missing or invalid usage, failures, cancellations, native adapter calls without usage provenance, and streams without trustworthy usage/termination evidence. Durable attempt evidence is stored separately; this metrics endpoint is process-local.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string", "description": "Unique process/replica identifier (configured via NIU_INSTANCE_ID or generated per process startup)." }, "started_at_ms": { "type": "integer", "format": "int64", "description": "Process startup timestamp in Unix milliseconds for counter-reset detection." }, "requests_total": { "type": "integer" }, "requests_failed": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "usage": { "type": "object", "properties": { "attempts_total": { "type": "integer" }, "attempts_unknown": { "type": "integer" }, "attempts_provider_reported": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" } } } } } } } } }, "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/workspaces/by-route/{route_slug}": { "get": { "operationId": "resolveWorkspaceRoute", "summary": "Resolve an authorized canonical workspace route", "description": "Exact persisted route lookup independent of workspace list limits. Renames preserve the route. Historical name aliases are not supported. Foreign, missing and malformed references return the same 404.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "route_slug", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 81 } } ], "responses": { "200": { "description": "Authorized workspace identity.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "name", "route_slug", "slug", "slug_aliases" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "route_slug": { "type": "string", "maxLength": 81, "description": "Deprecated compatibility alias for slug.", "deprecated": true }, "slug": { "type": "string", "maxLength": 81, "description": "Stable, readable workspace slug. Use in dashboard URLs; renaming preserves it." }, "slug_aliases": { "type": "array", "items": { "type": "string" }, "description": "Previously issued slugs accepted for existing bookmarks." } } } } } }, "401": { "description": "Invalid or inference-only credential." }, "403": { "description": "Credential lacks read permission." }, "404": { "description": "No authorized workspace matches the reference." } }, "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List an authorized page of workspaces", "description": "Requires installation or member read authorization. Member company/workspace scope is enforced server-side. Stable company/workspace creation order; renaming does not move entries. Follow next_cursor as after with unchanged credentials until null. Pages reflect live state, not a snapshot; restart traversal if a cursor workspace is deleted. UUIDs are routing identifiers, not display labels.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Last next_cursor from this authorized traversal." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } } ], "responses": { "200": { "description": "Authorized workspace page, with null next_cursor at the current end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceDirectoryEntry" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid page size, malformed cursor, or unknown query parameter." }, "401": { "description": "Missing, invalid, expired or revoked management credential." }, "403": { "description": "Credential lacks management read access." }, "409": { "description": "Cursor is missing, deleted or outside the authorized scope. Restart traversal." } }, "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } }, "post": { "operationId": "createWorkspace", "summary": "Create a workspace with retry-safe identity", "description": "Requires installation write access or a company-scoped member allowed to create workspaces, platform currency setup, and either payment readiness or a funded/granted/approved-credit arrangement for the selected company. Optional Idempotency-Key is durable and actor-scoped: identical input returns the original identity and current metadata with 201; changed input returns 409; replay after deletion returns 404 without recreation. Installation credentials share one namespace; members use their stable member identity. Without the header, each successful call creates a workspace. Current member/session authorization is rechecked after lock waits. If an installation caller omits organization_id, company, zero-funded USD account, zero approved credit, workspace and receipt commit together. No payment or funded balance is created.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "One header containing visible ASCII characters. Retain the same value and input when recovering an uncertain response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceCreationInput" } } } }, "responses": { "201": { "description": "Created or replayed workspace with its current metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceDirectoryEntry" } } } }, "400": { "description": "Invalid name, malformed JSON syntax, or invalid/repeated Idempotency-Key header." }, "401": { "description": "Missing, expired or revoked credentials, including member/session authorization lost while waiting for a lock." }, "403": { "description": "Credential does not have write access." }, "404": { "description": "Company scope is not permitted, or the workspace from the original idempotent creation has been deleted." }, "409": { "description": "The requested slug is already in use, or Idempotency-Key belongs to different creation input." }, "422": { "description": "JSON body has an unknown field, invalid field type or UUID, or is missing a required field." }, "503": { "description": "Storage unavailable; the outcome may be uncertain. Retry with the same idempotency identity and input." } }, "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } } }, "/api/v1/organizations": { "post": { "operationId": "createOrganization", "summary": "Create a company and its initial zero-funded account", "description": "Installation administrator only. Atomically creates the company and an initial account in the configured platform currency (USD for legacy installations before currency setup), with zero funding and zero approved credit. No payment or funding receipt is recorded. Paid admission still requires permitted capacity and customer pricing. Name is validated but preserved without trimming. Additional currencies need explicit account setup; no currency conversion is implied. Optional Idempotency-Key is durable in one installation-wide namespace, separate from workspace creation. Repeating the same name and resolved currency returns the original company identity and current name with 201; different input returns 409. A deleted company returns 404 without recreation. Without the header each successful call creates a company. On uncertain outcomes retry the same key and input.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Must contain non-whitespace text and fit within 200 UTF-8 bytes." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "USD" } } } } } }, "responses": { "201": { "description": "Company identity and initial account currency.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "currency" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } } } } } }, "400": { "description": "Invalid name/currency, malformed JSON syntax, or invalid/repeated Idempotency-Key header." }, "401": { "description": "Missing, invalid, expired or revoked management credential." }, "403": { "description": "Installation administrator required; company/workspace members cannot create companies." }, "404": { "description": "The company from the original idempotent creation was deleted." }, "409": { "description": "Idempotency-Key was already used with a different name or currency." }, "422": { "description": "Missing required field, unknown field, or invalid JSON field type." }, "503": { "description": "Storage unavailable; creation outcome may be uncertain." } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Exactly one visible-ASCII identity; preserve it with the original input when retrying." } ], "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "organization" } }, "get": { "operationId": "listOrganizations", "summary": "List authorized company metadata", "description": "Requires management read authorization. Member company scope is applied before paging, including workspace-scoped members. Stable creation order; renaming does not move entries. Follow next_cursor as after with unchanged credentials until null. Pages reflect live data, not a frozen snapshot; deletion of a cursor requires restarting traversal. Returns only identity/name metadata, never financial data or credentials.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "responses": { "200": { "description": "Authorized company metadata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_CompanyMetadata" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "400": { "description": "Invalid page size, cursor syntax or unknown query parameter." }, "401": { "description": "Missing, invalid, expired or revoked management credential." }, "403": { "description": "Credential lacks management read access." }, "409": { "description": "Cursor is missing, deleted or outside current company scope." } }, "parameters": [ { "in": "query", "name": "after", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } } ], "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys": { "post": { "operationId": "issueKey", "summary": "Issue a workspace API key and return its secret once", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_KeyInput" } } } }, "responses": { "201": { "description": "Issued key identity and one-time secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_IssuedWorkspaceKey" } } }, "headers": { "Cache-Control": { "description": "Secrets must not be cached.", "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid fields, model grants, name or lifetime.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } }, "text/plain": { "schema": { "type": "string", "description": "Framework path or JSON syntax rejection may use a plain-text body instead of the application error envelope." } } } }, "401": { "description": "Invalid or expired administrative credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Workspace write permission required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace outside authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "x-niu-implementation": "implemented", "description": "Requires workspace write access. Workspace API keys do not authorize these management operations. Grants must be visible model aliases, or the wildcard * as the sole grant. The token is returned only in this response. ttl_seconds is required; explicit null opts into no automatic expiration. Finite integer lifetimes retain their existing range.", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "get": { "operationId": "listKeys", "summary": "List saved workspace API-key metadata", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "required": false, "description": "Explicit limit selects paginated mode (1 to 100). With after but no limit, page size is 50. Omit both for the full compatibility directory.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "after", "required": false, "description": "Exclusive key routing reference from next_cursor. Missing or foreign-workspace cursors return 409. Each page shares one snapshot with its cursor lookup; traversal is a live view.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scoped metadata, never token hashes or secrets. Last used is the latest durable dispatch intent, including uncertain attempts; it is not authentication time or proof of upstream completion.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKey" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid", "description": "Present only when limit or after is supplied. Null when the paginated range ends. Internal routing reference, not a product label." } } } } } }, "400": { "description": "Invalid limit or cursor syntax." }, "401": { "description": "Invalid or expired administrative credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace outside authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "409": { "description": "Missing or foreign-workspace cursor." } }, "x-niu-implementation": "implemented", "description": "Requires workspace read access. Workspace API keys do not authorize these management operations. Returns the complete saved directory in creation-time/routing-reference order; this compatibility response has no continuation cursor. Storage reads use transaction-local 250 ms lock and 2 s statement limits. Timeout returns sanitized 503, never empty or truncated success; pool admission and the complete HTTP deadline are separate. Internal IDs are API routing references, not product labels. Supplying limit or after selects a bounded keyset page and adds next_cursor; without either, the complete compatibility response is unchanged.", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}": { "delete": { "operationId": "revokeKey", "summary": "Revoke a workspace API key", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Key revoked, including an already revoked key." }, "401": { "description": "Invalid or expired administrative credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Workspace write permission required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace outside authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "409": { "description": "Key does not exist in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "x-niu-implementation": "implemented", "description": "Requires workspace write access. Workspace API keys do not authorize these management operations.", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "patch": { "operationId": "updateKeyMetadata", "summary": "Update workspace API key name and model grants", "description": "Requires workspace write access. Changes the saved name and model grants without returning or rotating the secret or extending expiry. Subsequent requests use the current grants; this does not cancel already dispatched requests. expected_revision is an integer, unlike decimal-string policy revisions. A no-op edit retains its revision; a changed edit increments it. Model aliases must exist in the authorized scope. The wildcard must be the sole grant.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "allowed_models", "expected_revision" ], "properties": { "name": { "type": "string", "description": "Trimmed before persistence; must be nonempty and at most 200 UTF-8 bytes." }, "allowed_models": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Existing scoped aliases, each nonempty and at most 200 UTF-8 bytes; [\"*\"] grants all eligible models." }, "expected_revision": { "type": "integer", "format": "int64", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Current metadata revision; no secret is returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "integer", "format": "int64", "minimum": 1 } } } } } }, "400": { "description": "Invalid name, model grants or revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } }, "text/plain": { "schema": { "type": "string", "description": "Framework path or JSON syntax rejection may use a plain-text body instead of the application error envelope." } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Write permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace access not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "409": { "description": "Stale revision, missing key, revoked key or expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "422": { "description": "Invalid JSON shape, missing or unknown fields" }, "503": { "description": "Durable storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/accounts": { "get": { "operationId": "listAccounts", "summary": "List account metadata without credential references", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Account registered as unverified, or metadata returned. Registration does not activate inference." }, "401": { "description": "Invalid administrator token." } }, "tags": [ "Legacy account and cost APIs" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "post": { "operationId": "registerAccount", "summary": "Register an unverified account", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountInput" } } } }, "responses": { "201": { "description": "Account registered as unverified, or metadata returned. Registration does not activate inference." }, "401": { "description": "Invalid administrator token." } }, "tags": [ "Legacy account and cost APIs" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/keys/{key}/rotate": { "post": { "operationId": "rotateKey", "summary": "Atomically replace a key while preserving its grants and expiry", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Issued key identity and one-time secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_IssuedWorkspaceKey" } } }, "headers": { "Cache-Control": { "description": "Secrets must not be cached.", "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Invalid or expired administrative credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Workspace write permission required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace outside authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "409": { "description": "Key is absent, revoked, expired or concurrently rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "x-niu-implementation": "implemented", "description": "Requires workspace write access. Workspace API keys do not authorize these management operations. Revokes the old secret atomically. The replacement preserves grants, expiry, spending identity and configured key policies; rotation does not reset consumed allowance.", "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/budget": { "post": { "operationId": "createProjectBudget", "summary": "Create a platform upstream cost budget (installation only)", "description": "Fails with conflict if a budget exists. Previously dispatched work is not retroactively reserved. Further dispatch requires a trusted held reservation; configure pricing separately in the model route.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "currency", "limit_nanos" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "limit_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Nonnegative integer billionths of currency, at most 9223372036854775807." } } } } } }, "responses": { "201": { "description": "Created budget snapshot with decimal-string amounts and lifetime period." }, "400": { "description": "Invalid currency or amount." }, "401": { "description": "Administrator authentication required." }, "409": { "description": "Budget already exists or the workspace is absent from the organization." }, "422": { "description": "JSON does not match the required schema." } }, "tags": [ "Legacy account and cost APIs" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "get": { "operationId": "getProjectBudget", "summary": "Read the platform upstream cost budget (installation only)", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Budget data or null. limit_nanos, reserved_nanos and spent_nanos are exact decimal strings in billionths of currency. A null budget is not a zero limit." }, "400": { "description": "Invalid path or query parameter." }, "401": { "description": "Administrator authentication required." } }, "tags": [ "Legacy account and cost APIs" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/costs": { "get": { "operationId": "listProjectCosts", "summary": "Read platform upstream cost entries (installation only)", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Data and nullable next_cursor. Monetary and token values are decimal strings. API-equivalent and cash charges remain distinct. Unsettled attempts are excluded; an empty page does not prove zero incurred cost. Traversal is a live view ordered by attempt UUID, not chronological or a snapshot." }, "400": { "description": "Invalid path or query parameter." }, "401": { "description": "Administrator authentication required." } }, "tags": [ "Legacy account and cost APIs" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/requests/export": { "get": { "operationId": "exportWorkspaceRequests", "summary": "Export filtered customer-safe request metadata as CSV", "description": "Requires workspace read access. Uses one database statement for the filtered range, newest first by default, with the requested sort applied to the whole range. Excludes internal identifiers, payloads, credentials and Provider costs. Unknown values remain empty, exact quantities remain decimal text, and formula-like text is neutralized. Pagination parameters are rejected; more than 10000 matched requests fails without a partial download.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "http_status", "in": "query", "description": "Recorded delivery HTTP status, or unknown when absent; independent of Provider execution.", "schema": { "type": "string", "pattern": "^(unknown|[1-5][0-9]{2})$" } }, { "name": "sort", "in": "query", "description": "Full-range order. Known latency/token values precede unknown values; time and ID break ties. Live traversal is not a cross-page snapshot.", "schema": { "type": "string", "enum": [ "time_desc", "time_asc", "latency_desc", "input_desc", "output_desc" ], "default": "time_desc" } }, { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from_ms", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "to_ms", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "model_alias", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "operation_id", "in": "query", "description": "Restrict to one operation within the authorized workspace.", "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "recorded_failure selects persisted failure observations, including SSE errors under HTTP 200; delivery_failed retains HTTP-error semantics.", "schema": { "type": "string", "enum": [ "not_sent", "may_have_executed", "confirmed_completed", "confirmed_not_executed", "output_withheld", "delivery_failed", "recorded_failure" ] } } ], "responses": { "200": { "description": "CSV attachment with no-store caching and meaningful customer fields only. Appended Cached input tokens and Reasoning output tokens columns contain exact reported subset counts; unknown counts are blank and explicit zero remains zero. Category counts do not establish billing rates or savings.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Content-Disposition": { "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid filters or pagination parameters." }, "401": { "description": "Missing, invalid or inference-only credentials." }, "403": { "description": "Administration credential cannot read this workspace." }, "413": { "description": "More than 10000 requests match; narrow the filters." } }, "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/requests": { "get": { "operationId": "listProjectGatewayActivity", "summary": "Read automatically retained gateway request activity", "description": "Returns metadata for model attempts admitted by Niu, newest first by default, with the requested sort applied to the whole range. Request and response bodies, prompts and completions are not included. Pages are bounded to at most 100 entries. Pass the previous response's next_cursor as after to read older matching entries; traversal is a live view, not a cross-page snapshot. Optional filters apply to the whole workspace scope. summary totals cover the selected filters independent of page. Rows and summary in one response share a database snapshot. Reporting reads use a one-second database lock timeout and a five-second timeout per SQL statement. Timeout returns a sanitized 503 error, never partial results; these are not whole-request deadlines. An absent task_id means the caller did not supply X-Niu-Task-ID. Missing usage remains unknown. All workspace responses exclude Provider expenses and platform margins, including for installation administrators. Customer-facing charges and nullable observed request phase timing are included.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "http_status", "in": "query", "description": "Recorded delivery HTTP status, or unknown when absent; independent of Provider execution.", "schema": { "type": "string", "pattern": "^(unknown|[1-5][0-9]{2})$" } }, { "name": "sort", "in": "query", "description": "Full-range order. Known latency/token values precede unknown values; time and ID break ties. Live traversal is not a cross-page snapshot.", "schema": { "type": "string", "enum": [ "time_desc", "time_asc", "latency_desc", "input_desc", "output_desc" ], "default": "time_desc" } }, { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "description": "Exclusive cursor from the previous page's next_cursor; continue strictly after this attempt in the same sort order; preserve sort and filters across pages.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "from_ms", "in": "query", "description": "Inclusive creation-time lower bound as Unix epoch milliseconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "to_ms", "in": "query", "description": "Exclusive creation-time upper bound as Unix epoch milliseconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "model_alias", "in": "query", "description": "Exact public model alias filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "operation_id", "in": "query", "description": "Restrict attempts and summaries to one operation within the authorized workspace. Unknown or foreign operations yield an empty result; this does not authorize cross-workspace reads.", "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "query", "description": "Workspace API key ID filter. Matches the dispatched key or a captured requested key in saved admission-denial evidence while the attempt remains unsent. Does not change billing attribution. Key names and IDs are visible only within the authorized workspace.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Exact gateway execution state, or output_withheld for recorded blocked/indeterminate output inspection. delivery_failed selects recorded HTTP errors (400–599). recorded_failure selects persisted upstream failure observations, including errors delivered inside HTTP 200 streams, and saved Gateway admission denials while the attempt remains unsent. Missing failure observations are not inferred from execution uncertainty. Completion at the Provider does not establish successful response delivery.", "schema": { "type": "string", "enum": [ "not_sent", "may_have_executed", "confirmed_completed", "confirmed_not_executed", "output_withheld", "delivery_failed", "recorded_failure" ] } } ], "responses": { "200": { "description": "Gateway activity wrapped in data, nullable next_cursor, and summary. Each entry includes attempt_id, operation_id, optional workspace api_key_id/key_name and task_id, an optional summary of the latest supplemental execution record for that task, public model alias and nullable provider-reported model, creation/dispatch/completion times, duration_ms, execution status, usage confidence, nullable prompt/completion token counts, and nullable customer charge currency/amount/status and request phase timing. Integer quantities and amounts are decimal strings. Pages follow the requested sort; next_cursor is the last attempt_id when further matching entries remain. summary covers all rows matching the filters, not only the current page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor", "summary" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_GatewayActivity" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "summary": { "type": "object", "required": [ "request_count", "usage_count", "prompt_tokens", "completion_tokens", "timing_count", "average_duration_ms" ], "properties": { "request_count": { "type": "integer", "format": "int64" }, "usage_count": { "type": "integer", "format": "int64" }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "timing_count": { "type": "integer", "format": "int64" }, "average_duration_ms": { "type": [ "integer", "null" ], "minimum": 0, "description": "Rounded mean of completed gateway request totals over all matching requests. Interrupted phase measurements are excluded. Historical rows without phase timing are excluded because their dispatch interval uses a different boundary. No eligible samples returns null." }, "unresolved_customer_charge_count": { "type": "integer", "minimum": 0 }, "unpriced_request_count": { "type": "integer", "minimum": 0 }, "owner_funded_request_count": { "type": "integer", "minimum": 0, "description": "Dispatched requests using the account owner’s API credential without a Niu customer debit." }, "delivery_statuses": { "type": "array", "description": "Counts by recorded delivery HTTP status across all matching requests in the summary snapshot. Null means unknown, not successful or failed.", "items": { "type": "object", "required": [ "http_status", "request_count" ], "properties": { "http_status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "request_count": { "type": "integer", "minimum": 0 } } } }, "customer_charges": { "type": "array", "items": { "type": "object", "required": [ "currency", "amount_nanos", "charged_requests" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "charged_requests": { "type": "integer", "minimum": 0 } } } }, "customer_unit_charges": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "definition_revision", "name", "display_precision", "atoms_per_unit", "charged_atoms", "restored_atoms", "net_atoms", "charged_requests" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "charged_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "restored_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "net_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "charged_requests": { "type": "integer", "minimum": 0 } } } }, "unit_charges_by_model": { "type": "array", "items": { "type": "object" } }, "unit_charges_by_key": { "type": "array", "items": { "type": "object" } }, "usage_by_model": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "model_alias", "request_count", "usage_count", "prompt_tokens", "completion_tokens", "unknown_usage_count" ], "properties": { "model_alias": { "type": "string" }, "request_count": { "type": "integer", "minimum": 0 }, "usage_count": { "type": "integer", "minimum": 0 }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "unknown_usage_count": { "type": "integer", "minimum": 0 } } } }, "charges_by_model": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Full-range customer ledger totals grouped separately by currency; missing amounts stay null. Coverage counts partition each row's requests. Provider expenses are excluded.", "required": [ "currency", "amount_nanos", "request_count", "charged_requests", "unresolved_requests", "unpriced_requests", "not_charged_requests" ], "properties": { "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "request_count": { "type": "integer", "minimum": 0 }, "charged_requests": { "type": "integer", "minimum": 0 }, "unresolved_requests": { "type": "integer", "minimum": 0 }, "unpriced_requests": { "type": "integer", "minimum": 0 }, "not_charged_requests": { "type": "integer", "minimum": 0 } } }, { "type": "object", "required": [ "model_alias" ], "properties": { "model_alias": { "type": "string" } } } ] } }, "charges_by_key": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Full-range customer ledger totals grouped separately by currency; missing amounts stay null. Coverage counts partition each row's requests. Provider expenses are excluded.", "required": [ "currency", "amount_nanos", "request_count", "charged_requests", "unresolved_requests", "unpriced_requests", "not_charged_requests" ], "properties": { "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "request_count": { "type": "integer", "minimum": 0 }, "charged_requests": { "type": "integer", "minimum": 0 }, "unresolved_requests": { "type": "integer", "minimum": 0 }, "unpriced_requests": { "type": "integer", "minimum": 0 }, "not_charged_requests": { "type": "integer", "minimum": 0 } } }, { "type": "object", "required": [ "api_key_id", "key_name" ], "properties": { "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "key_name": { "type": [ "string", "null" ] } } } ] } }, "usage_by_key": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "api_key_id", "key_name", "request_count", "usage_count", "prompt_tokens", "completion_tokens", "unknown_usage_count" ], "properties": { "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "key_name": { "type": [ "string", "null" ] }, "request_count": { "type": "integer", "minimum": 0 }, "usage_count": { "type": "integer", "minimum": 0 }, "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "unknown_usage_count": { "type": "integer", "minimum": 0 } } } }, "latency_percentiles": { "type": "object", "description": "Discrete percentiles of completed gateway body-consumption durations across the filtered range, independent of pagination. Incomplete or missing measurements are excluded. This is not client receipt time or upstream-only generation time.", "required": [ "boundary", "sample_count", "p50_ms", "p95_ms", "p99_ms" ], "properties": { "boundary": { "type": "string", "const": "gateway_body_ms" }, "sample_count": { "type": "integer", "minimum": 0 }, "p50_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "p95_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "p99_ms": { "type": [ "integer", "null" ], "minimum": 0 } } }, "token_categories": { "type": "object", "description": "Explicitly reported token subsets over the full filtered snapshot. Sums cover reported requests only; null means no observations. Missing category data is never inferred as zero, and no category-specific billing rate is implied.", "required": [ "cache_write_input_tokens", "cached_input_tokens", "cache_write_input_requests", "cached_input_requests", "cache_write_input_unknown_requests", "cached_input_unknown_requests", "reasoning_output_tokens", "reasoning_output_requests", "reasoning_output_unknown_requests" ], "properties": { "cache_write_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cached_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_input_requests": { "type": "integer", "minimum": 0 }, "cached_input_requests": { "type": "integer", "minimum": 0 }, "cache_write_input_unknown_requests": { "type": "integer", "minimum": 0 }, "cached_input_unknown_requests": { "type": "integer", "minimum": 0 }, "reasoning_output_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_output_requests": { "type": "integer", "minimum": 0 }, "reasoning_output_unknown_requests": { "type": "integer", "minimum": 0 } } }, "request_histogram": { "type": "array", "maxItems": 24, "description": "Nonempty time buckets over all filtered requests, independent of pagination. Buckets and other summary aggregates share one database snapshot. Empty ranges return an empty array.", "items": { "type": "object", "required": [ "start_ms", "end_ms", "request_count" ], "properties": { "start_ms": { "type": "integer" }, "end_ms": { "type": "integer" }, "request_count": { "type": "integer", "minimum": 0 } } } } } } } } } }, "headers": { "Cache-Control": { "description": "Request diagnostics must not be cached.", "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid path or query parameter." }, "401": { "description": "Administrator authentication required." } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/requests", "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/setup/default-workspace": { "post": { "operationId": "getOrCreateDefaultWorkspace", "x-niu-implementation": "implemented", "summary": "Get or create the installation default workspace", "description": "Installation credential only. First use atomically creates company/workspace ownership and a zero-funded USD balance account with zero approved credit. Repeated and concurrent calls reuse the designated default. Existing defaults retain their billing configuration. Development login uses the same first-use initializer. No API key, payment receipt or spending capacity is created. No request body is required. The legacy project_id field identifies the workspace; these identifiers are routing references, not display labels.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Stable default ownership references, without a data wrapper.", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "project_id" ], "additionalProperties": false, "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "description": "Workspace routing identifier." } } } } } }, "401": { "description": "Missing, invalid, expired or inference-only credential." }, "403": { "description": "Authenticated member lacks installation authority, including a platform administrator." } }, "tags": [ "Companies and workspaces" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "platform_admin", "scope": "platform" } } }, "/api/v1/organizations/{organization}/projects/{project}/asset-group-intents": { "get": { "operationId": "listAssetGroupRequests", "summary": "Discover saved asset group creation requests", "description": "Workspace-scoped local metadata only; no upstream query or asset-readiness claim. IDs and cursors are internal routing references and must not be displayed as labels. Expired and deleted request names are omitted as null. Provider bindings, credentials, fingerprints and procurement data are excluded.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Bounded page in routing-reference order; Cache-Control no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "status", "created_at", "request_content_status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "prepared", "dispatching", "uncertain", "succeeded" ] }, "created_at": { "type": "string", "format": "date-time" }, "request_content_status": { "type": "string", "enum": [ "retained", "deleted", "expired" ] } } } } } } } } }, "400": { "description": "Invalid cursor, limit or query field." }, "401": { "description": "Member or installation session required." }, "403": { "description": "Workspace read permission required." }, "404": { "description": "Workspace unavailable to this caller." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/asset-group-intents/{intent}/request": { "get": { "operationId": "getAssetGroupRequest", "summary": "Read customer-safe asset request content and retention status", "description": "Requires workspace read permission. Returns null for absent intents. Expired or deleted request content is hidden immediately. Account bindings, credential revisions, fingerprints and procurement data are excluded.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Customer-safe detail or null; Cache-Control no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "status", "created_at", "request_content_status", "request", "dispatch" ], "properties": { "dispatch": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "outcome", "reason", "duration_ms" ], "properties": { "outcome": { "type": "string", "enum": [ "succeeded", "uncertain" ] }, "reason": { "type": [ "string", "null" ], "enum": [ "invalid_configuration", "destination_rejected", "upstream_uncertain", "timeout", null ] }, "duration_ms": { "type": "integer", "minimum": 0, "description": "Measured transport interval; not an inferred upstream phase." } } }, "status": { "type": "string", "enum": [ "prepared", "dispatching", "uncertain", "succeeded" ] }, "created_at": { "type": "string", "format": "date-time" }, "request_content_status": { "type": "string", "enum": [ "retained", "deleted", "expired" ] }, "request": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "name", "description" ], "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } } } } } } } } } }, "401": { "description": "Member or installation session required." }, "403": { "description": "Workspace read permission required." }, "404": { "description": "Workspace outside authorized scope." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "delete": { "operationId": "deleteAssetGroupRequest", "summary": "Delete saved asset-creation request content", "description": "Requires workspace write access. Erases active-database request content while preserving reconciliation metadata and an immutable deletion event. Repeated or absent intent deletion returns 204 without disclosing existence. Does not delete upstream assets, backups or credentials. Prepared intents cannot dispatch after content deletion; already dispatched intents remain reconciliation work.", "security": [ { "adminBearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "intent", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Content absent or erased; no response body." }, "401": { "description": "Member or installation session required; inference keys are not accepted." }, "403": { "description": "Workspace write permission required." }, "404": { "description": "Workspace outside the authorized scope." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/billing/accounts/{currency}/policy/history": { "get": { "operationId": "getCustomerBalancePolicyHistory", "summary": "Read immutable company credit and warning policy revisions", "description": "Organization-wide owner/admin or installation administration required, using the same authorization as company balance reads. Workspace-only sessions and company viewers cannot read shared financial policy. No account IDs, payment references or Provider prices. Exact amounts and revisions are decimal strings. Revision-descending keyset pages use one database snapshot per request; separate pages do not share a snapshot. Missing currency account returns 404; missing revision cursor returns 409. Revision zero with empty history denotes an account with no policy writes. This read does not change funds or credit. Cache-Control no-store.", "security": [ { "bearerAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "before", "in": "query", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "description": "Exclusive existing revision cursor." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Current revision and history page", "content": { "application/json": { "schema": { "type": "object", "required": [ "current_revision", "data", "next_before" ], "properties": { "current_revision": { "type": "string", "pattern": "^[0-9]+$" }, "data": { "type": "array", "items": { "type": "object", "required": [ "revision", "credit_limit_nanos", "warning_threshold_nanos", "created_at", "is_current" ], "properties": { "revision": { "type": "string", "pattern": "^[0-9]+$" }, "credit_limit_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "warning_threshold_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "created_at": { "type": "string", "format": "date-time" }, "is_current": { "type": "boolean" } }, "additionalProperties": false } }, "next_before": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } } } } }, "400": { "description": "Invalid currency, revision or page query" }, "401": { "description": "Invalid session" }, "404": { "description": "Account absent or company billing access denied" }, "409": { "description": "Cursor revision does not exist for this account" } }, "tags": [ "Customer balances" ], "x-niu-authority": { "audience": "platform", "principals": [ "platform_admin", "installation_admin" ], "required_capability": "read", "scope": "platform" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations": { "get": { "operationId": "generationsSessionList", "summary": "List private generations sessions", "description": "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. Read categories are video (default) and chat; legacy Chat write APIs remain unchanged. Revisions and sequences are decimal strings. Video instructions follow existing Chat/intents JSON storage (not application-encrypted at rest); Video 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. Stable descending creation time then UUID pagination; before refers to an actor-visible record independently of its current archive state; archiving a prior page cursor does not invalidate traversal. Invalid cursor returns 400, never an empty page. Limit 1..100; next_before is null when exhausted. Set category=chat for a read-only bridge over the existing actor-private Chat record. The same route defaults to video; IDs are scoped independently by category. Chat metadata uses database clocks and current guarded-write revision. Missing Chat title is null, never replaced by an internal ID. Chat turns preserve comparison branches, not one running conversation task. Per-turn creation/expiry clocks are unknown and null; missing retained prompt yields missing state and null instruction. Turn references are read-only scoped identity/sequence/instruction digests and cannot be used with Video writes. Branch phase/output are exact saved conversation content; actual execution references require a current workspace attempt and matching model. Customer charges are hydrated from the existing ledger projection; no saved procurement fields are returned. Chat retention and writes stay under the legacy Chat contract; Video 30-day instruction retention does not apply to this bridge.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "archived", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video", "chat" ], "default": "video" } } ], "responses": { "200": { "description": "List private video generations sessions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSessionSummary" }, { "$ref": "#/components/schemas/handler_operations_json_GenerationsChatSessionSummary" } ] } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "data", "has_more", "next_before" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/sessions", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/{session}": { "put": { "operationId": "generationsSessionCreate", "summary": "Create a private video generations session", "description": "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. Client chooses stable UUID; expected_revision must be zero. Identical initial retry returns same session; changed title or an already advanced session conflicts.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Create a private video generations session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "const": "0" }, "title": { "type": "string", "minLength": 1, "maxLength": 800 } }, "required": [ "expected_revision", "title" ] } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/sessions/{session}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "get": { "operationId": "generationsSessionGet", "summary": "Read a private saved generations timeline", "description": "Reads accept a category-specific permanent public reference or legacy UUID. Both preserve the same private workspace/owner authorization. Mutation routes continue to require internal UUIDs. 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. Read categories are video (default) and chat; legacy Chat write APIs remain unchanged. Revisions and sequences are decimal strings. Video instructions follow existing Chat/intents JSON storage (not application-encrypted at rest); Video 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. Set category=chat for a read-only bridge over the existing actor-private Chat record. The same route defaults to video; IDs are scoped independently by category. Chat metadata uses database clocks and current guarded-write revision. Missing Chat title is null, never replaced by an internal ID. Chat turns preserve comparison branches, not one running conversation task. Per-turn creation/expiry clocks are unknown and null; missing retained prompt yields missing state and null instruction. Turn references are read-only scoped identity/sequence/instruction digests and cannot be used with Video writes. Branch phase/output are exact saved conversation content; actual execution references require a current workspace attempt and matching model. Customer charges are hydrated from the existing ledger projection; no saved procurement fields are returned. Chat retention and writes stay under the legacy Chat contract; Video 30-day instruction retention does not apply to this bridge.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "video", "chat" ], "default": "video" } } ], "responses": { "200": { "description": "Read a private saved video timeline", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" }, { "$ref": "#/components/schemas/handler_operations_json_GenerationsChatSession" } ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" }, "413": { "description": "Saved Chat payload exceeds the bounded 32 MiB materialization budget." } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/sessions/{session}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "patch": { "operationId": "generationsSessionUpdate", "summary": "Rename or archive a private video session", "description": "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.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rename or archive a private video session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "title": { "type": "string" }, "archived": { "type": "boolean" } }, "required": [ "expected_revision", "title", "archived" ] } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/sessions/{session}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/{session}/turns/{turn}": { "put": { "operationId": "generationsSessionAppend", "summary": "Append one retained video instruction", "description": "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.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "turn", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Append one retained video instruction", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "instruction": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoInstruction" } }, "required": [ "expected_revision", "instruction" ] } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/sessions/{session}/turns/{turn}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "delete": { "operationId": "generationsSessionDeleteInstruction", "summary": "Delete retained instruction content", "description": "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. Expected session revision is required; deletes only instruction content, retaining turn identity and immutable task association.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "turn", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delete retained instruction content", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, "required": [ "expected_revision" ] } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/sessions/{session}/turns/{turn}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/{session}/turns/{turn}/task": { "put": { "operationId": "generationsSessionAttach", "summary": "Attach an existing authorized video task", "description": "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. API-created dispatched video tasks with an original recovery route in the same workspace may be attached by a current workspace writer without an active key secret. An original actor-owned submission intent belonging to another actor is forbidden. One task belongs to one turn and one turn has one task. Existing association retries are idempotent; a different association conflicts. Current revision is required for fresh association. Revoked keys gain no dispatch or refresh authority.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "turn", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attach an existing authorized video task", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "task_id": { "type": "string", "format": "uuid" } }, "required": [ "expected_revision", "task_id" ] } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/sessions/{session}/turns/{turn}/task", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/tasks": { "get": { "operationId": "generationsInventoryTasks", "summary": "List saved Video tasks across workspace keys", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "enum": [ "video" ] } }, { "name": "state", "in": "query", "schema": { "enum": [ "queued", "running", "succeeded", "failed", "unknown", "submission_unknown", "reconciliation_required" ] } }, { "name": "session_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "const": "video" }, "model": { "type": "string" }, "model_display_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "unknown", "submission_unknown", "reconciliation_required" ] }, "source": { "enum": [ "api", "generations", "unknown" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "turn_id": { "type": [ "string", "null" ], "format": "uuid" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "enum": [ "video", "last_frame" ] }, "availability": { "enum": [ "available", "deleted", "expired", "unavailable" ] }, "capture": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationArtifactCapture" }, { "type": "null" } ] } }, "required": [ "kind", "availability", "capture" ] } }, "execution_context": { "type": "object", "additionalProperties": false, "required": [ "submitted_model", "dispatched_model", "provider", "channel", "dispatched_at", "source", "parameters_source", "references_state", "parameters" ], "properties": { "submitted_model": { "type": "string" }, "dispatched_model": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "description": "Adapter recorded at dispatch; not a Provider account name." }, "channel": { "type": [ "string", "null" ] }, "dispatched_at": { "type": "string", "format": "date-time" }, "source": { "const": "saved_execution" }, "parameters_source": { "enum": [ "saved_validated_snapshot", "unknown" ] }, "references_state": { "const": "not_in_execution_snapshot" }, "parameters": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "duration": { "type": "number" }, "seed": { "type": "number" }, "frames_per_second": { "type": "number" }, "watermark": { "type": "boolean" }, "camera_fixed": { "type": "boolean" }, "return_last_frame": { "type": "boolean" }, "resolution": { "type": "string" }, "ratio": { "type": "string" }, "omni_reference_task_type": { "type": "string" } } } } }, "model_display_name_source": { "enum": [ "current_catalog", "unknown" ] }, "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$", "description": "Permanent public run reference, independent of the internal identifier." } }, "required": [ "id", "kind", "model", "model_display_name", "created_at", "updated_at", "state", "source", "session_id", "turn_id", "artifacts", "execution_context", "model_display_name_source" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "supported_kinds": { "type": "array", "items": { "const": "video" } }, "complete": { "const": true } }, "required": [ "data", "has_more", "next_cursor", "supported_kinds", "complete" ] } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/tasks", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/tasks/{task}": { "get": { "operationId": "generationsInventoryTask", "summary": "Read a saved Video task", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$" } ] }, "description": "Internal task UUID or permanent public run reference. Both require the same current workspace and actor authorization." } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "const": "video" }, "model": { "type": "string" }, "model_display_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "unknown", "submission_unknown", "reconciliation_required" ] }, "source": { "enum": [ "api", "generations", "unknown" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "turn_id": { "type": [ "string", "null" ], "format": "uuid" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "enum": [ "video", "last_frame" ] }, "availability": { "enum": [ "available", "deleted", "expired", "unavailable" ] }, "capture": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationArtifactCapture" }, { "type": "null" } ] } }, "required": [ "kind", "availability", "capture" ] } }, "execution_context": { "type": "object", "additionalProperties": false, "required": [ "submitted_model", "dispatched_model", "provider", "channel", "dispatched_at", "source", "parameters_source", "references_state", "parameters" ], "properties": { "submitted_model": { "type": "string" }, "dispatched_model": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "description": "Adapter recorded at dispatch; not a Provider account name." }, "channel": { "type": [ "string", "null" ] }, "dispatched_at": { "type": "string", "format": "date-time" }, "source": { "const": "saved_execution" }, "parameters_source": { "enum": [ "saved_validated_snapshot", "unknown" ] }, "references_state": { "const": "not_in_execution_snapshot" }, "parameters": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "duration": { "type": "number" }, "seed": { "type": "number" }, "frames_per_second": { "type": "number" }, "watermark": { "type": "boolean" }, "camera_fixed": { "type": "boolean" }, "return_last_frame": { "type": "boolean" }, "resolution": { "type": "string" }, "ratio": { "type": "string" }, "omni_reference_task_type": { "type": "string" } } } } }, "model_display_name_source": { "enum": [ "current_catalog", "unknown" ] }, "reference": { "type": "string", "pattern": "^run-[1-9][0-9]{0,18}$", "description": "Permanent public run reference, independent of the internal identifier." } }, "required": [ "id", "kind", "model", "model_display_name", "created_at", "updated_at", "state", "source", "session_id", "turn_id", "artifacts", "execution_context", "model_display_name_source" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/tasks/{task}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/artifacts": { "get": { "operationId": "generationsInventoryArtifacts", "summary": "List actual saved output references", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "enum": [ "video" ] } }, { "name": "state", "in": "query", "schema": { "enum": [ "queued", "running", "succeeded", "failed", "unknown", "submission_unknown", "reconciliation_required" ] } }, { "name": "session_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "video", "last_frame" ] }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "content_type": { "type": [ "string", "null" ], "description": "Inspected captured-library content type when known; otherwise null." }, "availability": { "enum": [ "available", "deleted", "expired", "unavailable" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "turn_id": { "type": [ "string", "null" ], "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "capture": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationArtifactCapture" }, { "type": "null" } ] } }, "required": [ "task_id", "kind", "name", "created_at", "content_type", "availability", "session_id", "turn_id", "workspace_id", "capture" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "supported_kinds": { "type": "array", "items": { "const": "video" } }, "complete": { "const": true } }, "required": [ "data", "has_more", "next_cursor", "supported_kinds", "complete" ] } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/artifacts", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/artifacts/{task}/{kind}": { "get": { "operationId": "generationsInventoryArtifact", "summary": "Read an output availability record", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "video", "last_frame" ] }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "content_type": { "type": [ "string", "null" ], "description": "Inspected captured-library content type when known; otherwise null." }, "availability": { "enum": [ "available", "deleted", "expired", "unavailable" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "turn_id": { "type": [ "string", "null" ], "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "capture": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationArtifactCapture" }, { "type": "null" } ] } }, "required": [ "task_id", "kind", "name", "created_at", "content_type", "availability", "session_id", "turn_id", "workspace_id", "capture" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/artifacts/{task}/{kind}", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/artifacts/{task}/{kind}/content": { "get": { "operationId": "generationsInventoryContent", "summary": "Download an authorized retained output", "description": "Current dashboard workspace Read authorizes saved history even when its inference key is revoked, expired, or its model grants changed. No active key secret is needed. Actor-private session/intent tasks belonging to another actor are excluded. API-created tasks without a private association are workspace-readable. No prompt, upstream URL, asset URI, credential or procurement field is returned. This GET never dispatches, refreshes, retries or settles inference. Task pages use immutable created_at/id DESC; artifacts use immutable output created_at/task_id/kind DESC. A cursor resolves in current authorized workspace independently of mutable state filters; malformed, missing or out-of-scope cursor is 400. Changing filters starts a new live view. No partial successful empty result: storage errors return 503. Artifact reference availability is retention evidence, not a guarantee the upstream bytes still exist. Content delivery performs only bounded result retrieval, rechecking dashboard access and retention after download. Content remains explicitly refused with 409 if its original Provider account/model binding is no longer current; historical read access never restores routing or credential authority. Existing key-scoped APIs and explicit refresh authorization remain unchanged. Chat stays in typed saved sessions; only Video execution inventory is supported.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Saved projection; complete true means this supported Video inventory read completed, not all task kinds.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid query, unsupported kind or inaccessible cursor" }, "401": { "description": "Session invalid or expired" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Record missing or actor-inaccessible" }, "409": { "description": "Original Provider delivery binding is no longer current; metadata history remains readable." }, "503": { "description": "Saved read unavailable; never presented as empty inventory" } }, "x-niu-implementation": "implemented", "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/artifacts/{task}/{kind}/content", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/tasks/{task}/diagnostics": { "get": { "operationId": "generationsTaskDiagnostics", "x-niu-implementation": "implemented", "summary": "Read saved customer billing and transport diagnostics", "description": "Current dashboard workspace Read authorizes persisted diagnostics independently of the original inference key expiry, revocation or model grants. Actor-private tasks belonging to another actor are 404. Billing is customer-only; owner-funded jobs retain null customer charges and never expose procurement costs. Billing and measured transport/lifecycle observations share one bounded read-only snapshot. This GET never contacts a Provider, polls, refreshes, retries, submits or settles a task. Errors are explicit; no successful empty result hides a storage failure.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Persisted customer diagnostics", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "billing", "timings" ], "properties": { "billing": { "$ref": "#/components/schemas/handler_operations_json_VideoJobBilling" }, "timings": { "$ref": "#/components/schemas/handler_operations_json_VideoTransportTimings" } } } } } }, "401": { "description": "Invalid dashboard session" }, "403": { "description": "Workspace Read denied" }, "404": { "description": "Saved Video task missing or actor-private" }, "503": { "description": "Saved diagnostics unavailable" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/tasks/{task}/diagnostics", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/tasks/{task}/refresh": { "post": { "operationId": "refreshGenerationsTask", "x-niu-implementation": "implemented", "summary": "Explicitly refresh the original Video task", "description": "Explicit workspace Write action. Derives the original inference key and immutable Provider/account/model/channel binding from the actor-visible saved task; clients cannot choose replacements. Current original key grants and source policy remain required; revoked or expired keys never regain action authority through history. No generation, automatic retry or composer configuration is used. Rechecks actor visibility and grants after upstream work. Saved GET, cached artifact content, upstream refresh and fresh delivery remain distinct. Queries saved task status through the existing guarded recovery/settlement path; query receipts can be appended, but no task is created.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved Video state after explicit query", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "model", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "video.job" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "submission_unknown", "queued", "running", "succeeded", "failed", "unknown", "reconciliation_required" ] } } } } } }, "400": { "description": "Invalid kind or request" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace Write or original-key permission denied" }, "404": { "description": "Task missing, actor-private, or original key no longer available" }, "409": { "description": "Original Provider binding changed or query already claimed" }, "502": { "description": "Upstream query or result delivery failed" }, "503": { "description": "Storage or bounded delivery unavailable" }, "504": { "description": "Upstream query or delivery timed out" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/tasks/{task}/refresh", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/tasks/{task}/results/{kind}/refresh": { "post": { "operationId": "retrieveFreshGenerationsTaskResult", "x-niu-implementation": "implemented", "summary": "Retrieve fresh output from the original Video task", "description": "Explicit workspace Write action. Derives the original inference key and immutable Provider/account/model/channel binding from the actor-visible saved task; clients cannot choose replacements. Current original key grants and source policy remain required; revoked or expired keys never regain action authority through history. No generation, automatic retry or composer configuration is used. Rechecks actor visibility and grants after upstream work. Saved GET, cached artifact content, upstream refresh and fresh delivery remain distinct. Queries the original task once, then performs bounded authorized binary retrieval. Does not rewrite expired/deleted cached references. A fresh URL does not prove durable media availability; missing result404, Provider gone/unavailable502 and timeout504 remain explicit.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Bounded media bytes", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/webm": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid kind or request" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace Write or original-key permission denied" }, "404": { "description": "Task missing, actor-private, or original key no longer available" }, "409": { "description": "Original Provider binding changed or query already claimed" }, "502": { "description": "Upstream query or result delivery failed" }, "503": { "description": "Storage or bounded delivery unavailable" }, "504": { "description": "Upstream query or delivery timed out" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/tasks/{task}/results/{kind}/refresh", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/artifacts/{task}/{kind}/capture": { "get": { "operationId": "retrieveGenerationsArtifactCapture", "summary": "Read saved artifact capture status", "description": "Current dashboard workspace Read permission and actor-visible original task required. Task/output identity is scoped; no Provider URLs, private references, credentials or costs are returned. Saved claim metadata only; no download, refresh, retry, generation or ledger mutation. Source lookup returns the stored/active outcome or newest failed request; missing/private task or missing capture404.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Saved capture metadata; retained means actual encrypted library bytes were committed, independent of Provider URL expiry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "task_id", "kind", "status", "asset_id", "availability", "failure_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "video", "last_frame" ] }, "status": { "enum": [ "preparing", "stored", "failed" ] }, "asset_id": { "type": [ "string", "null" ], "format": "uuid" }, "availability": { "enum": [ "retained", "deleted", "not_stored" ] }, "failure_code": { "enum": [ null, "delivery_failed", "authorization_changed", "invalid_media", "capacity_exceeded", "storage_unavailable", "encryption_unavailable" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid capture request or media bytes" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace or current key authority denied" }, "404": { "description": "Missing/private task, capture, or unavailable source" }, "409": { "description": "Active lease, changed replay, quota exceeded or binding/visibility conflict" }, "413": { "description": "Source bytes exceed8MiB" }, "502": { "description": "Upstream query or delivery failed" }, "503": { "description": "Capture capacity, configuration or storage unavailable" }, "504": { "description": "Upstream query or delivery timeout" } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/artifacts/{task}/{kind}/capture", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "post": { "operationId": "captureGenerationsArtifact", "summary": "Explicitly save a generated output into workspace materials", "description": "Current dashboard workspace Write permission and actor-visible original task required. Task/output identity is scoped; no Provider URLs, private references, credentials or costs are returned. Explicit bounded copy into the existing encrypted workspace material library, not Provider registration or generation. Cached mode uses unexpired saved references under historical access; fresh mode explicitly queries the original task then retrieves output, using optional selected current workspace key or original-key fallback. The selected key cannot replace the immutable Provider/account/model/channel. Original expired keys without explicit current authority refuse fresh actions. Upstream operations never retry automatically. Two process capture slots; transport and format validation limited to8MiB; existing256asset/256MiB workspace quotas remain. A durable2minute preparing lease is committed before retrieval. Only an explicit repeated POST recovers failed/expired claims. Same requestid with changed fields409; a NEW requestid may change mode after failure; source identity prevents duplicate active/stored captures. Stored source replay returns canonical retained/deleted outcome without network; deleted retained bytes are never resurrected. Asset bytes, source provenance, quota and audit commit atomically after rechecking visibility under the source task lock. Failed delivery returns its error and retains a safe failed claim when storage is available; ambiguous failure-record writes leave preparing, not false availability. Cached expiry/deletion and original task/pricing identity are not rewritten. Fresh status queries may append diagnosis and settle an original pending liability through existing recovery, never create a new generation or reprice it. Saving shares copied bytes with authorized workspace members through the existing library; Provider readiness and verified identity remain separate.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Saved capture metadata; retained means actual encrypted library bytes were committed, independent of Provider URL expiry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "task_id", "kind", "status", "asset_id", "availability", "failure_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "video", "last_frame" ] }, "status": { "enum": [ "preparing", "stored", "failed" ] }, "asset_id": { "type": [ "string", "null" ], "format": "uuid" }, "availability": { "enum": [ "retained", "deleted", "not_stored" ] }, "failure_code": { "enum": [ null, "delivery_failed", "authorization_changed", "invalid_media", "capacity_exceeded", "storage_unavailable", "encryption_unavailable" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid capture request or media bytes" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace or current key authority denied" }, "404": { "description": "Missing/private task, capture, or unavailable source" }, "409": { "description": "Active lease, changed replay, quota exceeded or binding/visibility conflict" }, "413": { "description": "Source bytes exceed8MiB" }, "502": { "description": "Upstream query or delivery failed" }, "503": { "description": "Capture capacity, configuration or storage unavailable" }, "504": { "description": "Upstream query or delivery timeout" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "mode" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Canonical nonnil request identity retained before sending." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Exact trimmed UTF8 name, at most200 bytes, no control characters." }, "mode": { "enum": [ "cached", "fresh" ] }, "key_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Only fresh: explicit current workspace key authority; original Provider binding never changes." } } } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/artifacts/{task}/{kind}/capture", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/organizations/{organization}/projects/{project}/generations/{session}/turns/{turn}/intent": { "put": { "operationId": "generationsSessionBindIntent", "summary": "Bind a saved Video intent to a private turn", "description": "Current workspace Write and actor-owned video session/turn/intent required. This only binds saved restoration identity and never dispatches, refreshes or automatically submits inference. One turn and one intent form an immutable association within the same owner/workspace. A fresh association requires expected session revision, an unarchived session and retained turn/intent content. Identical binding retries are side-effect-free even after revision advances, archive, deletion or expiry; changed binding conflicts. If the turn already references a task, it must equal the actual attempt from the original intent submission identity. Session reads resolve any saved original attempt directly from that identity after a lost submission/association response without another inference call. Pending/not-dispatched/unknown outcomes are never assumed free or safe to resend. Safe intent projection includes id, revision, model, content state and submission state, not raw request, key secret or private upstream references. Turn content deletion/expiry clears the bound retained intent copy under turn-to-intent locking while preserving submission tombstones, task evidence, billing and diagnostics. Intent and turn keep their original 30-day retention deadlines; neither is extended. Legacy Video intent APIs remain compatible and explicit submission continues through their submit endpoint. The bound intent is canonical for the actual restored Video draft/request, including model, controls and material inputs. The separately saved turn instruction may be a review note and is not represented as proof of the dispatched prompt; reads never substitute it for missing retained intent content.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "turn", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attach an existing authorized video task", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoSession" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request or cursor" }, "401": { "description": "Invalid administrator session or unauthorized historical task" }, "403": { "description": "Current workspace permission denied" }, "404": { "description": "Actor-owned session is absent" }, "409": { "description": "Stale revision, changed idempotent identity, archive or task association conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "intent_id": { "type": "string", "format": "uuid" } }, "required": [ "expected_revision", "intent_id" ] } } } }, "x-niu-canonical-route": "/api/v1/workspaces/{workspace}/sessions/{session}/turns/{turn}/intent", "tags": [ "Generation history" ], "x-niu-authority": { "audience": "console", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/v1/key": { "get": { "operationId": "getCurrentKey", "summary": "Inspect the current workspace API key", "description": "Returns the existing customer-safe key projection: object, label, allowed_models, expires_at_ms and last_used_at_ms (Unix milliseconds), revoked/expired flags, spending_limits (limit_nanos, committed_nanos, remaining_nanos), flat rate_limits, usage_window and allowed_cidrs. Does not rename fields or change the HTTP response. Workspace policies and live authorization still apply. Unknown usage remains explicit and model grants do not establish upstream availability. Authenticates an inference API key, or the workspace key selected via X-Niu-Key-Id with an authorized console session. Never returns the secret token, internal platform UUIDs or Provider procurement costs.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "responses": { "200": { "description": "Current API key metadata, limits, and usage.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "object", "label", "allowed_models", "expires_at_ms", "last_used_at_ms", "revoked", "expired", "spending_limits", "rate_limits", "usage_window", "allowed_cidrs" ], "properties": { "object": { "type": "string", "const": "api_key" }, "label": { "type": "string" }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "expires_at_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix milliseconds, never seconds. Null means no automatic expiration; revocation and policies still apply." }, "last_used_at_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Last dispatch time in Unix milliseconds, or null when no dispatch is recorded." }, "revoked": { "type": "boolean" }, "expired": { "type": "boolean" }, "spending_limits": { "type": "array", "description": "Customer spending policies by currency. A null limit is unlimited; a null remaining value is not a zero allowance. Amounts are exact integer nanounit strings.", "items": { "type": "object", "additionalProperties": false, "required": [ "currency", "limit_nanos", "committed_nanos", "remaining_nanos" ], "properties": { "currency": { "type": "string" }, "limit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "committed_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "remaining_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } } } }, "unit_spending_limit": { "type": [ "object", "null" ] }, "rate_limits": { "type": "object", "additionalProperties": false, "description": "Null policy limits mean unlimited; a known zero blocks requests under that policy.", "required": [ "requests_per_minute", "tokens_per_minute", "max_concurrent_requests", "active_requests" ], "properties": { "requests_per_minute": { "type": [ "integer", "null" ], "minimum": 0 }, "tokens_per_minute": { "type": [ "integer", "null" ], "minimum": 0 }, "max_concurrent_requests": { "type": [ "integer", "null" ], "minimum": 0 }, "active_requests": { "type": "integer", "minimum": 0 } } }, "usage_window": { "type": "object", "additionalProperties": false, "description": "Known token subtotals are not complete usage when unknown_usage_requests is positive.", "required": [ "window_seconds", "window_end", "requests", "known_usage_requests", "unknown_usage_requests", "known_prompt_tokens", "known_completion_tokens" ], "properties": { "window_seconds": { "type": "integer", "const": 60 }, "window_end": { "type": "string", "format": "date-time" }, "requests": { "type": "integer", "minimum": 0 }, "known_usage_requests": { "type": "integer", "minimum": 0 }, "unknown_usage_requests": { "type": "integer", "minimum": 0 }, "known_prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "known_completion_tokens": { "type": "string", "pattern": "^[0-9]+$" } } }, "allowed_cidrs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Current source-IP allowlist, or null for no allowlist restriction." } } } } } } } }, "401": { "description": "Missing, revoked, expired or invalid key." } }, "x-niu-implementation": "implemented", "tags": [ "API keys" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/generations/{id}": { "get": { "operationId": "getGeneration", "summary": "Get generation usage, latency, and customer charge by ID", "description": "Returns token breakdown, latency/timing observations, execution status, and customer-facing charge for a generation attempt in the authenticated key's workspace. Never exposes Provider purchase costs, platform margins, or internal correlation UUIDs.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Generation telemetry and customer charge.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "model", "request_kind", "created_at", "execution", "usage_confidence", "usage", "customer_charge" ], "properties": { "id": { "type": "string", "format": "uuid" }, "model": { "type": "string" }, "provider_model": { "type": [ "string", "null" ] }, "request_kind": { "type": "string", "enum": [ "inference", "video" ] }, "created_at": { "type": "string", "format": "date-time" }, "dispatched_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ] }, "execution": { "type": "string" }, "usage_confidence": { "type": "string" }, "usage": { "type": "object", "required": [ "prompt_tokens", "completion_tokens", "cached_input_tokens", "cache_write_input_tokens", "reasoning_output_tokens" ], "properties": { "prompt_tokens": { "type": [ "string", "null" ] }, "completion_tokens": { "type": [ "string", "null" ] }, "cached_input_tokens": { "type": [ "string", "null" ] }, "cache_write_input_tokens": { "type": [ "string", "null" ] }, "reasoning_output_tokens": { "type": [ "string", "null" ] } } }, "customer_charge": { "type": "object", "required": [ "status", "currency", "amount_nanos" ], "properties": { "status": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "amount_nanos": { "type": [ "string", "null" ] }, "unit": { "type": [ "object", "null" ] } } }, "timing": { "type": [ "object", "null" ] }, "finish_reasons": { "type": [ "array", "null" ] }, "failure": { "type": [ "object", "null" ] }, "output_guardrail_outcome": { "type": [ "string", "null" ] } } } } } } } }, "401": { "description": "Missing, revoked, expired or invalid key." }, "404": { "description": "Generation not found in workspace." } }, "x-niu-implementation": "implemented", "tags": [ "Request logs and usage" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/media/capabilities": { "get": { "operationId": "discoverNativeProviderCapabilities", "summary": "Discover authorized model-specific native Provider tools", "description": "Requires a current workspace API key or a workspace session with X-Niu-Key-Id. Reuses current video discovery and native module admission: current key/model grants, composed workspace/key model and Provider policy, eligible exact route, ownership, selectable credential and current configuration identity. Optional model is an exact alias, never a Provider inference hint. With no model, returns all eligible admitted contexts without picking the first. With an authorized video model that has no supported native module (including OpenRouter), returns complete:true and modules:[]. Unknown or unauthorized model returns 404. Admission, storage or configuration failures are errors, never successful empty discovery. No upstream request, inventory probe, material mutation, verification creation or generation is issued. Volcengine requires explicitly configured fastrouter-actions-v1 management plus a validated matching ark-direct-v1 video schema and valid management endpoint. Materials support is independent of generation reference support; reference_inputs describes configured schema only, and use still requires acknowledged Active materials, exact account/model/channel binding, current policy and dispatch authorization. Mutation endpoints additionally require Write permission. Human verification support is not a verification outcome. Contains no credentials, API base, upstream model, Provider resource references or internal account identifiers. Successful responses carry Cache-Control:no-store.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "x-niu-implementation": "implemented", "parameters": [ { "name": "model", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Optional exact authorized video model alias." } ], "responses": { "200": { "description": "Complete authorized native-module contexts; an empty modules array means no eligible native tools for the selection.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_NativeProviderCapabilities" } } } }, "400": { "description": "Invalid path or model query, or an unknown query field." }, "401": { "description": "Authentication or selected workspace key is invalid or revoked." }, "403": { "description": "Workspace membership, Read permission or current policy denies access." }, "404": { "description": "Selected model or eligible route is absent or unauthorized." }, "409": { "description": "Selected route configuration changed during admission." }, "501": { "description": "Configured native management transport is unsupported." }, "503": { "description": "Storage, selectable credential, Provider qualification or native configuration unavailable." } }, "tags": [ "Media assets and verification" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "read", "scope": "workspace" } } }, "/v1/video/jobs/{id}/results/{kind}/refresh": { "post": { "operationId": "retrieveFreshVideoResult", "x-niu-implementation": "implemented", "summary": "Retrieve fresh output from the original Video task", "description": "Explicitly queries the original upstream video task once using the immutable original Provider/account/model/channel binding and delivers bounded media bytes without rewriting cached references. Requires a current workspace API key or a workspace session with X-Niu-Key-Id and Write permission.", "security": [ { "bearerAuth": [] }, { "niuApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "video", "last_frame" ] } } ], "responses": { "200": { "description": "Bounded media bytes", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/webm": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid kind or request" }, "401": { "description": "Invalid, expired or revoked credential" }, "403": { "description": "Permission or guardrail policy denied" }, "404": { "description": "Task or requested result missing" }, "409": { "description": "Original Provider binding changed or query already claimed" }, "502": { "description": "Upstream query or result delivery failed" }, "503": { "description": "Storage or bounded delivery unavailable" }, "504": { "description": "Upstream query or delivery timed out" } }, "tags": [ "Video generation" ], "x-niu-authority": { "audience": "model", "principals": [ "workspace_api_key", "console_key_selection" ], "required_capability": "inference", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys": { "get": { "operationId": "listWorkspaceKeys", "summary": "List workspace API keys with aggregated limits and policies", "description": "Returns workspace API keys along with their current spending limits, request/token rate limits, concurrency limits, IP allowlist policy, and 60-second usage window in a single response. Requires an installation credential or member session with workspace read access. Workspace inference API keys do not authorize key management. Without limit or after, returns the complete compatibility directory without next_cursor. Supplying either selects a bounded page (default 50, maximum 100). Follow next_cursor until null.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Workspace keys with aggregated limits and policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyDetailPage" } } } }, "400": { "description": "Invalid path, query or input. Framework parsing failures may be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, expired or revoked management credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Insufficient management permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace or key not found in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "503": { "description": "Durable storage or required configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "post": { "operationId": "createWorkspaceKey", "summary": "Create a workspace API key with optional initial limits and policies", "description": "Issues a new workspace API key and optionally configures initial spending limits, RPM/TPM/concurrency limits, and IP allowlist CIDRs in a single call. Explicit allowed_cidrs: [] denies every source; null or omission leaves sources unrestricted. Matches the independent IP policy endpoint. Requires an installation credential or member session with workspace write access. Workspace inference API keys do not authorize key management. With Idempotency-Key, retries cannot create a second credential. HTTP 201 returns a new secret once; HTTP 200 means the mutation already committed and the secret is unavailable. Inspect or revoke the resulting key before explicitly replacing lost access. Without this header, legacy non-idempotent behavior remains.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Keep this nonzero UUID and identical input for every retry. A committed replay returns metadata only and never repeats the secret." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "ttl_seconds" ], "properties": { "name": { "type": "string" }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "ttl_seconds": { "type": [ "integer", "null" ] }, "spending_limit": { "type": [ "object", "null" ], "required": [ "currency", "limit_nanos" ], "properties": { "currency": { "type": "string" }, "limit_nanos": { "type": [ "string", "null" ] } } }, "requests_per_minute": { "type": [ "integer", "null" ] }, "tokens_per_minute": { "type": [ "integer", "null" ] }, "max_concurrent_requests": { "type": [ "integer", "null" ] }, "allowed_cidrs": { "type": [ "array", "null" ], "description": "Empty array denies every source; null or omission leaves sources unrestricted.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Previously committed mutation; secret cannot be retrieved", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "key", "secret_available" ], "properties": { "id": { "type": "string", "format": "uuid" }, "secret_available": { "type": "boolean", "const": false }, "key": { "type": [ "object", "null" ], "additionalProperties": true } } } } } }, "201": { "description": "Issued key identity, one-time secret, and full key detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_IssuedWorkspaceKeyDetail" } } } }, "400": { "description": "Invalid path, query or input. Framework parsing failures may be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, expired or revoked management credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Insufficient management permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace or key not found in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "409": { "description": "Revision or write conflict; reload current state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "413": { "description": "Request body exceeds the route limit.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Unsupported request Content-Type.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "JSON body does not match the input type.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Durable storage or required configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}": { "get": { "operationId": "getWorkspaceKey", "summary": "Retrieve a workspace API key with its policies and usage window", "description": "Returns metadata, spending limits, RPM/TPM/concurrency limits, IP allowlist policy, and 60-second usage window for a single workspace API key. Requires an installation credential or member session with workspace read access. Workspace inference API keys do not authorize key management.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workspace API key detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyDetail" } } } }, "400": { "description": "Invalid path, query or input. Framework parsing failures may be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, expired or revoked management credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Insufficient management permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace or key not found in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "503": { "description": "Durable storage or required configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } }, "patch": { "operationId": "updateWorkspaceKey", "summary": "Update workspace API key metadata and policies", "description": "Updates key name, model grants, spending limit, RPM/TPM/concurrency limits, and IP allowlist policy in a single request and returns the updated key detail. Omitting ip_policy leaves it unchanged. Within ip_policy, explicit allowed_cidrs: [] denies every source and null permits any source, matching the independent IP policy endpoint. Existing saved policies are not reinterpreted. Requires an installation credential or member session with workspace write access. Workspace inference API keys do not authorize key management.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated workspace API key detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyDetail" } } } }, "400": { "description": "Invalid path, query or input. Framework parsing failures may be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, expired or revoked management credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Insufficient management permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace or key not found in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "409": { "description": "Revision or write conflict; reload current state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "413": { "description": "Request body exceeds the route limit.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Unsupported request Content-Type.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "JSON body does not match the input type.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Durable storage or required configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } }, "delete": { "operationId": "revokeWorkspaceKey", "summary": "Revoke a workspace API key", "description": "Idempotently revokes a workspace API key within the authorized workspace scope. Requires an installation credential or member session with workspace write access. Workspace inference API keys do not authorize key management.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Key revoked" }, "400": { "description": "Invalid path, query or input. Framework parsing failures may be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, expired or revoked management credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Insufficient management permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace or key not found in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "503": { "description": "Durable storage or required configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/{key}/rotate": { "post": { "operationId": "rotateWorkspaceKey", "summary": "Rotate a workspace API key while preserving its policies and expiry", "description": "Atomically revokes the existing key and issues a replacement key sharing the same model grants, expiration, and policy lineage. Requires an installation credential or member session with workspace write access. Workspace inference API keys do not authorize key management. With Idempotency-Key, retries cannot create a second credential. HTTP 201 returns a new secret once; HTTP 200 means the mutation already committed and the secret is unavailable. Inspect or revoke the resulting key before explicitly replacing lost access. Without this header, legacy non-idempotent behavior remains.", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Keep this nonzero UUID and identical input for every retry. A committed replay returns metadata only and never repeats the secret." } ], "responses": { "200": { "description": "Previously committed mutation; secret cannot be retrieved", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "key", "secret_available" ], "properties": { "id": { "type": "string", "format": "uuid" }, "secret_available": { "type": "boolean", "const": false }, "key": { "type": [ "object", "null" ], "additionalProperties": true } } } } } }, "201": { "description": "Replacement key identity, one-time secret, and full key detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_IssuedWorkspaceKeyDetail" } } } }, "400": { "description": "Invalid path, query or input. Framework parsing failures may be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, expired or revoked management credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "403": { "description": "Insufficient management permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "404": { "description": "Workspace or key not found in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "409": { "description": "Revision or write conflict; reload current state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } }, "503": { "description": "Durable storage or required configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler_operations_json_ApiErrorResponse" } } } } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "write", "scope": "workspace" } } }, "/api/v1/workspaces/{workspace}/keys/requests/{request}": { "get": { "operationId": "getWorkspaceKeyRequest", "x-niu-implementation": "implemented", "security": [ { "bearerAuth": [] } ], "summary": "Reconcile an API key creation or rotation request", "description": "Requires current workspace write access. Returns only a committed outcome and key metadata, never a key secret. Null data means no committed outcome was observed; an in-flight request may still commit, so retry only the same Idempotency-Key and unchanged input. This response is not cacheable.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Observed durable outcome, without secrets", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "action", "key" ], "properties": { "action": { "type": "string", "enum": [ "create", "rotate" ] }, "key": { "type": "object", "additionalProperties": true } } } ] } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace write access required" }, "404": { "description": "Workspace is unavailable to this caller" } }, "tags": [ "API keys" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "workspace" } } }, "/api/v1/payments/readiness": { "get": { "operationId": "getPaymentReadiness", "summary": "Read payment or scoped funding readiness", "x-niu-implementation": "implemented", "security": [ {}, { "bearerAuth": [] } ], "description": "Anonymous reads describe installation payment configuration only. Authenticated reads may select an authorized company using organization; member sessions default to their own company. An explicit funded, granted or approved-credit arrangement in the platform currency permits that company to use self-hosted workspace features without a merchant. Empty accounts and another company’s funds never qualify. This setup decision is separate from per-request balance reservation; spending credits does not hide history or settings. Authentication, administration, directory lookup and funding recovery stay available. No amounts, merchant credentials or identities are returned.", "responses": { "200": { "description": "Current prerequisite state", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "ready", "reason" ], "properties": { "ready": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "enum": [ "currency_required", "payment_setup_required", null ] } } } } } } } }, "401": { "description": "Requested authenticated scope has no valid session" }, "403": { "description": "Company outside authorized scope" }, "500": { "description": "Readiness could not be established; clients must not assume readiness." } }, "parameters": [ { "name": "organization", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Authenticated company scope; installation credentials may select a company, members may only select their own." } ], "tags": [ "Customer payments" ], "x-niu-authority": { "audience": "customer-management", "principals": [ "operator_session", "installation_admin" ], "required_capability": "read", "scope": "organization" } } } }, "components": { "schemas": { "ModelMetadataBase": { "type": "object", "required": [ "id", "public_catalog", "catalog", "customer_pricing" ], "properties": { "generation_capabilities": { "type": "object", "additionalProperties": false, "required": [ "chat", "video" ], "description": "Current configured preview support, from the same visible registry snapshot. A Video-only route overrides stale catalog text metadata. Null Chat support means unknown legacy metadata, not support. Key grants, current policy, funding and upstream availability are checked separately at execution.", "properties": { "chat": { "type": [ "boolean", "null" ] }, "video": { "type": "boolean" } } }, "id": { "type": "string", "description": "Public model alias." }, "public_catalog": { "type": "boolean" }, "catalog": { "type": "object", "additionalProperties": false, "required": [ "name", "description", "context_length", "max_completion_tokens", "input_modalities", "output_modalities", "supported_parameters" ], "properties": { "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "context_length": { "type": [ "integer", "null" ], "minimum": 1 }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 1 }, "input_modalities": { "type": "array", "items": { "type": "string" } }, "output_modalities": { "type": "array", "items": { "type": "string" } }, "supported_parameters": { "type": "array", "items": { "type": "string" } } } }, "customer_pricing": { "description": "Effective workspace customer selling tariff, or null when no workspace is selected, no tariff is resolved, or the route is personal. Null never means free. Excludes procurement rates.", "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_WorkspaceCustomerModelPrice" }, { "type": "null" } ] } } }, "ModelMetadataCapabilities": { "type": "object", "required": [ "supports_embeddings", "supports_embedding_dimensions", "supports_embedding_base64", "supports_tool_calls", "supports_streaming_tool_calls", "supports_structured_output", "supports_messages", "supports_messages_streaming", "supports_messages_tools", "supports_messages_streaming_tools", "supports_generate_content", "supports_responses" ], "properties": { "supports_embeddings": { "type": "boolean" }, "supports_embedding_dimensions": { "type": "boolean" }, "supports_embedding_base64": { "type": "boolean" }, "supports_tool_calls": { "type": "boolean" }, "supports_streaming_tool_calls": { "type": "boolean" }, "supports_structured_output": { "type": "boolean" }, "supports_messages": { "type": "boolean" }, "supports_messages_streaming": { "type": "boolean" }, "supports_messages_tools": { "type": "boolean" }, "supports_messages_streaming_tools": { "type": "boolean" }, "supports_generate_content": { "type": "boolean" }, "supports_responses": { "type": "boolean" } } }, "MemberModelMetadata": { "description": "Member projection; no private Provider mapping or procurement information.", "allOf": [ { "$ref": "#/components/schemas/ModelMetadataBase" }, { "type": "object", "required": [ "capabilities" ], "properties": { "capabilities": { "$ref": "#/components/schemas/ModelMetadataCapabilities" } } } ], "unevaluatedProperties": false }, "InstallationModelMetadata": { "description": "Installation-only projection with configured Provider/upstream mapping. Credentials and procurement prices are excluded.", "allOf": [ { "$ref": "#/components/schemas/ModelMetadataBase" }, { "$ref": "#/components/schemas/ModelMetadataCapabilities" }, { "type": "object", "required": [ "provider", "upstream_model" ], "properties": { "provider": { "type": "string" }, "upstream_model": { "type": "string" } } } ], "unevaluatedProperties": false }, "MediaVerificationSession": { "$ref": "#/components/schemas/handler_operations_json_MediaVerificationSession" }, "MediaAssetGroup": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroup" }, "MediaAsset": { "$ref": "#/components/schemas/handler_operations_json_MediaAsset" }, "MediaAssetOperation": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" }, "MediaAssetMutation": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetMutation" }, "MediaAssetGroupPage": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroupPage" }, "MediaAssetPage": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetPage" }, "BrandingConfiguration": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision", "settings" ], "properties": { "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "settings": { "$ref": "#/components/schemas/BrandingSettings" } } } } }, "BrandingSettings": { "type": "object", "additionalProperties": false, "required": [ "display_name", "default_appearance", "light", "dark" ], "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Trimmed nonempty text without control characters" }, "default_appearance": { "type": "string", "enum": [ "system", "light", "dark" ] }, "logo_data_url": { "type": [ "string", "null" ], "maxLength": 349550, "pattern": "^data:image/png;base64,[A-Za-z0-9+/=]+$", "description": "Static PNG up to 256 KiB, at most 1024 by 512 pixels. Re-encoded from decoded pixels before saving. Missing or null resets to default." }, "favicon_data_url": { "type": [ "string", "null" ], "maxLength": 43714, "pattern": "^data:image/png;base64,[A-Za-z0-9+/=]+$", "description": "Square static PNG up to 32 KiB, at most 256 by 256 pixels. Missing or null resets to default." }, "light": { "$ref": "#/components/schemas/BrandingPalette" }, "dark": { "$ref": "#/components/schemas/BrandingPalette" } } }, "BrandingPalette": { "type": "object", "maxProperties": 8, "propertyNames": { "enum": [ "background", "foreground", "primary", "primary-foreground", "sidebar", "sidebar-foreground", "accent", "accent-foreground" ] }, "additionalProperties": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "OrdinaryAssetLookupResult": { "type": "object", "additionalProperties": false, "required": [ "lookup_id", "asset" ], "properties": { "lookup_id": { "type": "string", "format": "uuid" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "name", "status", "asset_type", "created_at", "updated_at", "last_inference_at" ], "properties": { "name": { "type": "string", "maxLength": 64 }, "status": { "type": "string", "enum": [ "Active", "Processing", "Failed" ] }, "asset_type": { "type": "string", "enum": [ "Image", "Video", "Audio" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_inference_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "OrdinaryAssetLookupAudit": { "type": "object", "additionalProperties": false, "required": [ "lookup_id", "listing_id", "status", "asset_status", "started_at", "completed_at", "duration_ms", "reason" ], "properties": { "lookup_id": { "type": "string", "format": "uuid" }, "listing_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "unresolved", "succeeded", "failed" ] }, "asset_status": { "type": [ "string", "null" ], "enum": [ "Active", "Processing", "Failed", null ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "reason": { "type": [ "string", "null" ], "enum": [ "invalid_configuration", "destination_rejected", "unavailable", "transport", "timeout", "response_limit", "invalid_response", null ] } } }, "OrdinaryAssetListingAudit": { "type": "object", "additionalProperties": false, "required": [ "listing_id", "previous_listing_id", "page_number", "status", "started_at", "completed_at", "duration_ms", "reason", "item_count", "has_more" ], "properties": { "listing_id": { "type": "string", "format": "uuid" }, "previous_listing_id": { "type": [ "string", "null" ], "format": "uuid" }, "page_number": { "type": "integer", "minimum": 1, "maximum": 100 }, "status": { "type": "string", "enum": [ "unresolved", "succeeded", "failed" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "reason": { "type": [ "string", "null" ], "enum": [ null, "invalid_configuration", "destination_rejected", "unavailable", "transport", "timeout", "response_limit", "invalid_response" ] }, "item_count": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "has_more": { "type": [ "boolean", "null" ], "description": "Observed next-page availability, not complete inventory or current permission to continue." } } }, "OrdinaryAssetListingResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "listing_id", "items", "has_more" ], "properties": { "listing_id": { "type": "string", "format": "uuid" }, "has_more": { "type": "boolean", "description": "Additional upstream pages were observed; continue using this listing as previous_listing_id within the retained, authorized chain." }, "items": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "status", "asset_type", "created_at", "updated_at", "last_inference_at" ], "properties": { "name": { "type": "string", "maxLength": 64 }, "status": { "type": "string", "enum": [ "Active", "Processing", "Failed" ] }, "asset_type": { "type": "string", "enum": [ "Image", "Video", "Audio" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_inference_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "OrdinaryAssetGroupInput": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id", "idempotency_key", "vendor_revision", "credential_revision", "name" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "description": "Workspace routing identifier." }, "idempotency_key": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "integer", "minimum": 1 }, "credential_revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Nonblank ordinary group name; control characters are rejected." }, "description": { "type": [ "string", "null" ], "maxLength": 300, "description": "Newline/tab/carriage return allowed; other control characters rejected." } } }, "AssetOperationAuthorizationInput": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "project_id", "vendor_revision", "credential_revision", "rights_sha256", "protocol_sha256", "data_handling_sha256", "free_operation_sha256", "valid_for_seconds" ], "properties": { "operation": { "type": "string", "enum": [ "CreateAssetGroup", "GetAssetGroup", "ListAssets", "GetAsset", "UpdateAssetGroup", "DeleteAssetGroup", "CreateAsset" ], "default": "CreateAssetGroup", "description": "Each operation requires separate reviewed evidence; omitted means CreateAssetGroup only." }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "description": "Workspace routing identifier." }, "vendor_revision": { "type": "integer", "minimum": 1 }, "credential_revision": { "type": "integer", "minimum": 1 }, "rights_sha256": { "$ref": "#/components/schemas/AssetEvidenceDigest" }, "protocol_sha256": { "$ref": "#/components/schemas/AssetEvidenceDigest" }, "data_handling_sha256": { "$ref": "#/components/schemas/AssetEvidenceDigest" }, "free_operation_sha256": { "$ref": "#/components/schemas/AssetEvidenceDigest" }, "valid_for_seconds": { "type": "integer", "minimum": 1, "maximum": 7776000 } } }, "AssetEvidenceDigest": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$", "not": { "const": "0000000000000000000000000000000000000000000000000000000000000000" } }, "AssetOperationAuthorization": { "type": "object", "required": [ "id", "organization_id", "project_id", "vendor_revision", "credential_revision", "operation", "rights_sha256", "protocol_sha256", "data_handling_sha256", "free_operation_sha256", "created_at", "expires_at", "revoked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "integer", "minimum": 1 }, "credential_revision": { "type": "integer", "minimum": 1 }, "operation": { "type": "string", "enum": [ "CreateAssetGroup", "GetAssetGroup", "ListAssets", "GetAsset", "UpdateAssetGroup", "DeleteAssetGroup", "CreateAsset" ] }, "rights_sha256": { "$ref": "#/components/schemas/AssetEvidenceDigest" }, "protocol_sha256": { "$ref": "#/components/schemas/AssetEvidenceDigest" }, "data_handling_sha256": { "$ref": "#/components/schemas/AssetEvidenceDigest" }, "free_operation_sha256": { "$ref": "#/components/schemas/AssetEvidenceDigest" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "revoked": { "type": "boolean" } } }, "AssetManagementConfiguration": { "type": "object", "additionalProperties": false, "required": [ "revision", "upstream_project", "configured", "dispatch_available" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "upstream_project": { "type": "string" }, "configured": { "type": "boolean" }, "dispatch_available": { "type": "boolean", "const": false } } }, "VideoResultAvailability": { "type": "object", "additionalProperties": false, "required": [ "video", "last_frame" ], "properties": { "video": { "type": "string", "enum": [ "available", "missing", "unavailable" ] }, "last_frame": { "type": "string", "enum": [ "available", "missing", "unavailable" ] } } }, "VideoBillingQuantity": { "$ref": "#/components/schemas/handler_operations_json_VideoBillingQuantity" }, "VideoJobBilling": { "$ref": "#/components/schemas/handler_operations_json_VideoJobBilling" }, "CatalogMetadata": { "$ref": "#/components/schemas/handler_operations_json_CatalogMetadata" }, "ProviderCatalogModel": { "$ref": "#/components/schemas/handler_operations_json_ProviderCatalogModel" }, "GatewayActivity": { "$ref": "#/components/schemas/handler_operations_json_GatewayActivity" }, "Vendor": { "$ref": "#/components/schemas/handler_operations_json_Vendor" }, "VendorCreate": { "$ref": "#/components/schemas/handler_operations_json_VendorCreate" }, "VendorUpdate": { "$ref": "#/components/schemas/handler_operations_json_VendorUpdate" }, "VendorCapabilities": { "$ref": "#/components/schemas/handler_operations_json_VendorCapabilities" }, "VideoModelList": { "type": "object", "additionalProperties": false, "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoModel" } } } }, "VideoModel": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "mode", "input_types", "text", "maximum_body_bytes", "maximum_content_items", "controls", "required_controls", "exclusive_controls", "output" ], "properties": { "object": { "const": "video.model" }, "id": { "type": "string", "description": "Customer model alias" }, "mode": { "type": "string", "enum": [ "owner_funded", "customer" ] }, "input_types": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "enum": [ "text", "image_url", "audio_url", "video_url" ] } }, "requires_image": { "type": "boolean" }, "image_url": { "type": "object", "additionalProperties": false, "required": [ "maximum_items", "maximum_bytes", "https", "data_mime_types", "roles", "role_required", "requires_text" ], "properties": { "maximum_items": { "type": "integer", "minimum": 1, "maximum": 32 }, "maximum_bytes": { "type": "integer", "minimum": 1 }, "https": { "type": "boolean" }, "data_mime_types": { "type": "array", "uniqueItems": true, "items": { "enum": [ "image/png", "image/jpeg", "image/webp" ] } }, "roles": { "type": "array", "items": { "type": "string" } }, "role_required": { "type": "boolean" }, "requires_text": { "type": "boolean" }, "maximum_width": { "type": "integer", "minimum": 1 }, "maximum_height": { "type": "integer", "minimum": 1 }, "maximum_decoded_bytes": { "type": "integer", "minimum": 1 } } }, "audio_url": { "$ref": "#/components/schemas/VideoRemoteReferenceInput" }, "video_url": { "$ref": "#/components/schemas/VideoRemoteReferenceInput" }, "text": { "type": "object", "additionalProperties": false, "required": [ "maximum_items", "maximum_bytes" ], "properties": { "maximum_items": { "type": "integer", "minimum": 1, "maximum": 32 }, "maximum_bytes": { "type": "integer", "minimum": 1, "maximum": 16777216 } } }, "maximum_body_bytes": { "type": "integer", "minimum": 1, "maximum": 16777216 }, "maximum_content_items": { "type": "integer", "minimum": 1, "maximum": 32 }, "controls": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/VideoIntegerControl" }, { "$ref": "#/components/schemas/VideoChoiceControl" }, { "$ref": "#/components/schemas/VideoBooleanControl" } ] } }, "required_controls": { "type": "array", "items": { "type": "string" } }, "exclusive_controls": { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string" } } }, "output": { "description": "Null for personal Ark models without a configured output estimate; never a free billing quote.", "type": [ "object", "null" ], "additionalProperties": false, "required": [ "specifications", "meter", "estimator" ], "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "meter": { "const": "video_tokens" }, "estimator": { "const": "SeedancePixelsV1" } } }, { "type": "object", "properties": { "meter": { "const": "seconds" }, "estimator": { "const": "OutputSecondsV1" } } } ], "properties": { "meter": { "type": "string", "enum": [ "video_tokens", "seconds" ] }, "estimator": { "type": "string", "enum": [ "SeedancePixelsV1", "OutputSecondsV1" ] }, "specifications": { "$ref": "#/components/schemas/handler_operations_json_VideoOutputSchema" } } } } }, "VideoSchema": { "$ref": "#/components/schemas/handler_operations_json_VideoSchema" }, "VideoOutputSchema": { "$ref": "#/components/schemas/handler_operations_json_VideoOutputSchema" }, "VideoInputRule": { "$ref": "#/components/schemas/handler_operations_json_VideoInputRule" }, "VideoRemoteReferenceInput": { "type": "object", "additionalProperties": false, "required": [ "maximum_items", "maximum_bytes", "https", "data_mime_types", "roles", "role_required", "requires_text" ], "properties": { "maximum_items": { "type": "integer", "minimum": 1, "maximum": 32 }, "maximum_bytes": { "type": "integer", "minimum": 1 }, "https": { "const": true }, "data_mime_types": { "type": "array", "maxItems": 0, "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } }, "role_required": { "type": "boolean" }, "requires_text": { "const": false } } }, "VideoIntegerControl": { "$ref": "#/components/schemas/handler_operations_json_VideoIntegerControl" }, "VideoChoiceControl": { "$ref": "#/components/schemas/handler_operations_json_VideoChoiceControl" }, "VideoBooleanControl": { "$ref": "#/components/schemas/handler_operations_json_VideoBooleanControl" }, "VideoHttpsControl": { "$ref": "#/components/schemas/handler_operations_json_VideoHttpsControl" }, "VendorModelInput": { "$ref": "#/components/schemas/handler_operations_json_VendorModelInput" }, "VendorModel": { "$ref": "#/components/schemas/handler_operations_json_VendorModel" }, "OperatorInput": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "name", "role" ], "allOf": [ { "if": { "required": [ "issue_session" ], "properties": { "issue_session": { "const": false } } }, "then": { "not": { "required": [ "expires_in_seconds" ] } }, "else": { "required": [ "expires_in_seconds" ] } } ], "properties": { "issue_session": { "type": "boolean", "default": true, "description": "False requires Idempotency-Key and forbids expires_in_seconds." }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional workspace-level restriction within the organization." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "expires_in_seconds": { "type": "integer", "minimum": 60, "maximum": 31536000 } } }, "OperatorSessionInput": { "type": "object", "additionalProperties": false, "required": [ "expires_in_seconds" ], "properties": { "expires_in_seconds": { "type": "integer", "minimum": 60, "maximum": 31536000 } } }, "OperatorAuditPage": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorAuditEvent" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } }, "OperatorAuditEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "action", "actor_kind", "actor_operator_id", "target_operator_id", "target_session_id", "organization_id", "project_id", "before_role", "after_role", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "operator_created", "session_created", "session_revoked", "operator_revoked", "password_changed", "password_login_succeeded", "role_changed" ] }, "actor_kind": { "type": "string", "enum": [ "installation", "operator" ] }, "actor_operator_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Null only for installation actors." }, "target_operator_id": { "type": "string", "format": "uuid" }, "target_session_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Present for session creation", "revocation and password login; role changes apply to the member and have no target session.": null }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "before_role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "viewer", null ], "description": "Recorded original role for role_changed; null for other events." }, "after_role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "viewer", null ], "description": "Recorded new role for role_changed; null for other events." }, "created_at": { "type": "string", "format": "date-time" } } }, "ChatFunctionTool": { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "JSON Schema object forwarded to the configured provider.", "additionalProperties": true }, "strict": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "ChatToolChoice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 } } } }, "additionalProperties": true } ] }, "ChatResponseFormat": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "text" } }, "additionalProperties": true }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "json_object" } }, "additionalProperties": true }, { "type": "object", "required": [ "type", "json_schema" ], "properties": { "type": { "type": "string", "const": "json_schema" }, "json_schema": { "type": "object", "required": [ "name", "schema" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string" }, "strict": { "type": "boolean" }, "schema": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } ] }, "ResponsesRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "input" ], "properties": { "model": { "type": "string", "minLength": 1 }, "input": { "type": "string", "minLength": 1 }, "instructions": { "type": "string" }, "max_output_tokens": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "metadata": { "type": "object", "maxProperties": 16, "additionalProperties": { "type": "string", "maxLength": 512 } }, "user": { "type": "string", "maxLength": 512 }, "stream": { "type": "boolean", "default": false } } }, "ResponsesOutputText": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "output_text" }, "text": { "type": "string" }, "annotations": { "type": "array", "items": { "type": "object" } } }, "additionalProperties": true }, "ResponsesRefusal": { "type": "object", "required": [ "type", "refusal" ], "properties": { "type": { "type": "string", "const": "refusal" }, "refusal": { "type": "string" } }, "additionalProperties": true }, "ResponsesMessage": { "type": "object", "required": [ "type", "role", "content" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "message" }, "role": { "type": "string", "const": "assistant" }, "status": { "type": "string" }, "content": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponsesOutputText" }, { "$ref": "#/components/schemas/ResponsesRefusal" } ] } } }, "additionalProperties": true }, "ResponsesReasoning": { "type": "object", "required": [ "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "reasoning" }, "summary": { "type": "array" }, "encrypted_content": { "type": "string" } }, "additionalProperties": true }, "ResponsesResponse": { "type": "object", "required": [ "id", "object", "status", "model", "output" ], "properties": { "id": { "type": "string", "minLength": 1 }, "object": { "type": "string", "const": "response" }, "status": { "type": "string", "enum": [ "completed", "incomplete" ] }, "model": { "type": "string" }, "output": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponsesMessage" }, { "$ref": "#/components/schemas/ResponsesReasoning" } ] } }, "usage": { "type": "object", "required": [ "input_tokens", "output_tokens" ], "properties": { "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } }, "additionalProperties": true }, "EmbeddingRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "input" ], "properties": { "model": { "type": "string", "minLength": 1 }, "input": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "maxItems": 2048, "items": { "type": "string", "minLength": 1 } } ] }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "default": "float" }, "dimensions": { "type": "integer", "minimum": 1, "maximum": 65536 }, "user": { "type": "string", "maxLength": 512 } } }, "EmbeddingResponse": { "type": "object", "required": [ "object", "data", "model" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "required": [ "embedding" ], "properties": { "object": { "type": "string", "const": "embedding" }, "index": { "type": "integer", "minimum": 0 }, "embedding": { "oneOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] } }, "additionalProperties": true } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } }, "additionalProperties": true }, "PairedExperimentV1": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "mode", "opt_in", "authorization_ref", "candidates", "tasks", "repetitions", "acceptance", "cash_budget", "trials" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "mode": { "type": "string", "const": "paired_experiment" }, "opt_in": { "type": "boolean", "const": true }, "authorization_ref": { "type": "string", "minLength": 1 }, "candidates": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/components/schemas/BenchmarkCandidateV1" } }, "tasks": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BenchmarkTaskSnapshotV1" } }, "repetitions": { "type": "integer", "minimum": 1, "maximum": 100 }, "acceptance": { "$ref": "#/components/schemas/BenchmarkAcceptanceV1" }, "cash_budget": { "$ref": "#/components/schemas/BenchmarkBudgetV1" }, "trials": { "type": "array", "minItems": 2, "maxItems": 10000, "items": { "$ref": "#/components/schemas/BenchmarkTrialV1" } } } }, "BenchmarkCandidateV1": { "type": "object", "additionalProperties": false, "required": [ "id", "model_alias", "offer_revision" ], "properties": { "id": { "type": "string", "minLength": 1 }, "model_alias": { "type": "string", "minLength": 1 }, "offer_revision": { "type": "string", "minLength": 1 } } }, "BenchmarkTaskSnapshotV1": { "type": "object", "additionalProperties": false, "required": [ "id", "snapshot_sha256", "tools_sha256", "permissions_sha256", "acceptance_sha256" ], "properties": { "id": { "type": "string", "minLength": 1 }, "snapshot_sha256": { "type": "string", "pattern": "^[A-Fa-f0-9]{64}$" }, "tools_sha256": { "type": "string", "pattern": "^[A-Fa-f0-9]{64}$" }, "permissions_sha256": { "type": "string", "pattern": "^[A-Fa-f0-9]{64}$" }, "acceptance_sha256": { "type": "string", "pattern": "^[A-Fa-f0-9]{64}$" } } }, "BenchmarkAcceptanceV1": { "type": "object", "additionalProperties": false, "required": [ "max_latency_ms", "min_quality_basis_points" ], "properties": { "max_latency_ms": { "type": "integer", "minimum": 0 }, "min_quality_basis_points": { "type": "integer", "minimum": 0, "maximum": 10000 } } }, "BenchmarkBudgetV1": { "type": "object", "additionalProperties": false, "required": [ "currency", "limit_nanos" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "limit_nanos": { "type": "string", "pattern": "^[0-9]+$" } } }, "BenchmarkTrialV1": { "type": "object", "additionalProperties": false, "required": [ "task_snapshot_id", "candidate_id", "offer_revision", "repetition", "execution", "gateway_attempts", "costs" ], "properties": { "task_snapshot_id": { "type": "string", "minLength": 1 }, "candidate_id": { "type": "string", "minLength": 1 }, "offer_revision": { "type": "string", "minLength": 1 }, "repetition": { "type": "integer", "minimum": 1 }, "execution": { "$ref": "#/components/schemas/ExecutionRecordV1" }, "gateway_attempts": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BenchmarkGatewayAttemptEvidenceV1" } }, "quality_basis_points": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10000 }, "costs": { "$ref": "#/components/schemas/BenchmarkTrialCostsV1" } } }, "BenchmarkGatewayAttemptEvidenceV1": { "type": "object", "additionalProperties": false, "required": [ "attempt_id", "task_id", "model_alias", "currency", "cash_nanos", "api_equivalent_nanos" ], "properties": { "attempt_id": { "type": "string", "format": "uuid", "description": "Canonical Niu gateway attempt ID referenced by the execution spans." }, "task_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "cash_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "api_equivalent_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } } }, "BenchmarkTrialCostsV1": { "type": "object", "additionalProperties": false, "required": [ "currency", "api_equivalent_nanos", "evaluator_api_equivalent_nanos", "cash_nanos", "evaluator_cash_nanos", "complete" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "api_equivalent_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "evaluator_api_equivalent_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "cash_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "evaluator_cash_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "complete": { "type": "boolean", "const": true } } }, "PairedExperimentReportV1": { "type": "object", "required": [ "schema_version", "evidence_kind", "authorization_ref", "currency", "cash_budget_nanos", "total_cash_nanos", "api_equivalent_nanos", "candidates", "pairs", "paired_uncertainty_95", "diagnostics", "limits" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "evidence_kind": { "type": "string", "const": "paired_experiment" }, "authorization_ref": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "cash_budget_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "total_cash_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "api_equivalent_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "candidates": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/components/schemas/BenchmarkCandidateReportV1" } }, "pairs": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkPairResultV1" } }, "paired_uncertainty_95": { "$ref": "#/components/schemas/BenchmarkWilsonIntervalV1" }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkDiagnosticV1" } }, "limits": { "type": "array", "items": { "type": "string" } } } }, "BenchmarkCandidateReportV1": { "type": "object", "required": [ "candidate_id", "model_alias", "offer_revision", "runs", "complete_coverage_runs", "source_accepted_runs", "qualified_completions", "qualification_rate_basis_points", "api_equivalent_per_qualified_completion", "cash_per_qualified_completion", "api_equivalent_nanos", "evaluator_api_equivalent_nanos", "total_api_equivalent_nanos", "cash_nanos", "evaluator_cash_nanos", "total_cash_nanos", "observed_latency_p50_ms", "observed_latency_p95_ms" ], "properties": { "candidate_id": { "type": "string" }, "model_alias": { "type": "string" }, "offer_revision": { "type": "string" }, "runs": { "type": "integer" }, "complete_coverage_runs": { "type": "integer" }, "source_accepted_runs": { "type": "integer" }, "qualified_completions": { "type": "integer" }, "qualification_rate_basis_points": { "type": "integer" }, "api_equivalent_per_qualified_completion": { "oneOf": [ { "$ref": "#/components/schemas/BenchmarkExactRatioV1" }, { "type": "null" } ] }, "cash_per_qualified_completion": { "oneOf": [ { "$ref": "#/components/schemas/BenchmarkExactRatioV1" }, { "type": "null" } ] }, "api_equivalent_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "evaluator_api_equivalent_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "total_api_equivalent_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "cash_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "evaluator_cash_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "total_cash_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "observed_latency_p50_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "observed_latency_p95_ms": { "type": [ "integer", "null" ], "minimum": 0 } } }, "BenchmarkExactRatioV1": { "type": "object", "required": [ "numerator_nanos", "denominator" ], "properties": { "numerator_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "integer", "minimum": 1 } } }, "BenchmarkPairResultV1": { "type": "object", "required": [ "task_snapshot_id", "repetition", "result" ], "properties": { "task_snapshot_id": { "type": "string" }, "repetition": { "type": "integer", "minimum": 1 }, "result": { "type": "string", "enum": [ "candidate_a_wins", "candidate_b_wins", "tie", "both_fail_acceptance" ] } } }, "BenchmarkWilsonIntervalV1": { "type": "object", "required": [ "wins", "losses", "ties", "both_failed", "evaluated_pairs", "lower_95", "upper_95" ], "properties": { "wins": { "type": "integer", "minimum": 0 }, "losses": { "type": "integer", "minimum": 0 }, "ties": { "type": "integer", "minimum": 0 }, "both_failed": { "type": "integer", "minimum": 0 }, "evaluated_pairs": { "type": "integer", "minimum": 0 }, "lower_95": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "upper_95": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 } } }, "BenchmarkDiagnosticV1": { "type": "object", "required": [ "label", "rule", "summary", "evidence" ], "properties": { "label": { "type": "string", "const": "heuristic" }, "rule": { "type": "string" }, "summary": { "type": "string" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkEvidenceLinkV1" } } } }, "BenchmarkEvidenceLinkV1": { "type": "object", "required": [ "candidate_id", "task_snapshot_id", "record_id", "gateway_attempt_ids", "span_ids" ], "properties": { "candidate_id": { "type": "string" }, "task_snapshot_id": { "type": "string" }, "record_id": { "type": "string" }, "gateway_attempt_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "span_ids": { "type": "array", "items": { "type": "string" } } } }, "ExecutionCohortV1": { "type": "object", "required": [ "records_scanned", "tasks_scanned", "record_limit", "truncated", "coverage", "outcomes", "outcome_evidence", "accepted_completions", "work", "cost_evidence", "api_equivalent_by_currency", "configured_rate_cash_by_currency", "api_equivalent_per_accepted_completion", "configured_rate_cash_per_accepted_completion", "invoice_cash", "subscription_allocation_cash", "capacity" ], "properties": { "records_scanned": { "type": "integer", "minimum": 0 }, "tasks_scanned": { "type": "integer", "minimum": 0, "description": "Distinct task IDs grouped by source across scanned records." }, "record_limit": { "type": "integer", "const": 10000 }, "truncated": { "type": "boolean", "description": "True when more records exist beyond the scan limit." }, "coverage": { "$ref": "#/components/schemas/ExecutionCoverageCountsV1" }, "outcomes": { "$ref": "#/components/schemas/ExecutionOutcomeCountsV1" }, "outcome_evidence": { "$ref": "#/components/schemas/ExecutionOutcomeEvidenceCountsV1" }, "accepted_completions": { "type": "integer", "minimum": 0, "description": "Distinct source/task groups with deterministic validator or human acceptance evidence and no conflicting outcome evidence." }, "work": { "$ref": "#/components/schemas/ExecutionWorkCountsV1" }, "cost_evidence": { "$ref": "#/components/schemas/ExecutionCostEvidenceV1" }, "api_equivalent_by_currency": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyAmountV1" } }, "configured_rate_cash_by_currency": { "type": "array", "description": "Niu configured-rate settlement amounts; not Provider invoice amounts.", "items": { "$ref": "#/components/schemas/CurrencyAmountV1" } }, "api_equivalent_per_accepted_completion": { "type": "array", "items": { "$ref": "#/components/schemas/CostPerAcceptedCompletionV1" } }, "configured_rate_cash_per_accepted_completion": { "type": "array", "items": { "$ref": "#/components/schemas/CostPerAcceptedCompletionV1" } }, "invoice_cash": { "$ref": "#/components/schemas/NotImportedAccountingV1" }, "subscription_allocation_cash": { "$ref": "#/components/schemas/NotImportedAccountingV1" }, "capacity": { "$ref": "#/components/schemas/ExecutionCapacityV1" } } }, "ExecutionCoverageCountsV1": { "type": "object", "required": [ "complete", "partial", "unknown" ], "properties": { "complete": { "type": "integer", "minimum": 0 }, "partial": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 } } }, "ExecutionOutcomeCountsV1": { "type": "object", "required": [ "accepted", "rejected", "inconclusive", "conflicting", "unverified" ], "properties": { "accepted": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0 }, "inconclusive": { "type": "integer", "minimum": 0 }, "conflicting": { "type": "integer", "minimum": 0 }, "unverified": { "type": "integer", "minimum": 0 } } }, "ExecutionOutcomeEvidenceCountsV1": { "type": "object", "required": [ "agent_claim", "deterministic_validator", "human_acceptance" ], "properties": { "agent_claim": { "$ref": "#/components/schemas/AuthorityEvidenceCountsV1" }, "deterministic_validator": { "$ref": "#/components/schemas/AuthorityEvidenceCountsV1" }, "human_acceptance": { "$ref": "#/components/schemas/AuthorityEvidenceCountsV1" } } }, "AuthorityEvidenceCountsV1": { "type": "object", "required": [ "absent", "accepted", "rejected", "inconclusive", "conflicting", "evidence_events" ], "properties": { "absent": { "type": "integer", "minimum": 0 }, "accepted": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0 }, "inconclusive": { "type": "integer", "minimum": 0 }, "conflicting": { "type": "integer", "minimum": 0 }, "evidence_events": { "type": "integer", "minimum": 0 } } }, "ExecutionWorkCountsV1": { "type": "object", "required": [ "model_invocations", "tool_invocations", "attempts", "validation_spans", "human_interventions", "failed_spans", "cancelled_spans", "retry_links", "billable_roots_without_charge_references" ], "properties": { "model_invocations": { "type": "integer", "minimum": 0 }, "tool_invocations": { "type": "integer", "minimum": 0 }, "attempts": { "type": "integer", "minimum": 0 }, "validation_spans": { "type": "integer", "minimum": 0 }, "human_interventions": { "type": "integer", "minimum": 0 }, "failed_spans": { "type": "integer", "minimum": 0 }, "cancelled_spans": { "type": "integer", "minimum": 0 }, "retry_links": { "type": "integer", "minimum": 0 }, "billable_roots_without_charge_references": { "type": "integer", "minimum": 0 } } }, "ExecutionCostEvidenceV1": { "type": "object", "required": [ "unique_charge_references", "unique_attempt_references", "resolved_attempts", "unresolved_references", "attempts_without_cost_entries", "settled_cost_entries", "complete" ], "properties": { "unique_charge_references": { "type": "integer", "minimum": 0 }, "unique_attempt_references": { "type": "integer", "minimum": 0 }, "resolved_attempts": { "type": "integer", "minimum": 0 }, "unresolved_references": { "type": "integer", "minimum": 0 }, "attempts_without_cost_entries": { "type": "integer", "minimum": 0 }, "settled_cost_entries": { "type": "integer", "minimum": 0 }, "complete": { "type": "boolean", "description": "True only when all scanned records have complete coverage, every billable root and charge reference resolves to a settled scoped ledger entry, and the scan was not truncated." } } }, "CurrencyAmountV1": { "type": "object", "required": [ "currency", "amount_nanos" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount_nanos": { "type": "string", "pattern": "^[0-9]+$" } } }, "CostPerAcceptedCompletionV1": { "type": "object", "required": [ "currency", "numerator_nanos", "denominator", "evidence_complete" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "numerator_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "integer", "minimum": 1 }, "evidence_complete": { "type": "boolean", "const": true } } }, "NotImportedAccountingV1": { "type": "object", "required": [ "state", "totals_by_currency" ], "properties": { "state": { "type": "string", "const": "not_imported" }, "totals_by_currency": { "type": "array", "maxItems": 0 } } }, "ExecutionCapacityV1": { "type": "object", "required": [ "quota_observations", "task_attribution" ], "properties": { "quota_observations": { "type": "integer", "minimum": 0 }, "task_attribution": { "type": "string", "const": "unavailable" } } }, "ExecutionRecordV1": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "source", "record_id", "task_id", "coverage", "spans", "links", "outcomes" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "source": { "type": "string", "minLength": 1, "maxLength": 200 }, "record_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "task_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "coverage": { "type": "string", "enum": [ "complete", "partial", "unknown" ] }, "spans": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/ExecutionSpanV1" } }, "links": { "type": "array", "maxItems": 50000, "items": { "$ref": "#/components/schemas/ExecutionLinkV1" } }, "outcomes": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/ExecutionOutcomeV1" } }, "external_usage": { "$ref": "#/components/schemas/ExternalUsageV1", "description": "Optional source-reported usage estimate. It is not a settled Niu charge and is excluded from ledger cost calculations." } } }, "ExternalUsageV1": { "type": "object", "additionalProperties": false, "required": [ "authority", "agent_version", "request_count", "retry_count", "input_tokens", "output_tokens", "cache_read_tokens", "cache_creation_tokens", "cost_nanos", "currency" ], "properties": { "authority": { "type": "string", "const": "agent_reported_estimate" }, "agent_version": { "type": [ "string", "null" ], "maxLength": 200 }, "request_count": { "type": "integer", "minimum": 0 }, "retry_count": { "type": "integer", "minimum": 0, "description": "Source-reported retries; separate from Niu gateway attempt records." }, "input_tokens": { "type": [ "string", "null" ], "pattern": "^\\\\d{1,38}$" }, "output_tokens": { "type": [ "string", "null" ], "pattern": "^\\\\d{1,38}$" }, "cache_read_tokens": { "type": [ "string", "null" ], "pattern": "^\\\\d{1,38}$" }, "cache_creation_tokens": { "type": [ "string", "null" ], "pattern": "^\\\\d{1,38}$" }, "cost_nanos": { "type": [ "string", "null" ], "pattern": "^\\\\d{1,38}$", "description": "Estimated source cost in nanounits; not an invoice or settled charge." }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" } } }, "ExecutionSpanV1": { "type": "object", "additionalProperties": false, "required": [ "id", "kind" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "enum": [ "task", "agent", "step", "model_invocation", "tool_invocation", "attempt", "validation", "human_intervention", "checkpoint" ] }, "status": { "type": [ "string", "null" ], "enum": [ "running", "completed", "failed", "cancelled", "unknown", null ], "description": "Source-reported lifecycle status. Missing or null means unknown; Niu does not infer cancellation from a missing end time." }, "started_at_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "ended_at_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "requested_model": { "type": [ "string", "null" ], "maxLength": 200 }, "reported_model": { "type": [ "string", "null" ], "maxLength": 200, "description": "Provider-reported actual identity; absent means unknown." }, "charge_ref": { "type": [ "string", "null" ], "maxLength": 200, "description": "Reference to canonical accounting evidence; does not create another charge. An attempt UUID can resolve to an assigned Provider account." } } }, "ExecutionLinkV1": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "kind" ], "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 200 }, "to": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "enum": [ "contains", "delegates", "depends_on", "fallbacks", "retries", "resumes" ], "description": "A fallback edge points from a model invocation to its explicitly selected replacement invocation." } } }, "ExecutionOutcomeV1": { "type": "object", "additionalProperties": false, "required": [ "span_id", "evidence_id", "authority", "result" ], "properties": { "span_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "evidence_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "authority": { "type": "string", "enum": [ "agent_claim", "deterministic_validator", "human_acceptance" ] }, "result": { "type": "string", "enum": [ "accepted", "rejected", "inconclusive" ] } } }, "ExecutionAccountLinkV1": { "type": "object", "required": [ "span_id", "attempt_id", "account_id", "provider", "plan" ], "properties": { "span_id": { "type": "string" }, "attempt_id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "plan": { "type": "string" } } }, "ExecutionTaskLinkV1": { "type": "object", "required": [ "id", "task_id", "source", "record_id", "imported_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string" }, "source": { "type": "string" }, "record_id": { "type": "string" }, "imported_at": { "type": "string", "format": "date-time" } } }, "AccountInput": { "type": "object", "required": [ "provider", "plan", "authentication_mode", "billing_mode", "credential_reference", "concurrency_limit" ], "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 100 }, "plan": { "type": "string", "minLength": 1, "maxLength": 200 }, "authentication_mode": { "type": "string", "enum": [ "api_key", "oauth_refresh" ] }, "billing_mode": { "type": "string", "enum": [ "metered_api", "subscription" ] }, "credential_reference": { "type": "string", "description": "Opaque env or secret reference, never the secret value." }, "concurrency_limit": { "type": "integer", "minimum": 1, "maximum": 10000 } } }, "QuotaObservationV1": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "window_key", "unit", "observed_at_ms", "valid_until_ms", "resets_at_ms", "source" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "window_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "unit": { "type": "string", "enum": [ "tokens", "requests", "millionths_of_window" ] }, "remaining": { "type": [ "integer", "null" ], "minimum": 0 }, "maximum": { "type": [ "integer", "null" ], "minimum": 0 }, "observed_at_ms": { "type": "integer", "minimum": 0 }, "valid_until_ms": { "type": "integer", "minimum": 1 }, "resets_at_ms": { "type": "integer", "minimum": 1 }, "source": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "QuotaWindowViewV1": { "type": "object", "required": [ "window_key", "unit", "remaining", "maximum", "observed_at_ms", "valid_until_ms", "resets_at_ms", "source", "previous_remaining", "previous_observed_at_ms", "fresh" ], "properties": { "window_key": { "type": "string" }, "unit": { "type": "string", "enum": [ "tokens", "requests", "millionths_of_window" ] }, "remaining": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "maximum": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "observed_at_ms": { "type": "integer" }, "valid_until_ms": { "type": "integer" }, "resets_at_ms": { "type": "integer" }, "source": { "type": "string" }, "previous_remaining": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "previous_observed_at_ms": { "type": [ "integer", "null" ] }, "fresh": { "type": "boolean" } } }, "NameInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "WorkspaceInput": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "organization_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "Workspace": { "type": "object", "required": [ "id", "name", "slug", "route_slug", "slug_aliases", "organization_id", "organization_name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Workspace ID used to address this workspace." }, "name": { "type": "string", "description": "Workspace name." }, "slug": { "type": "string", "maxLength": 81, "description": "Stable readable workspace slug." }, "slug_aliases": { "type": "array", "items": { "type": "string" }, "description": "Previously issued workspace slugs." }, "route_slug": { "type": "string", "deprecated": true, "maxLength": 81, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Immutable globally unique routing reference assigned by the backend. Renaming preserves it. Use only in routes", "never as a display label or authorization grant.": null }, "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "is_default": { "type": "boolean" }, "created_at_ms": { "type": "integer", "format": "int64", "description": "Workspace creation time in Unix milliseconds." }, "active_key_count": { "type": "integer", "format": "int64", "minimum": 0, "description": "Keys that are neither revoked nor expired." }, "requests_30d": { "type": "integer", "format": "int64", "minimum": 0, "description": "Request operations created in the past 30 days; retries are counted once." }, "requests_by_day": { "type": "array", "description": "Request operations per UTC calendar day for today and the previous 29 days, including zero days.", "items": { "type": "object", "required": [ "start_ms", "request_count" ], "properties": { "start_ms": { "type": "integer", "format": "int64" }, "request_count": { "type": "integer", "format": "int64", "minimum": 0 } } } }, "last_request_at_ms": { "type": "integer", "format": "int64", "nullable": true, "description": "Most recent request operation creation time in Unix milliseconds." } } }, "WorkspaceKey": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKey" }, "KeyInput": { "$ref": "#/components/schemas/handler_operations_json_KeyInput" }, "handler_operations_json_VideoBillingQuantity": { "type": "object", "additionalProperties": false, "required": [ "numerator", "denominator" ], "properties": { "numerator": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "handler_operations_json_ModelRoutePool": { "type": "object", "required": [ "alias", "organization_id", "enabled", "revision", "candidates" ], "properties": { "alias": { "type": "string" }, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "public_catalog": { "type": "boolean" }, "billing_mode": { "type": "string", "enum": [ "pool_tariff", "candidate_tariff" ] }, "enabled": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "candidates": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "object", "required": [ "alias", "priority", "weight", "enabled" ], "properties": { "alias": { "type": "string" }, "priority": { "type": "integer", "minimum": -1000, "maximum": 1000 }, "weight": { "type": "integer", "minimum": 1, "maximum": 10000 }, "enabled": { "type": "boolean" } } } }, "rules": { "type": "array", "maxItems": 32, "items": { "type": "object" } }, "default_action": { "type": "string", "enum": [ "candidates", "reject" ] } } }, "handler_operations_json_VideoIntentIndexItem": { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "expires_at_ms", "content_state" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "expires_at_ms": { "description": "Immutable original intent deadline. A bound turn may expire or delete content earlier; content_state determines availability.", "type": "string", "pattern": "^[0-9]+$" }, "content_state": { "type": "string", "enum": [ "retained", "deleted", "expired" ] } } }, "handler_operations_json_VideoSubmissionIntent": { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "original_key_id", "key_id", "model", "funding_mode", "request", "content_state", "expires_at_ms", "submission_state", "job", "session_binding" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "expires_at_ms": { "description": "Immutable original intent deadline. A bound turn may expire or delete content earlier; content_state determines availability.", "type": "string", "pattern": "^[0-9]+$" }, "content_state": { "type": "string", "enum": [ "retained", "deleted", "expired" ] }, "original_key_id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string", "format": "uuid", "description": "Available active rotation-lineage key with the model grant, otherwise the original saved key. Context only; current action authorization remains required and no secret is returned." }, "model": { "type": "string" }, "funding_mode": { "type": "string", "enum": [ "owner_funded", "customer" ] }, "request": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_VideoIntentRequest" }, { "type": "null" } ] }, "submission_state": { "type": "string", "enum": [ "saved", "not_dispatched", "dispatched" ], "description": "Dispatch and job status are read from one bounded read-only database snapshot. not_dispatched means original preparation has no recorded dispatch; it never grants a fresh submission right." }, "job": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "object", "model", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "video.job" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "submission_unknown", "queued", "running", "succeeded", "failed", "unknown", "reconciliation_required" ] } } }, { "type": "null" } ] }, "session_binding": { "type": [ "object", "null" ], "description": "Original actor-private session and turn binding, if any. Internal routing references only; never render these IDs. Remains available after content deletion or expiry and does not authorize inference. Explicit null means no saved binding; older gateways with no field must not be interpreted as confirmed absence.", "required": [ "session_id", "turn_id" ], "additionalProperties": false, "properties": { "session_id": { "type": "string", "format": "uuid" }, "turn_id": { "type": "string", "format": "uuid" } } } } }, "handler_operations_json_VideoIntentRequest": { "type": "object", "required": [ "model", "content" ], "additionalProperties": true, "description": "Validated original Niu request with configured defaults materialized at save time, at most 60 KiB JSON. Supports text, Provider-owned image/audio/video IDs, or workspace-owned image IDs with explicit consent. Provider/local reference families cannot be mixed. Only scoped metadata is read at save; no bytes, upload, Provider query, processing readiness or dispatch. No private Provider URI or schema placeholder is persisted. URL, inline data, ingested_image and callbacks are unsupported. Current model schema, policy and funding mode apply; actual live binding, Active readiness and inspection are rechecked only at explicit submit.", "properties": { "model": { "type": "string" }, "content": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "provider_asset" ], "properties": { "type": { "const": "provider_asset" }, "provider_asset": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Canonical nonnil Niu reference." } } }, "role": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Explicit configured role; null, whitespace padding and control characters are invalid." } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "workspace_asset" ], "properties": { "type": { "const": "workspace_asset" }, "workspace_asset": { "type": "object", "additionalProperties": false, "required": [ "asset_id", "consent_to_process" ], "properties": { "asset_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Canonical nonnil Niu reference." }, "consent_to_process": { "type": "boolean", "const": true } } }, "role": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Explicit configured role; null, whitespace padding and control characters are invalid." } } } ] }, "maxItems": 32 } } }, "handler_operations_json_VideoComposerDraftResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_VideoComposerDraftState" } } }, "handler_operations_json_VideoComposerDraftState": { "type": "object", "additionalProperties": false, "required": [ "payload", "revision", "expires_at_ms", "content_state" ], "properties": { "payload": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_VideoComposerDraftPayload" }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expires_at_ms": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "content_state": { "type": "string", "enum": [ "empty", "retained", "expired" ] } } }, "handler_operations_json_VideoComposerDraftPayload": { "type": "object", "additionalProperties": false, "required": [ "prompt", "controls", "references" ], "properties": { "keyId": { "oneOf": [ { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, { "type": "null" } ] }, "sessionId": { "oneOf": [ { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, { "type": "null" } ] }, "model": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512 }, "prompt": { "type": "string", "maxLength": 12000 }, "controls": { "type": "object", "additionalProperties": false, "required": [], "properties": { "duration": { "oneOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string", "maxLength": 256 } ] }, "seed": { "oneOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string", "maxLength": 256 } ] }, "frames_per_second": { "oneOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string", "maxLength": 256 } ] }, "resolution": { "type": "string", "maxLength": 256 }, "ratio": { "type": "string", "maxLength": 256 }, "omni_reference_task_type": { "type": "string", "maxLength": 256 }, "watermark": { "type": "boolean" }, "camera_fixed": { "type": "boolean" }, "return_last_frame": { "type": "boolean" } } }, "references": { "type": "array", "maxItems": 32, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "provider_asset" ], "properties": { "type": { "const": "provider_asset" }, "provider_asset": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } }, "role": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Optional nonempty role matching the existing VideoIntent reference grammar; explicit null is rejected." } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "workspace_asset" ], "properties": { "type": { "const": "workspace_asset" }, "workspace_asset": { "type": "object", "additionalProperties": false, "required": [ "asset_id", "consent_to_process" ], "properties": { "asset_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "consent_to_process": { "const": true } } }, "role": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Optional nonempty role matching the existing VideoIntent reference grammar; explicit null is rejected." } } } ] } } } }, "handler_operations_json_VideoComposerDraftUpdate": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740989 }, "payload": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_VideoComposerDraftPayload" }, { "type": "null" } ] } } }, "handler_operations_json_ChatDraftResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_ChatDraftState" } } }, "handler_operations_json_ChatDraftState": { "type": "object", "required": [ "payload", "revision" ], "properties": { "payload": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_ChatDraftPayload" }, { "type": "null" } ] }, "revision": { "type": "integer", "format": "int64", "minimum": 0, "description": "Zero before the first saved draft; integer revision, not a string." } } }, "handler_operations_json_ChatDraftPayload": { "type": "object", "additionalProperties": false, "required": [ "prompt", "models", "attachments", "settings" ], "properties": { "sessionId": { "oneOf": [ { "type": "string", "format": "uuid", "description": "Optional saved conversation belonging to this owner and workspace." }, { "type": "null" } ] }, "prompt": { "type": "string", "maxLength": 12000 }, "models": { "type": "array", "maxItems": 4, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "description": "Nonblank and at most 512 UTF-8 bytes; saving a draft does not invoke or grant access to this model." } }, "attachments": { "type": "array", "maxItems": 4, "items": { "$ref": "#/components/schemas/handler_operations_json_ChatDraftAttachment" } }, "settings": { "$ref": "#/components/schemas/handler_operations_json_ChatDraftSettings" } } }, "handler_operations_json_ChatDraftAttachment": { "type": "object", "additionalProperties": false, "required": [ "name", "type", "content" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "At most 1024 UTF-8 bytes." }, "type": { "type": "string", "enum": [ "image", "text" ] }, "content": { "type": "string", "description": "At most 6291456 UTF-8 bytes; stored text, not a server-fetched URL." } } }, "handler_operations_json_ChatDraftSettings": { "type": "object", "additionalProperties": false, "required": [ "systemPrompt", "maxTokens", "temperature", "logPayloads" ], "properties": { "systemPrompt": { "type": "string", "maxLength": 12000 }, "maxTokens": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "logPayloads": { "type": "boolean" } } }, "handler_operations_json_ChatDraftUpdate": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "format": "int64", "description": "Exact last observed integer revision. Negative or stale values return 409; use zero for initial creation." }, "payload": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_ChatDraftPayload" }, { "type": "null" } ] } }, "description": "An omitted or null payload clears the draft while retaining its revision." }, "handler_operations_json_GenerationArtifactCapture": { "type": "object", "additionalProperties": false, "required": [ "id", "task_id", "kind", "status", "asset_id", "availability", "failure_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "video", "last_frame" ] }, "status": { "enum": [ "preparing", "stored", "failed" ] }, "asset_id": { "type": [ "string", "null" ], "format": "uuid" }, "availability": { "enum": [ "retained", "deleted", "not_stored" ] }, "failure_code": { "enum": [ null, "delivery_failed", "authorization_changed", "invalid_media", "capacity_exceeded", "storage_unavailable", "encryption_unavailable" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "handler_operations_json_VideoJobBilling": { "type": [ "object", "null" ], "additionalProperties": false, "description": "Saved estimated quantity priced using the original customer tariff. Neither confirmed usage, maximum liability nor a final charge. Owner-funded or unpriceable amounts remain null.", "required": [ "meter", "quantity", "provenance", "currency", "amount_nanos" ], "properties": { "meter": { "type": "string" }, "quantity": { "$ref": "#/components/schemas/handler_operations_json_VideoBillingQuantity" }, "provenance": { "type": "string", "enum": [ "Estimate" ] }, "currency": { "type": [ "string", "null" ] }, "amount_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "unit_code": { "type": [ "string", "null" ] }, "amount_atoms": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } } }, "handler_operations_json_VideoTransportTimings": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "lifecycle" ], "properties": { "has_more": { "type": "boolean" }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "phase", "started_unix_ms", "elapsed_ms", "outcome", "upstream_http_status", "upstream_error_code", "upstream_request_id" ], "properties": { "phase": { "type": "string", "enum": [ "submission", "query", "result" ] }, "started_unix_ms": { "type": "integer", "minimum": 0 }, "elapsed_ms": { "type": "integer", "minimum": 0 }, "outcome": { "type": "string", "enum": [ "received", "unavailable" ] }, "upstream_http_status": { "type": [ "integer", "null" ] }, "upstream_error_code": { "type": [ "string", "null" ] }, "upstream_request_id": { "type": [ "string", "null" ] } } } }, "lifecycle": { "type": "object", "additionalProperties": false, "required": [ "source", "submitted_unix_ms", "observations", "conflicting_terminal" ], "properties": { "source": { "type": "string", "enum": [ "gateway_observation" ] }, "submitted_unix_ms": { "type": [ "integer", "null" ] }, "conflicting_terminal": { "type": "boolean" }, "observations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "status", "observed_unix_ms" ], "properties": { "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "unknown" ] }, "observed_unix_ms": { "type": "integer" } } } } } } } }, "handler_operations_json_GenerationsVideoSessionSummary": { "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" }, "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", "owner" ] }, "handler_operations_json_GenerationsChatSessionSummary": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "category": { "type": "string", "const": "chat" }, "title": { "type": [ "string", "null" ] }, "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" }, "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", "owner" ] }, "handler_operations_json_GenerationsVideoSession": { "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": { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoTurn" } }, "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" ] }, "handler_operations_json_GenerationsVideoTurn": { "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": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoInstruction" }, { "type": "null" } ] }, "content_expires_at": { "type": "string", "format": "date-time" }, "task_id": { "type": [ "string", "null" ], "format": "uuid" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoTaskReference" }, { "type": "null" } ] }, "intent": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationsVideoIntentReference" }, { "type": "null" } ] } }, "required": [ "id", "sequence", "created_at", "content_state", "instruction", "content_expires_at", "task_id", "task", "intent" ] }, "handler_operations_json_GenerationsVideoInstruction": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "video" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 61440 } }, "required": [ "kind", "prompt" ] }, "handler_operations_json_GenerationsVideoTaskReference": { "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" ] }, "handler_operations_json_GenerationsVideoIntentReference": { "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." }, "handler_operations_json_GenerationsChatSession": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "category": { "type": "string", "const": "chat" }, "title": { "type": [ "string", "null" ] }, "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" }, "owner": { "type": "string", "description": "Internal authenticated actor reference; never a product display label." }, "turns": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_GenerationsChatTurn" } } }, "required": [ "id", "workspace_id", "category", "title", "revision", "archived", "created_at", "updated_at", "owner", "turns" ] }, "handler_operations_json_GenerationsChatTurn": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^chat-turn:[0-9a-f]{64}$", "description": "Read-only derived reference from scoped session identity, sequence and retained instruction digest. Changing legacy instruction/order changes the reference; comparison output updates do not." }, "kind": { "type": "string", "const": "chat" }, "sequence": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "created_at": { "type": "null" }, "content_state": { "type": "string", "enum": [ "retained", "missing" ] }, "instruction": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationsChatInstruction" }, { "type": "null" } ] }, "content_expires_at": { "type": "null" }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_GenerationsChatBranch" } } }, "required": [ "id", "kind", "sequence", "created_at", "content_state", "instruction", "content_expires_at", "branches" ] }, "handler_operations_json_GenerationsChatInstruction": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "chat" }, "prompt": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" } }, "required": [ "name", "type", "content" ] } } }, "required": [ "kind", "prompt" ] }, "handler_operations_json_GenerationsChatBranch": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string" }, "content": { "type": "string" }, "elapsedMs": { "type": "number" }, "phase": { "type": "string", "enum": [ "connecting", "streaming", "complete", "failed", "cancelled" ], "description": "Saved client comparison phase, never authoritative task state or upstream cancellation." }, "promptTokens": { "type": [ "number", "null" ] }, "completionTokens": { "type": [ "number", "null" ] }, "totalTokens": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "customerChargeNanos": { "type": [ "string", "null" ] }, "customerChargeCurrency": { "type": [ "string", "null" ] }, "customerChargeStatus": { "type": "string", "enum": [ "charged", "owner_funded", "pending", "unpriced", "not_charged", "unknown" ] }, "task": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_GenerationsChatTaskReference" }, { "type": "null" } ] } }, "required": [ "task" ] }, "handler_operations_json_GenerationsChatTaskReference": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "const": "chat" }, "model": { "type": "string" }, "execution": { "type": "string", "enum": [ "not_sent", "may_have_executed", "confirmed_completed", "confirmed_not_executed" ] } }, "required": [ "id", "kind", "model", "execution" ] }, "handler_operations_json_WorkspaceSpendingSummary": { "type": "object", "required": [ "currency", "limit_nanos", "revision", "committed_nanos" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "limit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." }, "committed_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." } } }, "handler_operations_json_WorkspaceSpendingInput": { "type": "object", "required": [ "limit_nanos", "expected_revision" ], "properties": { "limit_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." }, "expected_revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." } }, "additionalProperties": false }, "handler_operations_json_WorkspaceSpendingHistory": { "type": "object", "required": [ "currency", "revision", "limit_nanos", "recorded_at", "source", "actor_kind", "actor_name" ], "properties": { "currency": { "type": "string" }, "revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." }, "limit_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact nonnegative decimal integer, within signed 64-bit range." }, "recorded_at": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": "string" }, "actor_kind": { "type": [ "string", "null" ] }, "actor_name": { "type": [ "string", "null" ] } } }, "handler_operations_json_GatewayActivity": { "type": "object", "additionalProperties": false, "required": [ "attempt_id", "operation_id", "api_key_id", "key_name", "task_evidence", "model", "provider_model", "created_at", "execution", "output_guardrail_outcome", "usage_confidence" ], "properties": { "attempt_id": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string", "format": "uuid" }, "retry": { "type": [ "object", "null" ], "description": "Durable bounded retry policy and chain position; null for requests outside this policy. Internal correlation identifiers must not be displayed in product UI.", "properties": { "ordinal": { "type": "integer", "minimum": 1, "maximum": 2 }, "predecessor_attempt_id": { "type": [ "string", "null" ], "format": "uuid" }, "maximum_attempts": { "type": "integer", "const": 2 }, "policy_revision": { "type": "string" } }, "required": [ "ordinal", "predecessor_attempt_id", "maximum_attempts", "policy_revision" ] }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "key_name": { "type": [ "string", "null" ] }, "task_id": { "type": [ "string", "null" ], "maxLength": 200 }, "task_evidence": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "execution_id", "source", "record_id", "coverage", "outcomes" ], "properties": { "execution_id": { "type": "string", "format": "uuid", "description": "Historical correlation reference; external execution imports are no longer supported." }, "source": { "type": "string" }, "record_id": { "type": "string" }, "coverage": { "type": "string", "enum": [ "complete", "partial", "unknown" ] }, "outcomes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "authority", "result" ], "properties": { "authority": { "type": "string", "enum": [ "agent_claim", "deterministic_validator", "human_acceptance" ] }, "result": { "type": "string", "enum": [ "accepted", "rejected", "inconclusive" ] } } } } } } ] }, "model": { "type": "string", "description": "Public model alias requested through Niu." }, "request_kind": { "type": "string", "enum": [ "video", "inference" ], "description": "Durable video recovery-route identity; model names and pricing alone do not establish video kind." }, "provider_model": { "type": [ "string", "null" ], "description": "Provider-reported model identity when explicitly returned, including identity-validated video query responses. Missing video model fields remain unknown and are never filled from configured route mappings. It is distinct from the public model alias." }, "created_at": { "type": "string", "format": "date-time" }, "dispatched_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "minimum": 0, "description": "Legacy dispatch-to-completion attempt interval. Null when completion was first confirmed by supplemental reconciliation; confirmation delay is not generation latency. Prefer timing.total_ms when timing.complete is true for the full measured gateway request interval; interrupted timing must not be treated as completed latency." }, "execution": { "type": "string" }, "output_guardrail_outcome": { "type": [ "string", "null" ], "enum": [ "allowed", "redacted", "blocked", "indeterminate", null ], "description": "Immutable recorded output inspection. Null means no recorded outcome, not successful delivery or content protection. Blocked/indeterminate output is withheld without cancelling incurred usage or customer charges." }, "usage_confidence": { "type": "string" }, "prompt_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "completion_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Explicitly reported subset of prompt tokens. Null means unknown." }, "cached_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Explicitly reported subset of prompt tokens. Null means unknown." }, "reasoning_output_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Explicitly reported subset of completion tokens. Null means unknown." }, "admission_denial": { "description": "Recorded Gateway request-rate rejection for a retained unsent attempt. Null includes historical records and unavailable diagnostics. The captured requested key name is provenance, not dispatch or billing authority. This is independent of upstream failure evidence.", "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "kind", "http_status", "requested_key_name", "key_name_source", "recorded_at" ], "properties": { "kind": { "type": "string", "enum": [ "key_request_rate_disabled", "key_request_rate_exceeded" ] }, "http_status": { "type": "integer", "enum": [ 429 ], "description": "Gateway admission HTTP status, never an upstream status." }, "requested_key_name": { "type": "string", "description": "Name captured from the authorized key at admission; never inferred from current configuration." }, "key_name_source": { "type": "string", "enum": [ "captured_at_admission" ] }, "recorded_at": { "type": "string", "format": "date-time" } } } ] }, "failure": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "kind", "upstream_http_status" ], "properties": { "kind": { "type": "string", "enum": [ "upstream_http_error", "upstream_region_unavailable", "upstream_timeout", "upstream_connection_error", "upstream_transport_error", "upstream_invalid_response", "response_stream_cancelled" ], "description": "response_stream_cancelled means the response body was dropped before terminal or explicit upstream failure handling. It does not identify who cancelled delivery or prove upstream nonexecution." }, "upstream_http_status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599, "description": "Recorded upstream non-success status. Null for transport, invalid-response or response-cancellation classifications. This is independent of the HTTP status delivered by Niu." }, "transport_phase": { "type": [ "string", "null" ], "enum": [ "connection", "request", null ], "description": "Observed transport stage, not execution certainty. Connection does not distinguish DNS/TCP/TLS; historical unknown stays null." } } } ], "description": "Content-free immutable upstream or delivery diagnosis, independent of payload retention. Null means no recorded classification, not a successful request. Does not establish execution, usage or billing certainty." }, "finish_reasons": { "type": [ "array", "null" ], "description": "Explicit allowlisted terminal observations, independent of payload retention. Chat indexes identify choices. For nonstreaming Responses interruptions, index zero identifies the whole response; max_output_tokens maps to length and content_filter maps to content_filter. Completed Responses status alone supplies no stop reason. Null means unknown; finish reasons do not establish task success or customer delivery.", "minItems": 1, "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": [ "index", "reason" ], "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "reason": { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] } } } }, "customer_charge_currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "customer_charge_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "customer_unit_charge": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "definition_revision", "name", "display_precision", "atoms_per_unit", "charged_atoms", "restored_atoms", "net_atoms" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "charged_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "restored_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "net_atoms": { "type": "string", "pattern": "^[0-9]+$" } } }, "customer_charge_status": { "type": "string", "enum": [ "charged", "owner_funded", "pending", "unpriced", "not_charged" ] }, "timing": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "dispatch_ms", "headers_ms", "first_output_ms", "total_ms", "complete", "http_status" ], "description": "Monotonic millisecond offsets from gateway request handling. Missing observations stay null; values do not include client network delivery after body consumption. First output means a meaningful streamed Chat event, not a role, keepalive or usage event.", "properties": { "dispatch_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "headers_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "first_output_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "total_ms": { "type": "integer", "minimum": 0 }, "complete": { "type": "boolean", "description": "The response body reached EOF without a stream error; not a claim of successful inference." }, "http_status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 } } } ] } } }, "handler_operations_json_GatewayRequestMetadata": { "type": "object", "required": [ "attempt_id", "reference", "operation_id", "api_key_id", "key_name", "task_id", "provider_model", "output_guardrail_outcome", "customer_charge_currency", "task_evidence", "request_kind", "model", "created_at", "execution", "usage_confidence", "customer_charge_status", "dispatched_at", "completed_at", "duration_ms", "prompt_tokens", "completion_tokens", "cache_write_input_tokens", "cached_input_tokens", "reasoning_output_tokens", "customer_charge_nanos", "timing", "failure", "finish_reasons" ], "properties": { "reference": { "type": "string", "description": "Stable public run reference for customer-facing links" }, "attempt_id": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string", "format": "uuid" }, "retry": { "type": [ "object", "null" ], "description": "Durable bounded retry policy and chain position; null for requests outside this policy. Internal correlation identifiers must not be displayed in product UI.", "properties": { "ordinal": { "type": "integer", "minimum": 1, "maximum": 2 }, "predecessor_attempt_id": { "type": [ "string", "null" ], "format": "uuid" }, "maximum_attempts": { "type": "integer", "const": 2 }, "policy_revision": { "type": "string" } }, "required": [ "ordinal", "predecessor_attempt_id", "maximum_attempts", "policy_revision" ] }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "key_name": { "type": [ "string", "null" ] }, "task_id": { "type": [ "string", "null" ] }, "provider_model": { "type": [ "string", "null" ] }, "output_guardrail_outcome": { "type": [ "string", "null" ] }, "customer_charge_currency": { "type": [ "string", "null" ] }, "task_evidence": { "description": "Legacy optional correlation metadata; not request content or a complete agent trace." }, "request_kind": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string" }, "execution": { "type": "string" }, "usage_confidence": { "type": "string" }, "customer_charge_status": { "type": "string" }, "dispatched_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "description": "Legacy dispatch-to-completion interval, not complete gateway latency. Null when completion was first confirmed by supplemental reconciliation; confirmation delay is not generation latency. Use timing for independently observed delivery measurements." }, "prompt_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "completion_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cached_input_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_output_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "customer_charge_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Customer retail charge only. Null is unknown or absent, never an upstream expense fallback." }, "customer_unit_charge": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "definition_revision", "name", "display_precision", "atoms_per_unit", "charged_atoms", "restored_atoms", "net_atoms" ], "properties": { "definition_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "name": { "type": "string" }, "display_precision": { "type": "integer", "minimum": 0, "maximum": 9 }, "atoms_per_unit": { "type": "string", "const": "1000000000" }, "charged_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "restored_atoms": { "type": "string", "pattern": "^[0-9]+$" }, "net_atoms": { "type": "string", "pattern": "^[0-9]+$" } } }, "timing": { "type": [ "object", "null" ], "required": [ "dispatch_ms", "headers_ms", "first_output_ms", "http_status", "total_ms", "complete" ], "properties": { "dispatch_ms": { "type": [ "integer", "null" ] }, "headers_ms": { "type": [ "integer", "null" ] }, "first_output_ms": { "type": [ "integer", "null" ] }, "http_status": { "type": [ "integer", "null" ] }, "total_ms": { "type": "integer" }, "complete": { "type": "boolean" } } }, "admission_denial": { "description": "Recorded Gateway request-rate rejection for a retained unsent attempt. Null includes historical records and unavailable diagnostics. The captured requested key name is provenance, not dispatch or billing authority. This is independent of upstream failure evidence.", "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "kind", "http_status", "requested_key_name", "key_name_source", "recorded_at" ], "properties": { "kind": { "type": "string", "enum": [ "key_request_rate_disabled", "key_request_rate_exceeded" ] }, "http_status": { "type": "integer", "enum": [ 429 ], "description": "Gateway admission HTTP status, never an upstream status." }, "requested_key_name": { "type": "string", "description": "Name captured from the authorized key at admission; never inferred from current configuration." }, "key_name_source": { "type": "string", "enum": [ "captured_at_admission" ] }, "recorded_at": { "type": "string", "format": "date-time" } } } ] }, "failure": { "type": [ "object", "null" ], "required": [ "kind", "upstream_http_status" ], "properties": { "kind": { "type": "string" }, "upstream_http_status": { "type": [ "integer", "null" ] }, "transport_phase": { "type": [ "string", "null" ], "enum": [ "connection", "request", null ], "description": "Observed transport stage, not execution certainty. Connection does not distinguish DNS/TCP/TLS; historical unknown stays null." } } }, "finish_reasons": { "type": [ "array", "null" ], "items": { "type": "object", "required": [ "index", "reason" ], "properties": { "index": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "handler_operations_json_KeyRequestRatePolicy": { "type": "object", "required": [ "requests_per_minute", "revision" ], "properties": { "requests_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyRequestRateRequestLimit" }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } }, "handler_operations_json_KeyRequestRateRequestLimit": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000, "description": "Maximum dispatches per rolling 60 seconds; null is unlimited and zero denies dispatch." }, "handler_operations_json_KeyConcurrencyPolicy": { "type": "object", "required": [ "max_concurrent_requests", "revision", "active_requests" ], "properties": { "max_concurrent_requests": { "$ref": "#/components/schemas/handler_operations_json_KeyConcurrencyConcurrencyLimit" }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "active_requests": { "type": "integer", "minimum": 0, "description": "Current unresolved dispatch count shared across rotations; includes work admitted before configuration." } } }, "handler_operations_json_KeyConcurrencyConcurrencyLimit": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10000, "description": "Maximum unresolved dispatched requests; null is unlimited and zero denies dispatch." }, "handler_operations_json_KeyTokenRatePolicy": { "type": "object", "required": [ "tokens_per_minute", "revision", "snapshot_at", "known_tokens", "reserved_tokens", "unbounded_requests", "committed_tokens" ], "properties": { "tokens_per_minute": { "$ref": "#/components/schemas/handler_operations_json_KeyTokenRateTokenRateLimit" }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "snapshot_at": { "type": "string", "format": "date-time" }, "known_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Known provider usage completed within 60 seconds." }, "reserved_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Estimates retained for unresolved usage, without time-based expiry." }, "unbounded_requests": { "type": "integer", "minimum": 0, "description": "Unknown dispatched requests without a saved bound." }, "committed_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Known plus reserved tokens, or null when unbounded requests prevent a complete total." } } }, "handler_operations_json_KeyTokenRateTokenRateLimit": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000000000, "description": "Token budget includes unresolved reservations plus provider-reported usage completed in the last 60 seconds. Null is unlimited; zero denies dispatch." }, "handler_operations_json_RetailSelection": { "type": "object", "additionalProperties": false, "properties": { "price_id": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "currency": { "type": "string" }, "version": { "type": "string", "pattern": "^[0-9]+$" }, "current_standard_revision": { "type": "string", "format": "uuid" }, "baseline_revision": { "type": "string", "format": "uuid" }, "promotion_revision": { "type": [ "string", "null" ], "format": "uuid" }, "promotion_scope": { "type": [ "string", "null" ], "enum": [ "global", "customer", null ] }, "selected_at": { "type": "string", "pattern": "^[0-9]+$" }, "schedule": { "$ref": "#/components/schemas/handler_operations_json_RetailSchedule" } }, "required": [ "price_id", "model_alias", "currency", "version", "current_standard_revision", "baseline_revision", "promotion_revision", "promotion_scope", "selected_at", "schedule" ] }, "handler_operations_json_RetailSchedule": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_RetailTextSchedule" }, { "$ref": "#/components/schemas/handler_operations_json_RetailMediaSchedule" } ], "description": "Concrete resulting selling price; exact decimal strings, no multipliers or Provider purchase terms." }, "handler_operations_json_RetailTextSchedule": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "text" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "minimum_charge_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "request_fee_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/handler_operations_json_RetailContextTier" } } }, "required": [ "kind", "prompt_rate", "completion_rate", "cached_prompt_rate", "cache_write_prompt_rate", "reasoning_completion_rate", "minimum_charge_nanos", "request_fee_nanos", "context_tiers" ] }, "handler_operations_json_RetailContextTier": { "type": "object", "additionalProperties": false, "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } }, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate", "cached_prompt_rate", "cache_write_prompt_rate", "reasoning_completion_rate" ] }, "handler_operations_json_RetailMediaSchedule": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "media" }, "dimensions": { "$ref": "#/components/schemas/handler_operations_json_RetailDimensions" }, "meter": { "type": "string", "minLength": 1, "maxLength": 256 }, "decimal_places": { "type": "integer", "minimum": 0, "maximum": 9 }, "amount_units": { "type": "string", "pattern": "^[0-9]+$" }, "per_quantity": { "$ref": "#/components/schemas/handler_operations_json_RetailQuantity" }, "minimum_quantity": { "$ref": "#/components/schemas/handler_operations_json_RetailQuantity" }, "rounding": { "type": "string", "enum": [ "Down", "Up", "HalfEven" ] } }, "required": [ "kind", "dimensions", "meter", "decimal_places", "amount_units", "per_quantity", "minimum_quantity", "rounding" ] }, "handler_operations_json_RetailDimensions": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "channel": { "type": "string", "minLength": 1, "maxLength": 256 }, "resolution": { "type": "string", "minLength": 1, "maxLength": 256 }, "reference_video": { "type": "boolean" } }, "required": [ "model", "channel", "resolution", "reference_video" ] }, "handler_operations_json_RetailQuantity": { "type": "object", "additionalProperties": false, "properties": { "numerator": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "numerator", "denominator" ] }, "handler_operations_json_RetailPublicationResult": { "type": "object", "additionalProperties": false, "properties": { "price_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "format": "uuid" }, "version": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "price_id", "revision", "version" ] }, "handler_operations_json_RetailStandardPublication": { "type": "object", "additionalProperties": false, "properties": { "model_alias": { "type": "string", "minLength": 1, "maxLength": 200 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "schedule": { "$ref": "#/components/schemas/handler_operations_json_RetailSchedule" }, "expected_version": { "type": "string", "pattern": "^[0-9]+$" }, "idempotency_key": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "model_alias", "currency", "schedule", "expected_version", "idempotency_key", "reason" ] }, "handler_operations_json_RetailPriceRecord": { "type": "object", "additionalProperties": false, "properties": { "price_id": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "currency": { "type": "string" }, "version": { "type": "string", "pattern": "^[0-9]+$" }, "revision": { "type": "string", "format": "uuid" }, "schedule": { "$ref": "#/components/schemas/handler_operations_json_RetailSchedule" }, "published_at": { "type": "string", "format": "date-time" }, "pricing_health": { "$ref": "#/components/schemas/handler_operations_json_PlatformPricingHealth" } }, "required": [ "price_id", "model_alias", "currency", "version", "revision", "schedule", "published_at" ] }, "handler_operations_json_PlatformPricingHealth": { "type": "object", "description": "Confidential platform-only advisory comparison against current Provider quotes; not admission authorization or a realized margin. Refresh after publication.", "required": [ "advisory", "checks" ], "properties": { "advisory": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "required": [ "status", "dimensions" ], "properties": { "route": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "below_cost", "missing_provider_price", "comparison_unavailable", "no_lower_unit_rates" ] }, "message": { "type": "string" }, "dimensions": { "type": "array", "items": { "type": "object", "required": [ "dimension", "minimum_input_tokens" ], "properties": { "dimension": { "type": "string" }, "minimum_input_tokens": { "type": "string" } } } } } } } } }, "handler_operations_json_RetailPromotionPublication": { "type": "object", "additionalProperties": false, "properties": { "baseline_revision": { "type": "string", "format": "uuid" }, "customer_organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "schedule": { "$ref": "#/components/schemas/handler_operations_json_RetailSchedule" }, "effective_from": { "type": "string", "pattern": "^[0-9]+$" }, "effective_until": { "type": "string", "pattern": "^[0-9]+$" }, "expected_version": { "type": "string", "pattern": "^[0-9]+$" }, "idempotency_key": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "baseline_revision", "customer_organization_id", "schedule", "effective_from", "effective_until", "expected_version", "idempotency_key", "reason" ] }, "handler_operations_json_RetailPromotionRetirement": { "type": "object", "additionalProperties": false, "properties": { "effective_until": { "type": "string", "pattern": "^[0-9]+$" }, "expected_version": { "type": "string", "pattern": "^[0-9]+$" }, "idempotency_key": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "effective_until", "expected_version", "idempotency_key", "reason" ] }, "handler_operations_json_RetailHistoryEntry": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "string", "format": "uuid" }, "version": { "type": "string", "pattern": "^[0-9]+$" }, "action": { "type": "string", "enum": [ "standard_published", "promotion_published", "promotion_retired" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "created_at": { "type": "string", "format": "date-time" }, "standard_schedule": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_RetailSchedule" }, { "type": "null" } ] }, "promotion": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_RetailHistoryPromotion" }, { "type": "null" } ] }, "retirement": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_RetailHistoryRetirement" }, { "type": "null" } ] } }, "required": [ "revision", "version", "action", "reason", "created_at", "standard_schedule", "promotion", "retirement" ] }, "handler_operations_json_RetailHistoryPromotion": { "type": "object", "additionalProperties": false, "required": [ "baseline_revision", "scope", "customer_organization_id", "customer_name", "effective_from", "effective_until", "schedule" ], "properties": { "baseline_revision": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "global", "customer" ] }, "customer_organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_name": { "type": [ "string", "null" ] }, "effective_from": { "type": "string", "pattern": "^[0-9]+$" }, "effective_until": { "type": "string", "pattern": "^[0-9]+$" }, "schedule": { "$ref": "#/components/schemas/handler_operations_json_RetailSchedule" } } }, "handler_operations_json_RetailHistoryRetirement": { "type": "object", "additionalProperties": false, "required": [ "promotion_revision", "effective_until" ], "properties": { "promotion_revision": { "type": "string", "format": "uuid" }, "effective_until": { "type": "string", "pattern": "^[0-9]+$" } } }, "handler_operations_json_MediaAssetOperation": { "type": "object", "required": [ "id", "group_id", "model", "action", "status", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "asset_id": { "type": [ "string", "null" ], "format": "uuid" }, "model": { "type": "string" }, "action": { "type": "string", "enum": [ "create_group", "update_group", "delete_group", "create_asset", "rename_asset", "delete_asset" ] }, "status": { "type": "string", "enum": [ "prepared", "unknown", "acknowledged", "not_sent" ] }, "http_status": { "type": [ "integer", "null" ] }, "request_id": { "type": [ "string", "null" ] }, "diagnostic": { "description": "Sanitized observed failure category and phase. Null for older records or when no diagnostic was saved. Does not establish nonexecution or authorize replay.", "type": [ "object", "null" ], "additionalProperties": false, "required": [ "category", "phase" ], "properties": { "category": { "type": "string", "enum": [ "transport", "timeout", "response_too_large", "invalid_response", "upstream_rejected" ] }, "phase": { "type": "string", "enum": [ "exchange", "response", "acknowledgement" ] } } }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" } } }, "handler_operations_json_MediaAssetGroup": { "type": "object", "required": [ "id", "model", "name", "kind", "status", "revision", "created_at_ms", "updated_at_ms", "observation" ], "properties": { "id": { "type": "string", "format": "uuid" }, "model": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "generated", "person" ] }, "status": { "type": "string" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "observation": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroupObservation" }, { "type": "null" } ], "description": "Last successful identity-validated Provider Get metadata, independent of mutation status. Null before any successful read. An observation never acknowledges or unblocks unknown writes, grants dispatch or proves an uncertain write completed." } } }, "handler_operations_json_MediaAssetGroupObservation": { "type": "object", "additionalProperties": false, "required": [ "source", "status", "name", "observed_at_ms", "description" ], "properties": { "source": { "type": "string", "const": "provider_get" }, "status": { "type": "string", "const": "present" }, "name": { "type": [ "string", "null" ], "maxLength": 64 }, "observed_at_ms": { "type": "integer", "format": "int64", "description": "Server time of the saved successful Provider read. Historical observation, not a current availability guarantee." }, "description": { "type": [ "string", "null" ], "maxLength": 300 } } }, "handler_operations_json_MediaAsset": { "type": "object", "required": [ "id", "group_id", "model", "kind", "status", "revision", "created_at_ms", "updated_at_ms", "observation" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "model": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "image", "audio", "video" ] }, "status": { "type": "string" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "observation": { "oneOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaAssetObservation" }, { "type": "null" } ], "description": "Last successful identity-validated Provider Get metadata, independent of mutation status. Null before any successful read. An observation never acknowledges or unblocks unknown writes, grants dispatch or proves an uncertain write completed." } } }, "handler_operations_json_MediaAssetObservation": { "type": "object", "additionalProperties": false, "required": [ "source", "status", "name", "observed_at_ms" ], "properties": { "source": { "type": "string", "const": "provider_get" }, "status": { "type": "string", "enum": [ "processing", "active", "failed" ] }, "name": { "type": [ "string", "null" ], "maxLength": 64 }, "observed_at_ms": { "type": "integer", "format": "int64", "description": "Server time of the saved successful Provider read. Historical observation, not a current availability guarantee." } } }, "handler_operations_json_MediaAssetOperationInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "action", "model", "name" ], "properties": { "action": { "type": "string", "const": "create_group" }, "model": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "model", "group_id" ], "properties": { "action": { "type": "string", "const": "update_group" }, "model": { "type": "string" }, "group_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "model", "group_id" ], "properties": { "action": { "type": "string", "const": "delete_group" }, "model": { "type": "string" }, "group_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "model", "group_id", "url", "kind" ], "properties": { "action": { "type": "string", "const": "create_asset" }, "model": { "type": "string" }, "group_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "writeOnly": true }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "model", "asset_id", "name" ], "properties": { "action": { "type": "string", "const": "rename_asset" }, "model": { "type": "string" }, "asset_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "model", "asset_id" ], "properties": { "action": { "type": "string", "const": "delete_asset" }, "model": { "type": "string" }, "asset_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } } } ] }, "handler_operations_json_MediaVerificationSession": { "type": "object", "additionalProperties": false, "required": [ "id", "model", "subject_name", "status", "group_id", "expires_at", "created_at_ms", "updated_at_ms" ], "properties": { "id": { "type": "string", "format": "uuid" }, "model": { "type": "string" }, "subject_name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "prepared", "unknown", "not_sent", "waiting_user", "processing", "verified", "failed", "expired" ] }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at_ms": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" } } }, "handler_operations_json_MediaAssetMutation": { "type": "object", "additionalProperties": false, "required": [ "data", "group", "asset" ], "properties": { "data": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetOperation" }, "group": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroup" }, { "type": "null" } ] }, "asset": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaAsset" }, { "type": "null" } ] } } }, "handler_operations_json_MediaAssetGroupPage": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_MediaAssetGroup" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } }, "handler_operations_json_MediaAssetPage": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_MediaAsset" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } }, "handler_operations_json_CustomerTextTariffHistoryEntry": { "type": "object", "additionalProperties": false, "required": [ "model_alias", "revision", "currency", "created_at", "is_current", "prompt_rate", "completion_rate", "minimum_charge_nanos", "request_fee_nanos", "cached_prompt_rate", "reasoning_completion_rate", "cache_write_prompt_rate", "context_tiers" ], "properties": { "model_alias": { "type": "string" }, "revision": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "created_at": { "type": "string", "format": "date-time" }, "is_current": { "type": "boolean" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "minimum_charge_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "request_fee_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." } } }, "handler_operations_json_VendorRequestRateLimitRevision": { "type": "object", "additionalProperties": false, "required": [ "requests_per_minute", "revision", "recorded_at", "actor_kind", "actor_name" ], "properties": { "requests_per_minute": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000 }, "revision": { "type": "string", "pattern": "^[0-9]+$" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor_kind": { "type": "string", "enum": [ "installation", "member" ] }, "actor_name": { "type": "string" } } }, "handler_operations_json_VendorRequestRateLimit": { "type": "object", "additionalProperties": false, "required": [ "requests_per_minute", "revision" ], "properties": { "requests_per_minute": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000 }, "revision": { "type": "string", "pattern": "^[0-9]+$" } } }, "handler_operations_json_ProviderOfferHistoryEntry": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "revision", "model_alias", "created_at", "rate_kind", "currency", "prompt_rate", "completion_rate", "cached_prompt_rate", "is_current", "reasoning_completion_rate", "cache_write_prompt_rate" ], "properties": { "revision": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "rate_kind": { "const": "text" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "is_current": { "type": "boolean" }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured Provider rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." } } }, { "type": "object", "additionalProperties": false, "required": [ "revision", "model_alias", "created_at", "rate_kind", "currency", "prompt_rate", "completion_rate", "cached_prompt_rate", "is_current", "reasoning_completion_rate", "cache_write_prompt_rate" ], "properties": { "revision": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "rate_kind": { "const": "media" }, "currency": { "type": "null" }, "prompt_rate": { "type": "null" }, "completion_rate": { "type": "null" }, "cached_prompt_rate": { "type": "null" }, "is_current": { "type": "boolean" }, "reasoning_completion_rate": { "type": "null", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": "null", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured Provider rate prices it separately; missing quantity remains unresolved." } } } ] }, "handler_operations_json_PlatformAuditPage": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_PlatformAuditEvent" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor, null on the final page." } } }, "handler_operations_json_PlatformAuditEvent": { "type": "object", "required": [ "id", "source", "category", "action", "actor_kind", "actor_label", "target_label", "created_at", "revision", "before_role", "after_role" ], "properties": { "id": { "type": "string", "description": "Internal source-qualified event reference. Never render as a display label." }, "source": { "type": "string", "enum": [ "operator", "vendor", "supplier", "branding", "payment_gateway", "platform_access", "retail_price", "retail_text_enrollment", "retail_media_enrollment", "balance_grant", "gift_correction", "credit_policy", "grant_preparation", "media_liability", "procurement_configuration" ] }, "category": { "type": "string", "enum": [ "authentication", "configuration", "access", "supplier" ] }, "action": { "type": "string" }, "actor_kind": { "type": "string" }, "actor_label": { "type": "string", "description": "Recorded name or recorded system role; Unknown actor when historical attribution is absent. Labels are current names, not historical name snapshots." }, "target_label": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "revision": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$", "description": "Decimal revision string, when present. No configuration values are included." }, "before_role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "viewer", null ], "description": "Recorded role before a future role_changed event; null for historical events and other journal streams." }, "after_role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "viewer", null ], "description": "Recorded role after the same mutation; never inferred from current user metadata." } } }, "password_sessions_openapi_yaml_Session": { "type": "object", "additionalProperties": false, "required": [ "id", "operator_id", "expires_at_unix", "revoked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "operator_id": { "type": "string", "format": "uuid" }, "expires_at_unix": { "type": "integer" }, "revoked": { "type": "boolean" } } }, "handler_operations_json_MediaBillingCustomerMediaRateCard": { "type": "object", "additionalProperties": false, "required": [ "revision", "vendor_id", "vendor_revision", "model_revision", "schema_revision", "offer_revision", "tariff", "discounts", "maximum_quantity", "liability_qualification_revision" ], "properties": { "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "vendor_id": { "type": "string", "format": "uuid", "description": "Internal route reference; never a display label." }, "vendor_revision": { "type": "integer", "minimum": 1, "format": "int64" }, "model_revision": { "type": "integer", "minimum": 1, "format": "int64" }, "schema_revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "offer_revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "tariff": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingMediaSellingTariff" }, "discounts": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingMediaSellingDiscount" } }, "maximum_quantity": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingExactMediaQuantity" }, "liability_qualification_revision": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Reference to independently qualified upper-bound evidence; a point estimate is insufficient." } } }, "handler_operations_json_MediaBillingMediaSellingTariff": { "type": "object", "additionalProperties": false, "required": [ "revision", "dimensions", "meter", "currency", "decimal_places", "amount_units", "per_quantity", "minimum_quantity", "rounding", "effective_from" ], "properties": { "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "dimensions": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingMediaBillingDimensions" }, "meter": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "decimal_places": { "type": "integer", "minimum": 0, "maximum": 9 }, "amount_units": { "type": "integer", "minimum": 0, "description": "Exact u64 smallest accounting units at the declared decimal precision. JavaScript SDK requires a safe integer." }, "per_quantity": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingExactMediaQuantity" }, "minimum_quantity": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingExactMediaQuantity" }, "rounding": { "type": "string", "enum": [ "Down", "Up", "HalfEven" ] }, "effective_from": { "type": "integer", "format": "int64", "description": "Unix seconds, inclusive." }, "effective_until": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix seconds, exclusive; must exceed effective_from." } } }, "handler_operations_json_MediaBillingMediaBillingDimensions": { "type": "object", "additionalProperties": false, "required": [ "model", "channel", "resolution", "reference_video" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 256 }, "channel": { "type": "string", "minLength": 1, "maxLength": 256 }, "resolution": { "type": "string", "minLength": 1, "maxLength": 256 }, "reference_video": { "type": "boolean" } } }, "handler_operations_json_MediaBillingExactMediaQuantity": { "type": "object", "additionalProperties": false, "required": [ "numerator", "denominator" ], "description": "Reduced nonnegative rational quantity; canonical decimal strings bounded to u128. Denominator must be positive. Maximum liability quantity must be positive.", "properties": { "numerator": { "type": "string", "maxLength": 39, "pattern": "^(0|[1-9][0-9]*)$" }, "denominator": { "type": "string", "maxLength": 39, "pattern": "^[1-9][0-9]*$" } } }, "handler_operations_json_MediaBillingMediaSellingDiscount": { "type": "object", "additionalProperties": false, "required": [ "revision", "effective_from", "priority", "stacking", "multiplier" ], "properties": { "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "dimensions": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaBillingMediaBillingDimensions" }, { "type": "null" } ] }, "offer": { "type": [ "string", "null" ] }, "customer": { "type": [ "string", "null" ] }, "effective_from": { "type": "integer", "format": "int64" }, "effective_until": { "type": [ "integer", "null" ], "format": "int64" }, "priority": { "type": "integer", "format": "int32" }, "stacking": { "type": "string", "enum": [ "Exclusive", "Multiply" ] }, "multiplier": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingExactMediaQuantity" } } }, "handler_operations_json_MediaBillingCustomerMediaRateRecordCard": { "type": "object", "required": [ "revision", "vendor_id", "vendor_revision", "model_revision", "schema_revision", "offer_revision", "tariff", "discounts", "maximum_quantity", "liability_qualification_revision" ], "properties": { "revision": { "type": "string" }, "vendor_id": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "string", "pattern": "^[0-9]+$" }, "model_revision": { "type": "string", "pattern": "^[0-9]+$" }, "schema_revision": { "type": "string" }, "offer_revision": { "type": "string" }, "maximum_quantity": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingExactMediaQuantity" }, "liability_qualification_revision": { "type": "string" }, "tariff": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingMediaSellingTariffRecord" }, "discounts": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingMediaSellingDiscountRecord" } } } }, "handler_operations_json_MediaBillingMediaSellingTariffRecord": { "type": "object", "additionalProperties": false, "required": [ "revision", "dimensions", "meter", "currency", "decimal_places", "amount_units", "per_quantity", "minimum_quantity", "rounding", "effective_from" ], "properties": { "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "dimensions": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingMediaBillingDimensions" }, "meter": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "decimal_places": { "type": "integer", "minimum": 0, "maximum": 9 }, "amount_units": { "type": "string", "pattern": "^[0-9]+$" }, "per_quantity": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingExactMediaQuantity" }, "minimum_quantity": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingExactMediaQuantity" }, "rounding": { "type": "string", "enum": [ "Down", "Up", "HalfEven" ] }, "effective_from": { "type": "string", "pattern": "^-?[0-9]+$" }, "effective_until": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+$" } } }, "handler_operations_json_MediaBillingMediaSellingDiscountRecord": { "type": "object", "additionalProperties": false, "required": [ "revision", "effective_from", "priority", "stacking", "multiplier" ], "properties": { "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "dimensions": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_MediaBillingMediaBillingDimensions" }, { "type": "null" } ] }, "offer": { "type": [ "string", "null" ] }, "customer": { "type": [ "string", "null" ] }, "effective_from": { "type": "string", "pattern": "^-?[0-9]+$" }, "effective_until": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+$" }, "priority": { "type": "integer", "format": "int32" }, "stacking": { "type": "string", "enum": [ "Exclusive", "Multiply" ] }, "multiplier": { "$ref": "#/components/schemas/handler_operations_json_MediaBillingExactMediaQuantity" } } }, "handler_operations_json_ProviderOfferRevision": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "revision", "model_alias", "created_at", "rate_kind", "currency", "prompt_rate", "completion_rate", "cached_prompt_rate", "reasoning_completion_rate", "cache_write_prompt_rate" ], "properties": { "revision": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "rate_kind": { "const": "text" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured Provider rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." } } }, { "type": "object", "additionalProperties": false, "required": [ "revision", "model_alias", "created_at", "rate_kind", "currency", "prompt_rate", "completion_rate", "cached_prompt_rate", "reasoning_completion_rate", "cache_write_prompt_rate" ], "properties": { "revision": { "type": "string", "format": "uuid" }, "model_alias": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "rate_kind": { "const": "media" }, "currency": { "type": "null" }, "prompt_rate": { "type": "null" }, "completion_rate": { "type": "null" }, "cached_prompt_rate": { "type": "null" }, "reasoning_completion_rate": { "type": "null", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": "null", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured Provider rate prices it separately; missing quantity remains unresolved." } } } ] }, "handler_operations_json_BrandingConfiguration": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision", "settings" ], "properties": { "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "settings": { "$ref": "#/components/schemas/handler_operations_json_BrandingSettings" } } } } }, "handler_operations_json_BrandingSettings": { "type": "object", "additionalProperties": false, "required": [ "display_name", "default_appearance", "light", "dark" ], "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Trimmed nonempty text without control characters" }, "default_appearance": { "type": "string", "enum": [ "system", "light", "dark" ] }, "logo_data_url": { "type": [ "string", "null" ], "maxLength": 349550, "pattern": "^data:image/png;base64,[A-Za-z0-9+/=]+$", "description": "Static PNG up to 256 KiB, at most 1024 by 512 pixels. Re-encoded from decoded pixels before saving. Missing or null resets to default." }, "favicon_data_url": { "type": [ "string", "null" ], "maxLength": 43714, "pattern": "^data:image/png;base64,[A-Za-z0-9+/=]+$", "description": "Square static PNG up to 32 KiB, at most 256 by 256 pixels. Missing or null resets to default." }, "light": { "$ref": "#/components/schemas/handler_operations_json_BrandingPalette" }, "dark": { "$ref": "#/components/schemas/handler_operations_json_BrandingPalette" } } }, "handler_operations_json_BrandingPalette": { "type": "object", "maxProperties": 8, "propertyNames": { "enum": [ "background", "foreground", "primary", "primary-foreground", "sidebar", "sidebar-foreground", "accent", "accent-foreground" ] }, "additionalProperties": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "handler_operations_json_VideoIntegerControl": { "type": "object", "additionalProperties": false, "required": [ "kind", "minimum", "maximum" ], "description": "Signed 64-bit integer bounds; maximum must be at least minimum and any default must lie within them. The dashboard edits exact JavaScript-safe integers only.", "properties": { "kind": { "type": "string", "const": "integer" }, "minimum": { "type": "integer", "format": "int64" }, "maximum": { "type": "integer", "format": "int64" }, "default": { "type": [ "integer", "null" ], "format": "int64" } } }, "handler_operations_json_VideoChoiceControl": { "type": "object", "additionalProperties": false, "required": [ "kind", "values" ], "description": "Values are canonical names of at most 256 UTF-8 bytes; any default must be one of them.", "properties": { "kind": { "type": "string", "const": "choice" }, "values": { "type": "array", "minItems": 1, "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "default": { "type": [ "string", "null" ] } } }, "handler_operations_json_VideoBooleanControl": { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "type": "string", "const": "boolean" }, "default": { "type": [ "boolean", "null" ] } } }, "handler_operations_json_VideoOutputSchema": { "type": "object", "additionalProperties": false, "required": [ "specifications", "estimator", "estimator_revision" ], "description": "Optional effective output mapping for this schema revision. Requires resolution, ratio and positive duration controls, each with a default or required input. Pixel estimation additionally requires a positive frames_per_second control; seconds estimation may omit it. Missing resolution/ratio combinations reject requests before dispatch. Estimates never establish reported usage or maximum liability. The ark-direct-v1 adapter qualifies video_tokens only; openrouter-video-v1 supports owner-funded text generation with seconds estimates and unknown reported quantity.", "properties": { "estimator": { "type": "string", "enum": [ "SeedancePixelsV1", "OutputSecondsV1" ] }, "estimator_revision": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Reviewed configuration reference; at most 256 UTF-8 bytes." }, "specifications": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "type": "object", "additionalProperties": false, "required": [ "resolution", "ratio", "width", "height" ], "properties": { "resolution": { "type": "string", "description": "Must be accepted by the configured resolution control." }, "ratio": { "type": "string", "description": "Must be accepted by the configured ratio control; each resolution/ratio pair is unique." }, "width": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "height": { "type": "integer", "minimum": 1, "maximum": 4294967295 } } } } } }, "handler_operations_json_VideoQueryObservationPage": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "cursor", "observed_at_ms", "meter", "status", "quantity", "provider_times" ], "properties": { "cursor": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Internal continuation reference; never a product label." }, "observed_at_ms": { "type": "integer", "format": "int64" }, "meter": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "expired", "unknown" ] }, "quantity": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "missing", "invalid" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "state", "value" ], "properties": { "state": { "type": "string", "const": "reported" }, "value": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } ] }, "provider_times": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "missing", "invalid" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "state", "created_at", "updated_at" ], "properties": { "state": { "type": "string", "const": "reported" }, "created_at": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "updated_at": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } ] } } } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" } } }, "guardrails_openapi_yaml_Policy": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "name", "models", "providers" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "models": { "$ref": "#/components/schemas/guardrails_openapi_yaml_AccessRule" }, "providers": { "$ref": "#/components/schemas/guardrails_openapi_yaml_AccessRule" }, "input_detectors": { "type": "array", "maxItems": 4, "description": "Required input detectors. Composes workspace and assigned-key restrictions. Only deployment-authorized workspaces and declared unmetered services can activate a current configuration fingerprint. Matched or indeterminate results fail closed before inference admission. Textual content only, after local redaction; unsupported content is denied. Paid and unknown-cost detectors remain synthetic-only.", "items": { "type": "object", "additionalProperties": false, "required": [ "detector", "configuration_fingerprint", "consent_to_external_processing" ], "properties": { "detector": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9_-]+$" }, "configuration_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "consent_to_external_processing": { "type": "boolean", "const": true } } } }, "input_rules": { "type": "array", "maxItems": 32, "description": "Local text rules enforced before dispatch. Workspace and assigned-key rules compose; unsupported content fails closed. At most 32 combined rules are supported.", "items": { "type": "object", "additionalProperties": false, "required": [ "action" ], "oneOf": [ { "required": [ "pattern" ] }, { "required": [ "preset" ] } ], "properties": { "pattern": { "type": "string", "maxLength": 4096 }, "preset": { "enum": [ "email_v1", "api_key_prefix_v1" ] }, "action": { "enum": [ "block", "redact" ] } } } }, "output": { "type": "object", "additionalProperties": false, "required": [ "mode", "rules" ], "description": "Complete textual output inspection bounded to 1 MiB. Streaming, tools, structured-output requests and Embeddings are incompatible and rejected before inference in both modes. Buffered enforcement withholds indeterminate output; observation records matches or indeterminate coverage without redaction or denial. Observation sees the original response and cannot weaken inherited enforcement. Incurred usage remains chargeable. External output detectors and streaming inspection are not implemented.", "properties": { "mode": { "enum": [ "buffered_full", "observe_only" ] }, "rules": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "action" ], "oneOf": [ { "required": [ "pattern" ] }, { "required": [ "preset" ] } ], "properties": { "pattern": { "type": "string", "maxLength": 4096 }, "preset": { "enum": [ "email_v1", "api_key_prefix_v1" ] }, "action": { "enum": [ "block", "redact" ] } } } } } } } }, "guardrails_openapi_yaml_AccessRule": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "inherit", "allow_all", "deny_all" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "mode", "values" ], "properties": { "mode": { "type": "string", "const": "allow_list" }, "values": { "type": "array", "maxItems": 1000, "items": { "type": "string", "minLength": 1, "maxLength": 200 } } } } ], "description": "Empty allowlists deny. Values must be exact, nonblank, trimmed identifiers without controls or wildcard; use allow_all explicitly." }, "request_observability_openapi_yaml_RequestPayload": { "type": "object", "additionalProperties": false, "required": [ "request", "response", "content_type", "complete", "truncated", "expires_at" ], "properties": { "request": { "description": "Captured JSON request with known credential fields removed." }, "response": { "type": "string", "description": "Sanitized retained output; empty when response_omitted is true." }, "response_omitted": { "type": "boolean", "description": "True when truncated JSON cannot be safely parsed and its response body is withheld. Request content remains available." }, "content_type": { "type": "string" }, "complete": { "type": "boolean" }, "truncated": { "type": "boolean" }, "expires_at": { "type": "string", "description": "PostgreSQL timestamp identifying content expiry." } } }, "handler_operations_json_EPayConfiguration": { "type": "object", "additionalProperties": false, "required": [ "merchant_id", "endpoint", "notify_url", "return_url", "revision", "enabled", "has_key", "methods" ], "properties": { "merchant_id": { "type": "string" }, "endpoint": { "type": "string", "description": "HTTPS gateway base or complete submit.php endpoint. A base path gets /submit.php appended; a supplied submit.php is preserved, including subdirectories. Trailing slashes are normalized. Query strings, fragments and URL credentials are rejected. The complete encoded checkout must fit 2048 bytes for the largest supported order and amount; invalid enabled configuration is rejected before persistence. Existing saved checkout URLs are not rewritten." }, "notify_url": { "type": "string" }, "return_url": { "type": "string" }, "revision": { "type": "string", "pattern": "^[0-9]+$" }, "enabled": { "type": "boolean" }, "has_key": { "type": "boolean" }, "methods": { "type": "array", "items": { "type": "string" }, "description": "Saved methods or deployment defaults; legacy disabled configurations may contain unsupported values. Writes accept only alipay and wxpay." } } }, "provider_business_openapi_yaml_SupplierMediaRateRead": { "type": "object", "additionalProperties": false, "required": [ "revision", "offer_revision", "vendor_revision", "model_revision", "schema_revision", "tariff", "discounts" ], "properties": { "revision": { "type": "string" }, "offer_revision": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "model_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "schema_revision": { "type": "string" }, "tariff": { "type": "object", "additionalProperties": false, "required": [ "revision", "dimensions", "meter", "currency", "decimal_places", "amount_units", "per_quantity", "minimum_quantity", "rounding", "effective_from", "effective_until" ], "properties": { "revision": { "type": "string" }, "dimensions": { "$ref": "#/components/schemas/billing_openapi_yaml_MediaBillingDimensions" }, "meter": { "type": "string" }, "currency": { "type": "string" }, "decimal_places": { "type": "integer", "minimum": 0, "maximum": 9 }, "amount_units": { "type": "string", "pattern": "^[0-9]+$" }, "per_quantity": { "$ref": "#/components/schemas/billing_openapi_yaml_ExactMediaQuantity" }, "minimum_quantity": { "$ref": "#/components/schemas/billing_openapi_yaml_ExactMediaQuantity" }, "rounding": { "type": "string", "enum": [ "Down", "Up", "HalfEven" ] }, "effective_from": { "type": "string", "pattern": "^-?[0-9]+$" }, "effective_until": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+$" } } }, "discounts": { "type": "array", "maxItems": 64, "items": { "type": "object", "additionalProperties": false, "required": [ "revision", "dimensions", "offer", "customer", "effective_from", "effective_until", "priority", "stacking", "multiplier" ], "properties": { "revision": { "type": "string" }, "dimensions": { "anyOf": [ { "$ref": "#/components/schemas/billing_openapi_yaml_MediaBillingDimensions" }, { "type": "null" } ] }, "offer": { "type": [ "string", "null" ] }, "customer": { "type": [ "string", "null" ] }, "effective_from": { "type": "string", "pattern": "^-?[0-9]+$" }, "effective_until": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+$" }, "priority": { "type": "integer" }, "stacking": { "type": "string", "enum": [ "Exclusive", "Multiply" ] }, "multiplier": { "$ref": "#/components/schemas/billing_openapi_yaml_ExactMediaQuantity" } } } } } }, "billing_openapi_yaml_MediaBillingDimensions": { "type": "object", "additionalProperties": false, "required": [ "model", "channel", "resolution", "reference_video" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 256 }, "channel": { "type": "string", "minLength": 1, "maxLength": 256 }, "resolution": { "type": "string", "minLength": 1, "maxLength": 256 }, "reference_video": { "type": "boolean" } } }, "billing_openapi_yaml_ExactMediaQuantity": { "type": "object", "additionalProperties": false, "required": [ "numerator", "denominator" ], "description": "Reduced nonnegative rational quantity; canonical decimal strings bounded to u128. Denominator must be positive. Maximum liability quantity must be positive.", "properties": { "numerator": { "type": "string", "maxLength": 39, "pattern": "^(0|[1-9][0-9]*)$" }, "denominator": { "type": "string", "maxLength": 39, "pattern": "^[1-9][0-9]*$" } } }, "provider_business_openapi_yaml_SupplierMediaRateCard": { "type": "object", "additionalProperties": false, "required": [ "revision", "offer_revision", "vendor_revision", "model_revision", "schema_revision", "tariff", "discounts" ], "properties": { "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "offer_revision": { "type": "string", "format": "uuid" }, "vendor_revision": { "type": "integer", "minimum": 1, "format": "int64" }, "model_revision": { "type": "integer", "minimum": 1, "format": "int64" }, "schema_revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "tariff": { "$ref": "#/components/schemas/billing_openapi_yaml_MediaSellingTariff", "description": "Same exact tariff structure, applied to confidential agreed Provider purchase terms." }, "discounts": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/billing_openapi_yaml_MediaSellingDiscount" } } } }, "billing_openapi_yaml_MediaSellingTariff": { "type": "object", "additionalProperties": false, "required": [ "revision", "dimensions", "meter", "currency", "decimal_places", "amount_units", "per_quantity", "minimum_quantity", "rounding", "effective_from" ], "properties": { "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "dimensions": { "$ref": "#/components/schemas/billing_openapi_yaml_MediaBillingDimensions" }, "meter": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "decimal_places": { "type": "integer", "minimum": 0, "maximum": 9 }, "amount_units": { "type": "integer", "minimum": 0, "description": "Exact u64 smallest accounting units at the declared decimal precision. JavaScript SDK requires a safe integer." }, "per_quantity": { "$ref": "#/components/schemas/billing_openapi_yaml_ExactMediaQuantity" }, "minimum_quantity": { "$ref": "#/components/schemas/billing_openapi_yaml_ExactMediaQuantity" }, "rounding": { "type": "string", "enum": [ "Down", "Up", "HalfEven" ] }, "effective_from": { "type": "integer", "format": "int64", "description": "Unix seconds, inclusive." }, "effective_until": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix seconds, exclusive; must exceed effective_from." } } }, "billing_openapi_yaml_MediaSellingDiscount": { "type": "object", "additionalProperties": false, "required": [ "revision", "effective_from", "priority", "stacking", "multiplier" ], "properties": { "revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "dimensions": { "anyOf": [ { "$ref": "#/components/schemas/billing_openapi_yaml_MediaBillingDimensions" }, { "type": "null" } ] }, "offer": { "type": [ "string", "null" ] }, "customer": { "type": [ "string", "null" ] }, "effective_from": { "type": "integer", "format": "int64" }, "effective_until": { "type": [ "integer", "null" ], "format": "int64" }, "priority": { "type": "integer", "format": "int32" }, "stacking": { "type": "string", "enum": [ "Exclusive", "Multiply" ] }, "multiplier": { "$ref": "#/components/schemas/billing_openapi_yaml_ExactMediaQuantity" } } }, "handler_operations_json_WorkspaceCustomerModelPrice": { "type": "object", "additionalProperties": false, "required": [ "currency", "unit", "prompt_rate", "completion_rate", "cached_prompt_rate", "minimum_charge_nanos", "request_fee_nanos", "reasoning_completion_rate", "cache_write_prompt_rate", "context_tiers" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "unit": { "type": "string", "const": "nanounits_per_million_tokens", "description": "Unit for token rate fields only. Minimum and request fee are currency nanounits per known completed request." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$" }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$" }, "minimum_charge_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "request_fee_nanos": { "type": "string", "pattern": "^[0-9]+$" }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported reasoning output is a subset of total completion tokens. A configured rate prices that subset separately; missing quantity remains unresolved." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Reported cache-write input is a disjoint subset of aggregate input. A configured rate prices it separately; missing quantity remains unresolved." }, "context_tiers": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "minimum_input_tokens", "prompt_rate", "completion_rate" ], "properties": { "minimum_input_tokens": { "type": "string", "pattern": "^[0-9]+$", "description": "Positive inclusive aggregate input threshold, at most 9223372036854775807." }, "prompt_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "completion_rate": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cached_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "cache_write_prompt_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." }, "reasoning_completion_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Integer currency nanounits per million tokens, at most 1000000000000000." } } }, "description": "Complete whole-request schedules; highest inclusive input threshold wins. Null category rates do not inherit the base schedule. Empty array clears tiers; omitting existing tiers conflicts." }, "pricing_source": { "type": "string", "enum": [ "workspace", "platform" ] }, "promotion_scope": { "type": [ "string", "null" ], "enum": [ "global", "customer", null ] }, "selected_at": { "type": "string", "pattern": "^[0-9]+$" }, "price_version": { "type": "string", "pattern": "^[0-9]+$" } } }, "handler_operations_json_ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object" } }, "tools": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "JSON Schema object forwarded to the configured provider.", "additionalProperties": true }, "strict": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 } } } }, "additionalProperties": true } ] }, "parallel_tool_calls": { "type": "boolean" }, "response_format": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "text" } }, "additionalProperties": true }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "json_object" } }, "additionalProperties": true }, { "type": "object", "required": [ "type", "json_schema" ], "properties": { "type": { "type": "string", "const": "json_schema" }, "json_schema": { "type": "object", "required": [ "name", "schema" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string" }, "strict": { "type": "boolean" }, "schema": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } ], "description": "Buffered and streamed structured JSON are supported on explicitly enabled priced text routes. Serialized response-format instructions count toward the route input byte guard alongside messages; this guard is not a provider tokenizer or a guarantee against reported overruns." }, "temperature": { "type": [ "number", "null" ], "minimum": 0, "maximum": 2 }, "top_p": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "frequency_penalty": { "type": [ "number", "null" ], "minimum": -2, "maximum": 2 }, "presence_penalty": { "type": [ "number", "null" ], "minimum": -2, "maximum": 2 }, "reasoning": { "type": "object", "description": "Priced Chat supports explicit reasoning budgets on OpenRouter routes. max_tokens must be a positive integer strictly below the total output limit; it is a subset of that limit. exclude controls whether upstream reasoning text is requested in the response. Other reasoning options on priced routes are rejected. Model support remains upstream-specific.", "required": [ "max_tokens" ], "additionalProperties": false, "properties": { "max_tokens": { "type": "integer", "minimum": 1 }, "exclude": { "type": "boolean" } } }, "max_tokens": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9223372036854776000 }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9223372036854776000 }, "n": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9223372036854776000 }, "seed": { "type": [ "integer", "null" ], "minimum": -9223372036854776000, "maximum": 9223372036854776000 }, "stream": { "type": "boolean" }, "stream_options": { "type": [ "object", "null" ], "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "handler_operations_json_ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "chat.completion" }, "model": { "type": "string", "description": "Public model alias." }, "created": { "type": "integer" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "finish_reason": { "type": [ "string", "null" ] }, "message": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "description": "Usually text or null for a function call; extensions remain provider-specific." }, "refusal": { "type": [ "string", "null" ] }, "tool_calls": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON-encoded function arguments; Niu does not execute the function." } }, "required": [ "name", "arguments" ] } }, "required": [ "id", "type", "function" ] } } } } }, "required": [ "message" ] } }, "usage": { "description": "Optional provider token usage. Its presence alone does not guarantee complete valid accounting evidence. Customer charges must be read from billing APIs, never inferred from missing counters." } }, "description": "Nonstreaming completion envelope. Provider extension fields may be present. Missing usage is unknown, not zero.", "required": [ "object", "model", "choices" ] }, "handler_operations_json_Vendor": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "adapter", "api_base", "enabled", "revision", "has_credential" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "adapter": { "type": "string", "enum": [ "openrouter", "openai", "anthropic", "gemini", "ark" ] }, "api_base": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 1 }, "has_credential": { "type": "boolean" }, "owner_funded": { "type": "boolean", "readOnly": true, "description": "Configuration-list metadata identifying a private credential owned by one account. Not accepted in configuration writes." }, "supplier": { "type": [ "object", "null" ], "description": "Provider ownership on configuration-list reads; credentials and commercial data are excluded.", "required": [ "id", "name" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } }, "handler_operations_json_VendorCreate": { "type": "object", "additionalProperties": false, "required": [ "name", "adapter", "api_base", "api_key" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "adapter": { "type": "string", "enum": [ "openrouter", "openai", "anthropic", "gemini", "ark" ] }, "api_base": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS endpoint or HTTP loopback endpoint without URL credentials or query parameters." }, "api_key": { "type": "string", "writeOnly": true, "minLength": 1, "maxLength": 8192 }, "enabled": { "type": "boolean", "default": true }, "supplier_id": { "type": "string", "format": "uuid", "description": "Existing Provider business to own this API-key configuration. Mutually exclusive with create_supplier=true; ownership and creation commit atomically." }, "create_supplier": { "type": "boolean", "default": false, "description": "Atomically create a Provider business with this name and its explicit configuration ownership link. Omission preserves legacy configuration-only creation." } } }, "handler_operations_json_VendorUpdate": { "type": "object", "additionalProperties": false, "required": [ "name", "api_base", "enabled", "expected_revision" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "api_base": { "type": "string", "format": "uri", "maxLength": 2048 }, "api_key": { "type": "string", "writeOnly": true, "minLength": 1, "maxLength": 8192, "description": "Omit to retain the current credential." }, "enabled": { "type": "boolean" }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "handler_operations_json_VendorModel": { "type": "object", "required": [ "alias", "vendor_id", "upstream_model", "enabled", "public_catalog", "capabilities", "pricing", "revision" ], "properties": { "alias": { "type": "string" }, "vendor_id": { "type": "string", "format": "uuid" }, "upstream_model": { "type": "string" }, "enabled": { "type": "boolean" }, "public_catalog": { "type": "boolean" }, "available": { "type": "boolean", "readOnly": true, "description": "Configuration eligibility in the management list; not an upstream health or entitlement check." }, "owner_funded": { "type": "boolean", "readOnly": true, "description": "Management-list metadata identifying private owner-funded routes. Omitted from configuration writes." }, "capabilities": { "$ref": "#/components/schemas/handler_operations_json_VendorCapabilities" }, "pricing": { "$ref": "#/components/schemas/handler_operations_json_VendorRoutePricing" }, "revision": { "type": "integer", "minimum": 1 } } }, "handler_operations_json_VendorCapabilities": { "type": "object", "additionalProperties": false, "properties": { "catalog": { "$ref": "#/components/schemas/handler_operations_json_CatalogMetadata" }, "video_schema": { "$ref": "#/components/schemas/handler_operations_json_VideoSchema" }, "provider_assets": { "description": "Explicit FastRouter asset protocol on an Ark adapter; not processing readiness or commercial qualification.", "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "channel" ], "properties": { "channel": { "type": "string", "const": "fastrouter-actions-v1" } } } ] }, "supports_tool_calls": { "type": "boolean", "default": false }, "supports_streaming_tool_calls": { "type": "boolean", "default": false }, "supports_structured_output": { "type": "boolean", "default": false }, "supports_embeddings": { "type": "boolean", "default": false }, "supports_embedding_dimensions": { "type": "boolean", "default": false }, "supports_embedding_base64": { "type": "boolean", "default": false }, "supports_generate_content": { "type": "boolean", "default": false, "description": "Native GenerateContent opt-in for static or managed gemini routes; does not imply streaming, tools or media support." }, "supports_messages_streaming_tools": { "type": "boolean", "default": false, "description": "Explicit native client-tool SSE capability; requires supports_messages_tools and supports_messages_streaming. JSON arguments are bounded and validated at block completion." }, "supports_messages_tools": { "type": "boolean", "default": false, "description": "Explicit buffered native client-tool capability; requires supports_messages. Streaming tools require the separate supports_messages_streaming_tools capability." }, "supports_messages_streaming": { "type": "boolean", "default": false, "description": "Explicit native text SSE opt-in; requires supports_messages." }, "supports_messages": { "type": "boolean", "default": false, "description": "Explicit native Messages nonstreaming text capability for OpenRouter or Anthropic routes. Does not imply streaming, tools or media support." }, "supports_responses": { "type": "boolean", "default": false } } }, "handler_operations_json_CatalogMetadata": { "type": "object", "additionalProperties": false, "description": "Descriptive provider metadata, stored under capabilities.catalog on vendor mappings and exposed as catalog on model listings. Advertised USD per-token prices are separate from billing rates. Missing values mean unknown, never zero.", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 300 }, "description": { "type": [ "string", "null" ], "maxLength": 12000 }, "context_length": { "type": [ "integer", "null" ], "minimum": 1 }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 1 }, "input_modalities": { "type": "array", "maxItems": 16, "items": { "type": "string", "maxLength": 40 } }, "output_modalities": { "type": "array", "maxItems": 16, "items": { "type": "string", "maxLength": 40 } }, "supported_parameters": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "input_price": { "type": [ "string", "null" ], "maxLength": 64, "description": "Advertised USD per input token." }, "output_price": { "type": [ "string", "null" ], "maxLength": 64, "description": "Advertised USD per output token." } } }, "handler_operations_json_VideoSchema": { "type": "object", "additionalProperties": false, "description": "Versioned constraints for the exact alias/upstream model/channel. The enclosing capabilities document is limited to 16 KiB. Backend validation enforces relative bounds, defaults, input transport, roles and incompatible controls. Configuration does not qualify a route or enable unsupported media/callback transport.", "required": [ "version", "revision", "model_alias", "upstream_model", "channel", "maximum_body_bytes", "maximum_content_items", "inputs", "controls", "required_controls", "exclusive_controls", "callbacks_qualified" ], "properties": { "version": { "type": "integer", "const": 1 }, "revision": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trimmed canonical revision with no control characters; at most 256 UTF-8 bytes." }, "model_alias": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Must match the enclosing model alias." }, "upstream_model": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Must match the enclosing upstream mapping." }, "channel": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact canonical channel contract; at most 256 UTF-8 bytes." }, "maximum_body_bytes": { "type": "integer", "minimum": 1, "maximum": 16777216 }, "maximum_content_items": { "type": "integer", "minimum": 1, "maximum": 32 }, "inputs": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "text": { "$ref": "#/components/schemas/handler_operations_json_VideoInputRule" }, "image_url": { "$ref": "#/components/schemas/handler_operations_json_VideoInputRule" }, "video_url": { "$ref": "#/components/schemas/handler_operations_json_VideoInputRule" }, "audio_url": { "$ref": "#/components/schemas/handler_operations_json_VideoInputRule" } } }, "controls": { "type": "object", "additionalProperties": false, "properties": { "duration": { "$ref": "#/components/schemas/handler_operations_json_VideoIntegerControl" }, "seed": { "$ref": "#/components/schemas/handler_operations_json_VideoIntegerControl" }, "frames_per_second": { "$ref": "#/components/schemas/handler_operations_json_VideoIntegerControl" }, "resolution": { "$ref": "#/components/schemas/handler_operations_json_VideoChoiceControl" }, "ratio": { "$ref": "#/components/schemas/handler_operations_json_VideoChoiceControl" }, "watermark": { "$ref": "#/components/schemas/handler_operations_json_VideoBooleanControl" }, "camera_fixed": { "$ref": "#/components/schemas/handler_operations_json_VideoBooleanControl" }, "return_last_frame": { "$ref": "#/components/schemas/handler_operations_json_VideoBooleanControl" }, "callback_url": { "$ref": "#/components/schemas/handler_operations_json_VideoHttpsControl" } } }, "required_controls": { "type": "array", "maxItems": 9, "uniqueItems": true, "description": "Every named control must be configured.", "items": { "type": "string", "enum": [ "duration", "resolution", "ratio", "seed", "watermark", "camera_fixed", "return_last_frame", "frames_per_second", "callback_url" ] } }, "exclusive_controls": { "type": "array", "maxItems": 32, "description": "Each pair names distinct configured controls; both cannot have defaults.", "items": { "type": "array", "minItems": 2, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "duration", "resolution", "ratio", "seed", "watermark", "camera_fixed", "return_last_frame", "frames_per_second", "callback_url" ] } } }, "output": { "$ref": "#/components/schemas/handler_operations_json_VideoOutputSchema" }, "callbacks_qualified": { "type": "boolean", "description": "Required for a callback_url declaration; separate adapter/offer qualification and callback authentication still apply." } } }, "handler_operations_json_VideoInputRule": { "type": "object", "additionalProperties": false, "required": [ "maximum_items", "maximum_bytes", "https", "data_mime_types", "roles", "role_required" ], "description": "Item/count bounds cannot exceed the enclosing request limits. Non-text inputs require HTTPS or at least one allowed Base64 MIME type; required roles need at least one allowed role. Names are trimmed, control-free and limited to 256 UTF-8 bytes.", "properties": { "maximum_items": { "type": "integer", "minimum": 1, "maximum": 32 }, "maximum_bytes": { "type": "integer", "minimum": 1, "maximum": 16777216 }, "https": { "type": "boolean" }, "data_mime_types": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "/" } }, "roles": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "role_required": { "type": "boolean" } } }, "handler_operations_json_VideoHttpsControl": { "type": "object", "additionalProperties": false, "required": [ "kind", "maximum_bytes" ], "properties": { "kind": { "type": "string", "const": "https_url" }, "maximum_bytes": { "type": "integer", "minimum": 1, "maximum": 8192 } } }, "handler_operations_json_VendorRoutePricing": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "currency", "api_prompt_rate", "api_completion_rate", "cash_prompt_rate", "cash_completion_rate", "max_input_tokens", "max_output_tokens" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "api_prompt_rate": { "type": "integer", "format": "int64", "minimum": 0, "description": "Currency nanounits per million tokens. JSON integer, not a decimal string. Platform procurement metadata only." }, "api_completion_rate": { "type": "integer", "format": "int64", "minimum": 0, "description": "Currency nanounits per million tokens. JSON integer, not a decimal string. Platform procurement metadata only." }, "cash_prompt_rate": { "type": "integer", "format": "int64", "minimum": 0, "description": "Currency nanounits per million tokens. JSON integer, not a decimal string. Platform procurement metadata only." }, "cash_completion_rate": { "type": "integer", "format": "int64", "minimum": 0, "description": "Currency nanounits per million tokens. JSON integer, not a decimal string. Platform procurement metadata only." }, "max_input_tokens": { "type": "integer", "format": "int64", "minimum": 1, "description": "Operator-attested provider token bound used for pre-dispatch liability admission; not an estimated token count." }, "max_output_tokens": { "type": "integer", "format": "int64", "minimum": 1, "description": "Operator-attested provider token bound used for pre-dispatch liability admission; not an estimated token count." } }, "description": "Confidential route procurement configuration, separate from customer selling tariffs. All fields are required when non-null. Combined charges at the configured bounds must fit a signed 64-bit nanounit amount; invalid or overflowing configurations are rejected. Personal-owned credentials require null pricing." }, "handler_operations_json_VendorModelInput": { "type": "object", "additionalProperties": false, "required": [ "alias", "upstream_model" ], "properties": { "alias": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._/-]+$" }, "upstream_model": { "type": "string", "minLength": 1, "maxLength": 200 }, "enabled": { "type": "boolean", "default": true }, "public_catalog": { "type": "boolean", "default": false }, "capabilities": { "$ref": "#/components/schemas/handler_operations_json_VendorCapabilities" }, "pricing": { "$ref": "#/components/schemas/handler_operations_json_VendorRoutePricing", "description": "Optional validated route pricing. Personal-owned credentials require null pricing; non-null pricing is rejected at save. Null clears pricing; omission preserves existing pricing on updates and leaves cost unknown on creates." }, "expected_revision": { "type": [ "integer", "null" ], "minimum": 1 } } }, "handler_operations_json_ProviderCatalogModel": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "context_length", "catalog" ], "properties": { "catalog": { "$ref": "#/components/schemas/handler_operations_json_CatalogMetadata" }, "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Provider model ID used for inference routing." }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Display name supplied by the provider." }, "context_length": { "type": [ "integer", "null" ], "minimum": 1 } } }, "handler_operations_json_MemberRoleUpdate": { "type": "object", "additionalProperties": false, "required": [ "role", "expected_role" ], "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "expected_role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] } } }, "handler_operations_json_MemberRoleChangeView": { "type": "object", "required": [ "id", "name", "role", "organization_id", "project_id", "revoked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "revoked": { "type": "boolean" } } }, "handler_operations_json_WorkspaceDirectoryEntry": { "type": "object", "required": [ "id", "name", "route_slug", "organization_id", "organization_name", "is_default", "created_at_ms", "active_key_count", "requests_30d", "requests_by_day", "last_request_at_ms", "slug", "slug_aliases" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "route_slug": { "type": "string", "maxLength": 81, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Deprecated compatibility alias for slug.", "deprecated": true }, "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "is_default": { "type": "boolean" }, "created_at_ms": { "type": "integer", "format": "int64" }, "active_key_count": { "type": "integer", "format": "int64", "minimum": 0 }, "requests_30d": { "type": "integer", "format": "int64", "minimum": 0, "description": "Request operations created in the last 30 days; retries count once." }, "requests_by_day": { "type": "array", "description": "UTC daily counts for today and the preceding 29 days, including zero days.", "items": { "type": "object", "required": [ "start_ms", "request_count" ], "properties": { "start_ms": { "type": "integer", "format": "int64" }, "request_count": { "type": "integer", "format": "int64", "minimum": 0 } } } }, "last_request_at_ms": { "type": [ "integer", "null" ], "format": "int64" }, "slug": { "type": "string", "maxLength": 81, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Stable, readable workspace slug. Use in dashboard URLs; renaming preserves it." }, "slug_aliases": { "type": "array", "items": { "type": "string" }, "description": "Previously issued slugs accepted for existing bookmarks." } } }, "handler_operations_json_WorkspaceCreationInput": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Must contain non-whitespace text; at most 200 UTF-8 bytes before trimming. The saved name is trimmed." }, "organization_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Company scope. Members default to their current company. Installation callers may omit it to create a Personal workspace company." }, "spending_limit": { "type": "object", "additionalProperties": false, "required": [ "currency", "limit_nanos" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "limit_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Nonnegative nanounits, at most 9223372036854775807." } }, "description": "Optional lifetime retail cap in an existing company account currency. Requires an owner or installation administrator. Saved atomically with the workspace; omitted means no limit." }, "slug": { "type": "string", "minLength": 1, "maxLength": 48, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Optional unique slug. When omitted, generated from the name using pinyin for Chinese, normalized separators, and a numeric suffix on collisions. The value default is reserved." } } }, "handler_operations_json_CompanyMetadata": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "handler_operations_json_KeyInput": { "type": "object", "additionalProperties": false, "description": "Unknown fields are rejected. Configure per-key customer spending, IP allowlist, rolling request rate, token budgets and concurrent-request limits through their separate key management APIs. Key creation does not set these policies. Workspace and company financial limits still apply; rotation preserves the key lineage policies.", "required": [ "name", "ttl_seconds" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "allowed_models": { "type": "array", "minItems": 1, "default": [ "*" ], "description": "Deprecated. Omit to grant every model available to this workspace; explicit aliases are retained for compatibility. The wildcard must be the only entry when used.", "items": { "type": "string" } }, "ttl_seconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 31536000, "description": "Required. Integer 1 to 31536000 sets a finite lifetime; explicit null creates a key without automatic expiration. Missing, zero or negative values are rejected. Revocation and all lineage limits still apply." } } }, "handler_operations_json_IssuedWorkspaceKey": { "type": "object", "required": [ "id", "token" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "One-time workspace API key secret; store securely. Never present in key metadata reads." } } }, "handler_operations_json_ApiErrorResponse": { "type": "object", "required": [ "error" ], "description": "Gateway application error envelope. This does not describe framework body/path parsing failures or a proxy-generated response. Branch on error.type and HTTP status rather than matching message text.", "properties": { "error": { "type": "object", "required": [ "message", "type", "param", "code" ], "properties": { "message": { "type": "string", "description": "Safe human-readable explanation; not a stable programmatic identifier." }, "type": { "type": "string", "description": "Machine-readable failure category; new categories may be added." }, "param": { "type": "null" }, "code": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code, not a separate application error number." } } } } }, "handler_operations_json_WorkspaceKey": { "type": "object", "required": [ "id", "revision", "name", "allowed_models", "expires_at_ms", "last_used_at_ms", "revoked", "expired", "slug" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "format": "int64", "minimum": 1 }, "name": { "type": "string" }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "expires_at_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix milliseconds for finite expiration. Null means no automatic expiration, not an invalid or unknown timestamp. Rotation preserves this state." }, "last_used_at_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Latest durable dispatch intent in Unix milliseconds. Null means no attributed dispatch is recorded, not that the credential was never authenticated. Rotation preserves the old key's history; its replacement starts without a dispatch record." }, "revoked": { "type": "boolean" }, "expired": { "type": "boolean" }, "slug": { "type": "string", "maxLength": 48, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "description": "Stable readable slug for product URLs. Renaming preserves it." } } }, "handler_operations_json_NativeProviderCapabilities": { "type": "object", "required": [ "complete", "selected_model", "modules" ], "properties": { "complete": { "type": "boolean", "const": true }, "selected_model": { "type": [ "string", "null" ] }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_NativeProviderModule" } } } }, "handler_operations_json_NativeProviderModule": { "type": "object", "required": [ "module", "model_alias", "display_name", "adapter", "video_channel", "management_channel", "context_label", "materials", "human_verification", "reference_inputs" ], "properties": { "module": { "type": "string", "const": "volcengine" }, "model_alias": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "adapter": { "type": "string" }, "video_channel": { "type": "string", "const": "ark-direct-v1" }, "management_channel": { "type": "string", "const": "fastrouter-actions-v1" }, "context_label": { "type": "string", "description": "Meaningful current model/adapter/channel label. Contains no account identifiers." }, "materials": { "$ref": "#/components/schemas/handler_operations_json_NativeProviderMaterials" }, "human_verification": { "type": "boolean", "description": "Supports explicit private H5 verification operations, not proof of human completion or permission to mutate." }, "reference_inputs": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_NativeProviderReferenceInput" } } } }, "handler_operations_json_NativeProviderMaterials": { "type": "object", "required": [ "groups", "assets", "reference_requires_active", "reference_requires_same_context", "reference_requires_dispatch_authorization", "kinds" ], "properties": { "groups": { "type": "boolean", "const": true }, "assets": { "type": "boolean", "const": true }, "reference_requires_active": { "type": "boolean", "const": true }, "reference_requires_same_context": { "type": "boolean", "const": true }, "reference_requires_dispatch_authorization": { "type": "boolean", "const": true }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "image", "audio", "video" ] } } } }, "handler_operations_json_NativeProviderReferenceInput": { "type": "object", "required": [ "kind", "roles", "maximum_items" ], "properties": { "kind": { "type": "string", "enum": [ "image", "audio", "video" ] }, "roles": { "type": "array", "items": { "type": "string" } }, "maximum_items": { "type": "integer", "minimum": 1, "maximum": 32 } } }, "handler_operations_json_WorkspaceKeyDetailPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyDetail" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid", "description": "Present when limit or after selects paging. Null ends the directory." } } }, "handler_operations_json_WorkspaceKeyDetail": { "description": "Workspace management key metadata and customer policies. Never contains the API secret or Provider procurement information.", "allOf": [ { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKey" }, { "type": "object", "required": [ "spending_limits", "request_rate_limit", "token_rate_limit", "concurrency_limit", "token_usage_window", "ip_policy" ], "properties": { "spending_limits": { "type": "array", "items": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeySpendingAccount" } }, "request_rate_limit": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyRequestRate" }, "token_rate_limit": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyTokenRate" }, "concurrency_limit": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyConcurrency" }, "token_usage_window": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyUsageWindow" }, { "type": "null" } ], "description": "Null when no snapshot is available; never infer zero usage." }, "ip_policy": { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyIpPolicy" } } } ] }, "handler_operations_json_WorkspaceKeySpendingAccount": { "type": "object", "required": [ "currency", "limit_nanos", "committed_nanos", "remaining_nanos", "revision" ], "properties": { "currency": { "type": "string" }, "limit_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Customer allowance in currency nanounits; null means unlimited." }, "committed_nanos": { "type": "string", "pattern": "^[0-9]+$", "description": "Customer committed amount in currency nanounits." }, "remaining_nanos": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Remaining customer allowance in currency nanounits; null when unlimited." }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Decimal policy revision; null means no saved policy." } } }, "handler_operations_json_WorkspaceKeyRequestRate": { "type": "object", "required": [ "requests_per_minute", "revision" ], "properties": { "requests_per_minute": { "type": [ "integer", "null" ], "minimum": 0 }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Decimal policy revision; null means no saved policy." } } }, "handler_operations_json_WorkspaceKeyTokenRate": { "type": "object", "required": [ "tokens_per_minute", "revision" ], "properties": { "tokens_per_minute": { "type": [ "integer", "null" ], "minimum": 0 }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Decimal policy revision; null means no saved policy." }, "snapshot_at": { "type": "string", "format": "date-time" }, "known_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "reserved_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "unbounded_requests": { "type": "integer", "minimum": 0 }, "committed_tokens": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } } }, "handler_operations_json_WorkspaceKeyConcurrency": { "type": "object", "required": [ "max_concurrent_requests", "active_requests", "revision" ], "properties": { "max_concurrent_requests": { "type": [ "integer", "null" ], "minimum": 0 }, "active_requests": { "type": "integer", "minimum": 0 }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Decimal policy revision; null means no saved policy." } } }, "handler_operations_json_WorkspaceKeyUsageWindow": { "type": "object", "required": [ "window_seconds", "window_end", "requests", "known_usage_requests", "unknown_usage_requests", "known_prompt_tokens", "known_completion_tokens" ], "properties": { "window_seconds": { "type": "integer", "const": 60 }, "window_end": { "type": "string", "format": "date-time" }, "requests": { "type": "integer", "minimum": 0 }, "known_usage_requests": { "type": "integer", "minimum": 0 }, "unknown_usage_requests": { "type": "integer", "minimum": 0 }, "known_prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "known_completion_tokens": { "type": "string", "pattern": "^[0-9]+$" } } }, "handler_operations_json_WorkspaceKeyIpPolicy": { "type": "object", "required": [ "allowed_cidrs", "revision" ], "properties": { "allowed_cidrs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Null permits any source; an empty array denies every source." }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Decimal policy revision; null means no saved policy." } } }, "handler_operations_json_IssuedWorkspaceKeyDetail": { "type": "object", "required": [ "id", "token", "key" ], "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "One-time secret returned only on creation or rotation. Store securely; never included in key directories or detail reads." }, "key": { "anyOf": [ { "$ref": "#/components/schemas/handler_operations_json_WorkspaceKeyDetail" }, { "type": "null" } ], "description": "Post-write detail snapshot; can be null if the key is removed before this read. The issued secret is still returned only once." } } } }, "securitySchemes": { "memberCookie": { "description": "Browser member session cookie. Same-origin and CSRF checks still apply to browser writes.", "type": "apiKey", "in": "cookie", "name": "__Host-niu_member_session" }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer credential accepted by this operation. Inference uses a workspace API key; management requires an authorized member session or installation credential. See the operation description for required authority and scope." }, "niuApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Niu-API-Key", "description": "Workspace inference API key sent in X-Niu-API-Key. Does not grant member or platform management authority." }, "adminBearerAuth": { "description": "Management bearer credential. The operation determines whether installation authority or a scoped member role is required; ordinary inference keys are insufficient.", "type": "http", "scheme": "bearer" }, "operatorBearer": { "type": "http", "scheme": "bearer", "description": "Member session bearer credential. Provider membership and role are checked per operation; company ownership alone does not grant Provider authority." } }, "parameters": { "billing_openapi_yaml_Organization": { "name": "organization", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "billing_openapi_yaml_Project": { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "billing_openapi_yaml_Invoice": { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "provider_business_openapi_yaml_provider": { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "provider_business_openapi_yaml_days": { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } } }, "responses": { "billing_openapi_yaml_InvoiceIdentity": { "description": "Invoice identity, including an exact idempotent replay", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } } } } } } } } }, "tags": [ { "name": "Model discovery", "description": "Discover models and their published capabilities." }, { "name": "Chat completions", "description": "OpenAI-compatible Chat requests, including dashboard-key invocation." }, { "name": "Responses", "description": "Responses API requests." }, { "name": "Messages and GenerateContent", "description": "Native protocol compatibility. Read each operation’s supported subset." }, { "name": "Embeddings", "description": "Embedding requests and supported response encodings." }, { "name": "Video generation", "description": "Discover video models, estimate a request, submit a job, and retrieve its status and results." }, { "name": "Providers", "description": "Provider identities, model purchase offers, usage and settlements. Each operation documents its actual authority and current constraints." }, { "name": "Provider API connections", "description": "Upstream endpoints, stored credentials, model mappings, discovery and connection diagnostics." }, { "name": "Model routing", "description": "Published routing snapshots and candidate pools." }, { "name": "Authentication", "description": "Sign-in configuration, browser sessions, profile, password and appearance. Credential requirements differ by operation." }, { "name": "Users and sessions", "description": "User identities, roles, sessions and authentication events." }, { "name": "API keys", "description": "Workspace inference keys, key self-introspection, rotation, grants, access policies and limits." }, { "name": "Companies and workspaces", "description": "Company and workspace discovery and lifecycle. Legacy project path segments refer to workspaces." }, { "name": "Chat sessions", "description": "Saved conversations, drafts, exports and archive state. Saving content does not invoke a model." }, { "name": "Generation history", "description": "Durable generation sessions, saved tasks, artifacts and video request drafts." }, { "name": "Workspace assets", "description": "Saved workspace assets and their content." }, { "name": "Media assets and verification", "description": "Upstream-specific asset groups, materials, operations and verification sessions. These are distinct from Provider onboarding." }, { "name": "Image ingestion", "description": "Image sources, inspection, ingestion and readiness reads." }, { "name": "Request logs and usage", "description": "Generation lookups, request history, exports, diagnostics, timing and captured usage reconciliation." }, { "name": "Guardrails", "description": "Policy configuration, previews, history, key bindings and recorded denials." }, { "name": "Financial reports", "description": "Financial summaries and Provider commercial positions. These are privileged reports, not customer account lifecycle APIs." }, { "name": "Customer balances", "description": "Company currency balances, limits, reservations, credit, adjustments and transaction history. Amounts are customer-facing, not Provider costs." }, { "name": "Customer payments", "description": "Top-up methods, checkout history, payment callbacks and payment gateway integrations. Checkout creation is not confirmation of funding." }, { "name": "Branded consumption units", "description": "Versioned unit definitions, purchase conversion rules, unit tariffs, and unit spending limits. Publication does not activate Credits billing." }, { "name": "Customer prices and statements", "description": "Customer selling prices, price enrollment, invoices and statements. Prices are independent of Provider purchase rates." }, { "name": "Branding and settings", "description": "Public branding, theme configuration and runtime settings." }, { "name": "Audit and recovery", "description": "Audit events and financial recovery controls." }, { "name": "Service health", "description": "Process health, readiness and composed extension readiness." }, { "name": "Legacy account and cost APIs", "description": "Compatibility APIs for upstream account metadata and upstream accounting. These are not customer billing accounts or customer charges." } ], "x-tagGroups": [ { "name": "Model APIs", "tags": [ "Model discovery", "Chat completions", "Responses", "Messages and GenerateContent", "Embeddings", "Video generation" ] }, { "name": "Providers and routing", "tags": [ "Providers", "Provider API connections", "Model routing" ] }, { "name": "Authentication and access", "tags": [ "Authentication", "Users and sessions", "API keys" ] }, { "name": "Workspaces and content", "tags": [ "Companies and workspaces", "Chat sessions", "Generation history", "Workspace assets", "Media assets and verification", "Image ingestion" ] }, { "name": "Usage and billing", "tags": [ "Request logs and usage", "Guardrails", "Financial reports", "Customer balances", "Customer payments", "Branded consumption units", "Customer prices and statements" ] }, { "name": "Service and compatibility", "tags": [ "Branding and settings", "Audit and recovery", "Service health", "Legacy account and cost APIs" ] } ] }