{ "openapi": "3.1.0", "info": { "title": "NEAR AI Cloud API", "description": "NEAR AI Cloud API for private AI model inference and organization administration.", "contact": { "name": "NEAR AI Team", "email": "support@near.ai" }, "license": { "name": "MIT" }, "version": "1.0.0" }, "paths": { "/v1/admin/access-tokens": { "get": { "tags": [ "Admin" ], "summary": "List admin access tokens (Admin only)", "description": "Retrieves a paginated list of all admin access tokens in the system.\nOnly authenticated admins can access this endpoint.", "operationId": "list_admin_access_tokens", "parameters": [ { "name": "limit", "in": "query", "description": "Number of records to return (default: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Admin access tokens retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "post": { "tags": [ "Admin" ], "summary": "Create admin access token (Admin only)", "description": "Creates an access token for admin users with customizable expiration time, IP address, and user agent.\nThis is typically used by billing services and other automated systems that need access to admin endpoints.\n\n**Security Note:** These tokens can have very long expiration times and should be used with caution.\nStore them securely and rotate them regularly.", "operationId": "create_admin_access_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminAccessTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Admin access token created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminAccessTokenResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/access-tokens/{token_id}": { "delete": { "tags": [ "Admin" ], "summary": "Delete admin access token (Admin only)", "description": "Revokes an admin access token by setting it as inactive.\nOnly authenticated admins can perform this operation.", "operationId": "delete_admin_access_token", "parameters": [ { "name": "token_id", "in": "path", "description": "ID of the admin access token to revoke", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAdminAccessTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Admin access token revoked successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Admin access token not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/feature-requests": { "get": { "tags": [ "Feature Requests" ], "summary": "List aggregated feature requests for admins.", "operationId": "list_admin_feature_requests", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Aggregated feature requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminFeatureRequestListResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/invitation-email-deliveries": { "get": { "tags": [ "Admin" ], "summary": "List organization invitation email deliveries (Admin only)", "description": "Returns delivery metadata for organization invitation emails without exposing invitation tokens.", "operationId": "list_invitation_email_deliveries", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of deliveries to return (default: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of deliveries to skip (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "organization_id", "in": "query", "description": "Filter by organization ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "recipient_email", "in": "query", "description": "Case-insensitive recipient email substring filter", "required": false, "schema": { "type": "string" } }, { "name": "email_status", "in": "query", "description": "Filter by email delivery status", "required": false, "schema": { "$ref": "#/components/schemas/InvitationEmailStatus" } }, { "name": "invitation_status", "in": "query", "description": "Filter by invitation status", "required": false, "schema": { "$ref": "#/components/schemas/InvitationStatus" } }, { "name": "created_after", "in": "query", "description": "Only invitations created at or after this timestamp", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Only invitations created at or before this timestamp", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Invitation email deliveries retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminInvitationEmailDeliveriesResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/invitation-email-deliveries/{invitation_id}/resend": { "post": { "tags": [ "Admin" ], "summary": "Resend a single organization invitation email (Admin only)", "operationId": "resend_invitation_email", "parameters": [ { "name": "invitation_id", "in": "path", "description": "Invitation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invitation email resend attempted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminInvitationEmailResendResultResponse" } } } }, "400": { "description": "Invitation is not pending or has expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Invitation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models": { "get": { "tags": [ "Admin" ], "summary": "List all models (Admin only)", "description": "Returns a paginated list of all models in the system. By default, only active models are returned.\nUse `include_inactive=true` to also include disabled models.", "operationId": "list_models", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of models to return (default: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of models to skip (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_inactive", "in": "query", "description": "Whether to include inactive (disabled) models (default: false)", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Models retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminModelListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Batch upsert models metadata (Admin only)", "description": "Upserts (inserts or updates) pricing and metadata for one or more models. Only authenticated admins can perform this operation.\nThe body should be an array of objects where each key is a model name and the value is the model data.", "operationId": "batch_upsert_models", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HashMap" } } }, "required": true }, "responses": { "200": { "description": "Models upserted successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModelWithPricing" } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models/deprecate": { "post": { "tags": [ "Admin" ], "summary": "Deprecate a model in favor of another (Admin only)", "description": "Atomically marks `modelId` as deprecated and routes its traffic to\n`successorModelId`:\n1. Adds `modelId` as an alias of `successorModelId`, so existing clients\n sending `model: \"\"` keep working — the alias resolver rewrites\n the request-side `model` field to the successor before backend dispatch,\n and the response's `model` field reflects the canonical (successor) name.\n2. Re-points any pre-existing inbound aliases of `modelId` at the\n successor, so historical aliases keep resolving.\n3. Sets `modelId.isActive = false` so it is hidden from public\n `GET /v1/models` and from `GET /v1/admin/models` unless\n `include_inactive=true`.\n4. Records a `model_history` entry for audit purposes.\n\nAll steps run in a single DB transaction. If the successor is inactive or\neither model is missing, returns 404 without modifying state.", "operationId": "deprecate_model", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecateModelRequest" } } }, "required": true }, "responses": { "200": { "description": "Model deprecated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecateModelResponse" } } } }, "400": { "description": "Invalid request (e.g. self-deprecation, empty model id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Either model not found, or successor is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models/pricing-changes": { "get": { "tags": [ "Admin" ], "summary": "List scheduled pricing changes (Admin only).", "operationId": "list_model_pricing_changes", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status: pending, applying, applied, cancelled, failed. Omit for all.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of changes to return (default: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of changes to skip (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Scheduled pricing changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPricingChangesResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models/pricing-changes/confirm": { "post": { "tags": [ "Admin" ], "summary": "Confirm a batch of scheduled pricing changes and notify affected admins (Admin only).", "description": "Persists the schedule (the background scheduler applies each change at its\neffective date) and sends one consolidated email per affected recipient.", "operationId": "confirm_model_pricing_changes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingChangeBatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Pricing changes scheduled and notifications attempted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingChangeConfirmResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found or inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A pending pricing change already exists for a model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models/pricing-changes/preview": { "post": { "tags": [ "Admin" ], "summary": "Preview a batch of scheduled pricing changes without mutating state (Admin only).", "operationId": "preview_model_pricing_changes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingChangeBatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Pricing change notification preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingChangePreviewResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found or inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models/pricing-changes/{id}": { "delete": { "tags": [ "Admin" ], "summary": "Cancel a pending scheduled pricing change (Admin only).", "operationId": "cancel_model_pricing_change", "parameters": [ { "name": "id", "in": "path", "description": "Scheduled pricing change ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pricing change cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledPricingChangeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pricing change not found or no longer pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models/{model_name}": { "delete": { "tags": [ "Admin" ], "summary": "Delete a model (Admin only)", "description": "Soft deletes a model by setting is_active to false. This preserves historical usage records\nthat reference the model name while preventing it from being used in new requests.\n\n**Note:** Model names containing forward slashes (e.g., \"Qwen/Qwen3-30B-A3B-Instruct-2507\") must be URL-encoded.\nFor example, use \"Qwen%2FQwen3-30B-A3B-Instruct-2507\" in the URL path.", "operationId": "delete_model", "parameters": [ { "name": "model_name", "in": "path", "description": "Model name to delete (URL-encode if it contains slashes)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteModelRequest" } } }, "required": true }, "responses": { "204": { "description": "Model deleted successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models/{model_name}/deprecation/confirm": { "post": { "tags": [ "Admin" ], "summary": "Confirm a planned model deprecation, update the catalog, and notify affected admins.", "operationId": "confirm_model_deprecation", "parameters": [ { "name": "model_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDeprecationRequest" } } }, "required": true }, "responses": { "200": { "description": "Deprecation confirmed and notifications attempted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDeprecationConfirmResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model or successor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models/{model_name}/deprecation/preview": { "post": { "tags": [ "Admin" ], "summary": "Preview affected admins for a planned model deprecation (Admin only).", "operationId": "preview_model_deprecation", "parameters": [ { "name": "model_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDeprecationRequest" } } }, "required": true }, "responses": { "200": { "description": "Deprecation notification preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDeprecationPreviewResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model or successor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/models/{model_name}/history": { "get": { "tags": [ "Admin" ], "summary": "Get complete history for a model (Admin only)", "description": "Returns the complete history for a specific model, showing all changes over time including pricing,\ncontext length, display name, and description.\n\n**Note:** Model names containing forward slashes (e.g., \"Qwen/Qwen3-30B-A3B-Instruct-2507\") must be URL-encoded.\nFor example, use \"Qwen%2FQwen3-30B-A3B-Instruct-2507\" in the URL path.", "operationId": "get_model_history", "parameters": [ { "name": "model_name", "in": "path", "description": "Model name to get complete history for (URL-encode if it contains slashes)", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of history entries to return (default: 50)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of history entries to skip (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Model history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelHistoryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}": { "get": { "tags": [ "Admin" ], "summary": "Get a single organization by id (Admin only)", "description": "Returns one organization with its spend limit and usage. Only authenticated\nadmins can perform this operation. Returns 404 if the organization does not\nexist or is inactive (consistent with the admin organizations list, which\nhides inactive orgs).", "operationId": "get_organization", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminOrganizationResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}/concurrent-limit": { "get": { "tags": [ "Admin" ], "summary": "Get organization concurrent request limit (Admin only)", "description": "Returns the current concurrent request limit for an organization.\nIf no custom limit is set, returns null for concurrent_limit and the default (64) for effective_limit.", "operationId": "get_organization_concurrent_limit", "parameters": [ { "name": "org_id", "in": "path", "description": "The organization's ID (as a UUID)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Concurrent limit retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrganizationConcurrentLimitResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Update organization concurrent request limit (Admin only)", "description": "Updates the maximum concurrent requests allowed per model for an organization.\nSet to null to use the default limit (64).\nChanges take effect within 5 minutes due to caching.", "operationId": "update_organization_concurrent_limit", "parameters": [ { "name": "org_id", "in": "path", "description": "The organization's ID (as a UUID)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationConcurrentLimitRequest" } } }, "required": true }, "responses": { "200": { "description": "Concurrent limit updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationConcurrentLimitResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}/limits": { "patch": { "tags": [ "Admin" ], "summary": "Update organization limits (Admin only)", "description": "Updates spending limits for a specific organization. This endpoint is typically called by\na billing service with an admin API key when a customer makes a purchase.", "operationId": "update_organization_limits", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID to update limits for", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationLimitsRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization limits updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationLimitsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}/limits/history": { "get": { "tags": [ "Admin" ], "summary": "Get limits history for an organization (Admin only)", "description": "Returns the complete limits history for a specific organization, showing all limits changes over time.\nGet limits history for an organization (Admin only)\n\nReturns the complete limits history for a specific organization, showing all limits changes over time.", "operationId": "get_organization_limits_history", "parameters": [ { "name": "org_id", "in": "path", "description": "The organization's ID (as a UUID)", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of history records to return (default: 50)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Limits history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgLimitsHistoryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}/members": { "get": { "tags": [ "Admin" ], "summary": "List members of a specific organization (Admin only)", "description": "Returns the members of the given organization with full user details\n(email, last login, active status), consistent with `/v1/admin/users`.\nOnly authenticated admins can perform this operation.", "operationId": "list_organization_members", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Maximum number of members to return (default: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of members to skip (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Organization members retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminOrganizationMembersResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}/metrics": { "get": { "tags": [ "Admin" ], "summary": "Get organization metrics (Admin only)", "description": "Returns usage metrics for an organization including summary totals,\nand breakdowns by workspace, API key, and model.", "operationId": "get_organization_metrics", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID to get metrics for", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Start of time range (ISO 8601). Defaults to 30 days ago.", "required": false, "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "End of time range (ISO 8601). Defaults to now.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization metrics retrieved successfully" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}/metrics/timeseries": { "get": { "tags": [ "Admin" ], "summary": "Get time series metrics for an organization (Admin only)", "description": "Returns daily/weekly/hourly aggregations for charting:\nrequests, tokens, and cost per time period.", "operationId": "get_organization_timeseries", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID to get metrics for", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Start of time range (ISO 8601). Defaults to 30 days ago.", "required": false, "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "End of time range (ISO 8601). Defaults to now.", "required": false, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "description": "Time granularity: hour, day (default), or week", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Time series metrics retrieved successfully" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}/staking/farm": { "get": { "tags": [ "Admin" ], "summary": "Get admin organization staking farm state", "description": "Returns the staking farm source and last synced farm-credit state for any\norganization. Requires platform admin access.", "operationId": "get_admin_organization_staking_farm", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization staking farm state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakingFarmStateResponse" } } } }, "400": { "description": "Invalid organization ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No staking farm source found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}/staking/farm/sync": { "post": { "tags": [ "Admin" ], "summary": "Sync admin organization staking farm credits", "description": "Refreshes staking farm reward units and derived credits for any linked\norganization. Requires platform admin access.", "operationId": "sync_admin_organization_staking_farm", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Synced organization staking farm state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakingFarmStateResponse" } } } }, "400": { "description": "Invalid organization ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No staking farm source found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/organizations/{org_id}/usage/balance": { "get": { "tags": [ "Admin" ], "summary": "Get organization balance (Admin only)", "description": "Returns the current spending balance for an organization without requiring\nthe caller to be a member of that organization. Intended for trusted\nautomated billing services.", "operationId": "get_admin_organization_balance", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationBalanceResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/platform/billing-summary": { "get": { "tags": [ "Admin" ], "summary": "Get the platform billing summary (Admin only)", "description": "Credit LIMITS (caps) and consumption — NOT payments/cash. Returns active paid/grant\ncredit limits, total consumed, paying/granted org counts, and a breakdown by funding\nsource. Real money-in lives in the billing service, not cloud-api.", "operationId": "get_billing_summary", "responses": { "200": { "description": "Billing summary retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSummary" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/platform/infra-summary": { "get": { "tags": [ "Admin" ], "summary": "Get the platform infrastructure / fleet burn summary (Admin only)", "description": "Fetches the live host list, counts active/idle hosts, and computes the monthly/daily\nGPU burn rate from the configured cost-per-host. Degrades gracefully (stale=true) if\nthe host inventory is unreachable.", "operationId": "get_infra_summary", "responses": { "200": { "description": "Infra summary retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfraSummary" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/platform/metrics": { "get": { "tags": [ "Admin" ], "summary": "Get platform-wide metrics for admin dashboards (Admin only)", "description": "Returns aggregated metrics across all organizations including:\n- Total users and organizations\n- Total requests and revenue\n- Top models by usage\n- Top organizations by spend", "operationId": "get_platform_metrics", "parameters": [ { "name": "start", "in": "query", "description": "Start of time range (ISO 8601). Defaults to 30 days ago.", "required": false, "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "End of time range (ISO 8601). Defaults to now.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Platform metrics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformMetrics" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/platform/metrics/timeseries": { "get": { "tags": [ "Admin" ], "summary": "Get platform-wide time series for admin dashboards (Admin only)", "description": "Returns per-bucket requests, tokens, cost (paid/granted + verifiable/external splits),\nactive organizations, and new signups for growth/mix trend charts.", "operationId": "get_platform_timeseries", "parameters": [ { "name": "start", "in": "query", "description": "Start of time range (ISO 8601). Defaults to 30 days ago.", "required": false, "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "End of time range (ISO 8601). Defaults to now.", "required": false, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "description": "Time granularity: hour, day (default), week, or month", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Platform time series retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTimeSeriesMetrics" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/platform/model-revenue": { "get": { "tags": [ "Admin" ], "summary": "Get the per-model consumption ranking (Admin only)", "description": "Models for the selected period ranked by consumed cost, with requests, tokens,\nunique orgs, verifiable flag, provider type, and latency. Paginated and filterable.", "operationId": "get_model_revenue", "parameters": [ { "name": "start", "in": "query", "description": "Start of time range (ISO 8601). Defaults to 30 days ago.", "required": false, "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "End of time range (ISO 8601). Defaults to now.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (1-1000, default 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset (default 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "verifiable", "in": "query", "description": "Filter to verifiable (true) or non-verifiable (false) models", "required": false, "schema": { "type": "boolean" } }, { "name": "provider_type", "in": "query", "description": "Filter by provider type (e.g. vllm, external, chutes)", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort: revenue (default), requests, tokens", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model revenue retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelRevenueReport" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/platform/org-revenue": { "get": { "tags": [ "Admin" ], "summary": "Get the per-organization consumption ranking (Admin only)", "description": "Organizations with usage in the selected period ranked by consumed cost, with the\nverifiable/external split, requests, tokens, models used, a current paying flag, and\nlast-usage timestamp. Paginated and filterable — full attribution of usage/spend per org.", "operationId": "get_org_revenue", "parameters": [ { "name": "start", "in": "query", "description": "Start of time range (ISO 8601). Defaults to 30 days ago.", "required": false, "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "End of time range (ISO 8601). Defaults to now.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (1-1000, default 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset (default 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "paying", "in": "query", "description": "Filter to current paying (true) / non-paying (false) orgs", "required": false, "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "description": "Sort: revenue (default), requests, tokens", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Org revenue retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgRevenueReport" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/services": { "post": { "tags": [ "Admin" ], "summary": "Create platform service (Admin only)", "operationId": "create_service", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceRequest" } } }, "required": true }, "responses": { "200": { "description": "Service created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminServiceResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/services/{id}": { "patch": { "tags": [ "Admin" ], "summary": "Update platform service (Admin only; display_name, description, cost_per_unit, is_active)", "operationId": "update_service", "parameters": [ { "name": "id", "in": "path", "description": "Service ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServiceRequest" } } }, "required": true }, "responses": { "200": { "description": "Service updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminServiceResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/admin/users": { "get": { "tags": [ "Admin" ], "summary": "List all registered users with pagination (Admin only)", "description": "Returns a paginated list of all users in the system. Only authenticated admins can perform this operation.", "operationId": "list_users", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of users to return (default: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of users to skip (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_organizations", "in": "query", "description": "Whether to include organization information and spend limits for the first organization owned by each user (default: false)", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Filter users by email, username, display name, user id, auth provider, or provider user id (case-insensitive partial match).", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "Filter users by active status. Omit to include active and inactive users.", "required": false, "schema": { "type": "boolean" } }, { "name": "search_by_name", "in": "query", "description": "Filter users by organization name (case-insensitive match). Only effective when include_organizations=true; separate from user search.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/attestation/ita-token": { "get": { "tags": [ "Attestation" ], "summary": "Get Intel Trust Authority attestation token", "description": "Get Intel Trust Authority signed attestation JWTs for the gateway and, when\nrequested, compatible model provider evidence. Public endpoint — this is an\nexplicit, documented decision (nearai/infra#193): the response carries only\nITA-signed TEE evidence (no customer or key-scoped data), public access lets\nthird parties verify the platform without an account, and upstream ITA rate\nlimits bound abuse (propagated as 429). See\n`build_public_attestation_routes` in `routes/attestation.rs`.", "operationId": "get_ita_token", "parameters": [ { "name": "model", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "nonce", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "signing_algo", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "signing_address", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_tls_fingerprint", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "policy_ids", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "policy_must_match", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "token_signing_alg", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "ITA attestation token retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItaTokenResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "ITA rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad ITA upstream response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "ITA attestation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "ITA request timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ {} ] } }, "/v1/attestation/report": { "get": { "tags": [ "Attestation" ], "summary": "Get attestation report", "description": "Get hardware attestation report for TEE verification. Requires an API key\n(nearai/infra#193); report retrieval is non-billable — no usage or billing\nrecords are created.", "operationId": "get_attestation_report", "parameters": [ { "name": "model", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "signing_algo", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "nonce", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "signing_address", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_tls_fingerprint", "in": "query", "description": "Include TLS certificate fingerprint in the report data.\nDefaults to false; when true, report_data[..32] = SHA256(signing_address || cert_fingerprint).", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "provider", "in": "query", "description": "Restrict the report to a specific serving tier.\nAccepted values: `near` (NEAR AI's own TEE fleet) or `chutes` (attested Chutes fallback).\nWhen omitted, the first successfully responding provider is used.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Attestation report retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationResponse" } } } }, "400": { "description": "Invalid nonce format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/audio/transcriptions": { "post": { "tags": [ "Audio" ], "summary": "Audio transcription endpoint", "description": "Transcribe audio files using Whisper models. Accepts audio file uploads via multipart/form-data.\nSupports MP3, WAV, WEBM, FLAC, OGG, and M4A formats. Maximum file size: 25 MB.\n\n**Request Body (multipart/form-data):**\nAll fields should be provided as text values or files as indicated in the schema.", "operationId": "audio_transcriptions", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioTranscriptionRequestSchema" } } }, "required": true }, "responses": { "200": { "description": "Successful transcription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioTranscriptionResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request (empty file, unsupported format, file too large)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or overloaded — retry with backoff. Check error.type: rate_limit_exceeded or service_overloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/billing/costs": { "post": { "tags": [ "Billing" ], "summary": "Get costs by request IDs", "description": "Returns the cost in nano-USD for each request ID provided. A request ID is\nthe UUID from the `inference-id` response header of /v1/chat/completions\nand /v1/messages responses (equivalently: UUIDv5 of the response body `id`\nunder the DNS namespace). The `x-request-id` response header is a transport\ncorrelation ID and cannot be used here.\n\nRequest IDs that are not found are returned with costNanoUsd: 0\n(HuggingFace-compatible); the response then carries a `warning` field\npointing at the correct ID source. Usage for a just-finished request can\ntake a few seconds to become visible.", "operationId": "get_billing_costs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCostsRequest" } } }, "required": true }, "responses": { "200": { "description": "Costs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCostsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/chat/completions": { "post": { "tags": [ "Chat" ], "summary": "Create chat completion", "description": "Generate AI model responses for chat conversations. Supports both streaming and non-streaming modes.\nOpenAI-compatible endpoint.", "operationId": "chat_completions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } }, "required": true }, "responses": { "200": { "description": "Completion generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or overloaded — retry with backoff. Check error.type: rate_limit_exceeded or service_overloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/check_api_key": { "post": { "tags": [ "Gateway" ], "summary": "Check API key validity", "description": "Validates the provided API key (via Bearer token), checks rate limits,\nand verifies the organization has sufficient credits.\n\nThis endpoint is designed for external model gateways to authenticate\nuser requests before forwarding to inference engines.", "operationId": "check_api_key", "responses": { "200": { "description": "API key is valid and has sufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckApiKeyResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Insufficient credits or spend limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/completions": { "post": { "tags": [ "Chat" ], "summary": "Create text completion", "description": "Generate AI model responses for text prompts. OpenAI-compatible endpoint.", "operationId": "completions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionRequest" } } }, "required": true }, "responses": { "200": { "description": "Completion generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or overloaded — retry with backoff. Check error.type: rate_limit_exceeded or service_overloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/feature-requests": { "post": { "tags": [ "Feature Requests" ], "summary": "Submit or update the current user's interest in a feature request target.", "operationId": "submit_feature_request", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitFeatureRequest" } } }, "required": true }, "responses": { "200": { "description": "Feature request recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitFeatureRequestResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Organization membership required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/health": { "get": { "tags": [ "Health" ], "summary": "Health check", "description": "Check service health status. No authentication required.", "operationId": "health_check", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v1/images/edits": { "post": { "tags": [ "Images" ], "summary": "Edit images from a text prompt and image", "description": "Edit images using an AI model from an image and text description. OpenAI-compatible endpoint.\n\n**Request Body (multipart/form-data):**\nAll fields should be provided as text values or files as indicated in the schema.", "operationId": "image_edits", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageEditRequestSchema" } } }, "required": true }, "responses": { "200": { "description": "Image edited successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or overloaded — retry with backoff. Check error.type: rate_limit_exceeded or service_overloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/images/generations": { "post": { "tags": [ "Images" ], "summary": "Generate images from text prompt", "description": "Generate images using an AI model from a text description. OpenAI-compatible endpoint.", "operationId": "image_generations", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" } } }, "required": true }, "responses": { "200": { "description": "Image generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or overloaded — retry with backoff. Check error.type: rate_limit_exceeded or service_overloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/invitations/{token}": { "get": { "tags": [ "Invitations" ], "summary": "Get invitation details by token (public endpoint)", "description": "Returns invitation details for a specific token. This is a public endpoint\nthat allows users to view invitation details before logging in.", "operationId": "get_invitation_by_token", "parameters": [ { "name": "token", "in": "path", "description": "Invitation token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvitationResponse" } } } }, "404": { "description": "Invitation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Invitation expired or no longer pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/invitations/{token}/accept": { "post": { "tags": [ "Invitations" ], "summary": "Accept invitation by token (requires authentication)", "description": "Accepts an invitation using its token. The authenticated user's email\nmust match the invitation email.", "operationId": "accept_invitation_by_token", "parameters": [ { "name": "token", "in": "path", "description": "Invitation token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation accepted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInvitationResponse" } } } }, "400": { "description": "Bad request - invitation expired or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - invitation belongs to another user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Invitation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "User is already a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/model/list": { "get": { "tags": [ "Models" ], "summary": "List models with pricing", "description": "Get all available models with pricing information. Public endpoint.\n\nThe full model catalog (a few dozen entries) is loaded once and cached\nin-process for a short TTL. `limit` / `offset` slice the cached list\nin memory, so pagination is consistent across pages within a single\ncache window and adds essentially no DB load.", "operationId": "list_models", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of models to return. Defaults to 100. Must be\nnon-negative; values are capped only by the catalog size.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of models to skip from the start of the catalog.\nDefaults to 0. Must be non-negative.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of models with pricing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelListResponse" } } } }, "400": { "description": "Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/model/{model_name}": { "get": { "tags": [ "Models" ], "summary": "Get model details", "description": "Get pricing and metadata for a specific model. URL-encode model names containing slashes. Public endpoint.", "operationId": "get_model_by_name", "parameters": [ { "name": "model_name", "in": "path", "description": "Model name (URL-encode if it contains slashes)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model details with pricing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelWithPricing" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/models": { "get": { "tags": [ "Chat" ], "summary": "List available models", "description": "Returns all AI models available for completions. OpenAI-compatible endpoint.", "operationId": "models", "responses": { "200": { "description": "List of available models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ {} ] } }, "/v1/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List organizations", "description": "Get all organizations you belong to.", "operationId": "list_organizations", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number to return", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number to skip", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "order_by", "in": "query", "description": "Sort by field", "required": false, "schema": { "$ref": "#/components/schemas/OrganizationOrderBy" } }, { "name": "order_direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "$ref": "#/components/schemas/OrganizationOrderDirection" } } ], "responses": { "200": { "description": "List of organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrganizationsResponse" } } } }, "401": { "description": "Invalid or missing session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "post": { "tags": [ "Organizations" ], "summary": "Create a new organization", "description": "Creates a new organization with the authenticated user as owner.", "operationId": "create_organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Organization already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}": { "get": { "tags": [ "Organizations" ], "summary": "Get organization by ID", "description": "Returns organization details for a specific organization ID.", "operationId": "get_organization", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "put": { "tags": [ "Organizations" ], "summary": "Update organization", "description": "Updates organization details for a specific organization ID.", "operationId": "update_organization", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "delete": { "tags": [ "Organizations" ], "summary": "Delete organization (owner only)", "description": "Deletes an organization. Only the organization owner can perform this action.", "operationId": "delete_organization", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization deleted successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Organization is bound to a NEAR staking wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/invitations/{invitation_id}": { "delete": { "tags": [ "Organization Members" ], "summary": "Cancel an organization invitation (short path)", "description": "Cancels a pending invitation for the organization. Only owners and admins can cancel invitations.\nThis endpoint is an alias for `DELETE /v1/organizations/{org_id}/members/invitations/{invitation_id}`.", "operationId": "cancel_invitation", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invitation_id", "in": "path", "description": "Invitation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Invitation cancelled successfully" }, "400": { "description": "Bad request - invitation is not pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not an admin or owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization or invitation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/members": { "get": { "tags": [ "Organization Members" ], "summary": "List organization members with limited user information", "description": "Returns limited user information for privacy and security:\n- All members: See only public user info (username, display name, avatar)\n- Sensitive data (email, last login, etc.) is not exposed to any organization members", "operationId": "list_organization_members", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of records to return (default: 100, max: 1000)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "List of organization members with public user information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrganizationMembersResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not a member of the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "post": { "tags": [ "Organization Members" ], "summary": "Add a member to an organization", "description": "Adds a new member to the organization. The authenticated user must be an owner or admin.", "operationId": "add_organization_member", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOrganizationMemberRequest" } } }, "required": true }, "responses": { "200": { "description": "Member added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMemberResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not an admin or owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "User is already a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/members/invitations": { "get": { "tags": [ "Organization Members" ], "summary": "List organization invitations", "description": "Returns invitations for the organization. Only accessible to owners and admins.", "operationId": "list_organization_invitations", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "$ref": "#/components/schemas/InvitationStatus" } } ], "responses": { "200": { "description": "List of organization invitations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationInvitationResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not an admin or owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/members/invitations/{invitation_id}": { "delete": { "tags": [ "Organization Members" ], "summary": "Cancel an organization invitation", "description": "Cancels a pending invitation for the organization. Only owners and admins can cancel invitations.", "operationId": "cancel_organization_invitation", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invitation_id", "in": "path", "description": "Invitation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Invitation cancelled successfully" }, "400": { "description": "Bad request - invitation is not pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not an admin or owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization or invitation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/members/invite-by-email": { "post": { "tags": [ "Organization Members" ], "summary": "Invite users to an organization by email", "description": "Invites multiple users to the organization by their email addresses. The authenticated user must be an owner or admin.\nReturns results for each invitation attempt, including successes and failures.", "operationId": "invite_organization_member_by_email", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteOrganizationMemberByEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Invitation results (may include partial failures)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteOrganizationMemberByEmailResponse" } } } }, "400": { "description": "Bad request - empty invitation list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not an admin or owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/members/{user_id}": { "put": { "tags": [ "Organization Members" ], "summary": "Update an organization member's role", "description": "Updates a member's role in the organization. The authenticated user must be an owner or admin.\nOnly owners can promote members to owner role.", "operationId": "update_organization_member", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "description": "User ID of the member to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationMemberRequest" } } }, "required": true }, "responses": { "200": { "description": "Member updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMemberResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not an admin or owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "delete": { "tags": [ "Organization Members" ], "summary": "Remove a member from an organization", "description": "Removes a member from the organization. The authenticated user must be an owner or admin,\nor the member can remove themselves. The last owner cannot be removed.", "operationId": "remove_organization_member", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "description": "User ID of the member to remove", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Member removed successfully" }, "400": { "description": "Bad request - cannot remove last owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not an admin or owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/reporting-tokens": { "get": { "tags": [ "Reporting" ], "summary": "List active reporting tokens for an organization.", "description": "The response includes non-secret prefixes and audit timestamps. It never\nincludes raw reporting tokens or stored hashes.", "operationId": "list_reporting_tokens", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Active reporting tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReportingTokensResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "post": { "tags": [ "Reporting" ], "summary": "Create a read-only reporting token.", "description": "Organization owners and admins can create reporting tokens for usage\nexport and summary endpoints. The raw `rpt-` token is returned once.", "operationId": "create_reporting_token", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportingTokenRequest" } } }, "required": true }, "responses": { "201": { "description": "Reporting token created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportingTokenResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/reporting-tokens/{token_id}": { "delete": { "tags": [ "Reporting" ], "summary": "Revoke a reporting token.", "description": "Revoked reporting tokens can no longer authenticate usage reporting\nrequests.", "operationId": "revoke_reporting_token", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "token_id", "in": "path", "description": "Reporting token ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Reporting token revoked" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Reporting token not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/staking/farm": { "get": { "tags": [ "Staking Farm" ], "summary": "Get organization staking farm state", "description": "Returns the staking farm source and last synced farm-credit state for an\norganization. The organization must be the NEAR-authenticated user's default\norganization.", "operationId": "get_organization_staking_farm", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization staking farm state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakingFarmStateResponse" } } } }, "400": { "description": "Invalid organization ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No staking farm source found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/staking/farm/sync": { "post": { "tags": [ "Staking Farm" ], "summary": "Sync organization staking farm credits", "description": "Links or refreshes the NEAR-authenticated user's staking farm source for the\norganization, then syncs reward units from the configured staking contract.", "operationId": "sync_organization_staking_farm", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Synced organization staking farm state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakingFarmStateResponse" } } } }, "400": { "description": "Invalid organization ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "NEAR account conflict or organization inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/usage/balance": { "get": { "tags": [ "Usage" ], "summary": "Get organization balance", "description": "Returns the current spending balance for an organization", "operationId": "get_organization_balance", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationBalanceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/usage/by-model": { "get": { "tags": [ "Usage" ], "summary": "Get organization usage broken down by model.", "description": "Returns one row per model, summed over a rolling window ending now:\n`day` = last 24h, `week` = last 7 days, `month` = last 30 days (NOT calendar\nday/week/month-to-date). Used by the dashboard pie chart to show which models\ndrive spend.", "operationId": "get_organization_usage_by_model", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Rolling window: `day` (last 24h), `week` (last 7d), or `month` (last 30d). Default: `month`", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-model usage breakdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageByModelResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/usage/export": { "get": { "tags": [ "Reporting" ], "summary": "Export organization usage and cost rows.", "description": "Requires a reporting token scoped to the organization in the path. Results\nare returned in descending `(created_at, source, id)` order with opaque\ncursor pagination.", "operationId": "export_usage", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_time", "in": "query", "description": "Inclusive RFC3339 start timestamp. Defaults to 366 days before the effective end_time.", "required": false, "schema": { "type": "string" } }, { "name": "end_time", "in": "query", "description": "Inclusive RFC3339 end timestamp. Defaults to the request time. The effective range must not exceed 366 days.", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Usage source to export. Defaults to all.", "required": false, "schema": { "$ref": "#/components/schemas/ReportingUsageSource" } }, { "name": "workspace_id", "in": "query", "description": "Filter by workspace ID.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "api_key_id", "in": "query", "description": "Filter by API key ID.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "description": "Filter inference rows by model name.", "required": false, "schema": { "type": "string" } }, { "name": "inference_type", "in": "query", "description": "Filter inference rows by inference type.", "required": false, "schema": { "type": "string" } }, { "name": "service_name", "in": "query", "description": "Filter service rows by platform service name.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum rows to return. Defaults to 100 and must not exceed 1000.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous export page.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage export page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingUsageExportResponse" } } } }, "400": { "description": "Invalid filters or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Reporting token is not scoped to this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Reporting rate or concurrency limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Reporting request timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "reporting_token": [] } ] } }, "/v1/organizations/{org_id}/usage/history": { "get": { "tags": [ "Usage" ], "summary": "Get organization usage history", "description": "Returns paginated usage history for an organization", "operationId": "get_organization_usage_history", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of records to return (default: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "start_date", "in": "query", "description": "Inclusive UTC start date in YYYY-MM-DD or RFC3339 format.", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "Inclusive UTC end date in YYYY-MM-DD or RFC3339 format.", "required": false, "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Inclusive RFC3339 start timestamp. Takes precedence over start_date.", "required": false, "schema": { "type": "string" } }, { "name": "end_time", "in": "query", "description": "Inclusive RFC3339 end timestamp. Takes precedence over end_date.", "required": false, "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "description": "Filter by workspace ID.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "api_key_id", "in": "query", "description": "Filter by API key ID.", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Usage history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageHistoryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/usage/metrics": { "get": { "tags": [ "Usage" ], "operationId": "get_user_organization_metrics", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Start date (ISO 8601, default: 30 days ago)", "required": false, "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "End date (ISO 8601, default: now)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization usage metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOrganizationMetrics" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/usage/summary": { "get": { "tags": [ "Reporting" ], "summary": "Summarize organization usage and costs.", "description": "Requires a reporting token scoped to the organization in the path. Totals\ninclude inference and platform service usage by default.", "operationId": "summary_usage", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_time", "in": "query", "description": "Inclusive RFC3339 start timestamp. Defaults to 366 days before the effective end_time.", "required": false, "schema": { "type": "string" } }, { "name": "end_time", "in": "query", "description": "Inclusive RFC3339 end timestamp. Defaults to the request time. The effective range must not exceed 366 days.", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Usage source to summarize. Defaults to all.", "required": false, "schema": { "$ref": "#/components/schemas/ReportingUsageSource" } }, { "name": "workspace_id", "in": "query", "description": "Filter by workspace ID.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "api_key_id", "in": "query", "description": "Filter by API key ID.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "model", "in": "query", "description": "Filter inference usage by model name.", "required": false, "schema": { "type": "string" } }, { "name": "inference_type", "in": "query", "description": "Filter inference usage by inference type.", "required": false, "schema": { "type": "string" } }, { "name": "service_name", "in": "query", "description": "Filter service usage by platform service name.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingUsageSummaryResponse" } } } }, "400": { "description": "Invalid filters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Reporting token is not scoped to this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Reporting rate or concurrency limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Reporting request timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "reporting_token": [] } ] } }, "/v1/organizations/{org_id}/usage/timeseries": { "get": { "tags": [ "Usage" ], "operationId": "get_user_organization_timeseries", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Start date (ISO 8601, default: 30 days ago)", "required": false, "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "End date (ISO 8601, default: now)", "required": false, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "description": "Time bucket size: hour, day, week (default: day)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization usage timeseries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTimeSeriesMetrics" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/organizations/{org_id}/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List workspaces in an organization", "description": "Lists all workspaces within the specified organization. The authenticated user must\nbe a member of the organization to list workspaces.", "operationId": "list_organization_workspaces", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "order_by", "in": "query", "description": "Order by", "required": false, "schema": { "$ref": "#/components/schemas/WorkspaceOrderBy" } }, { "name": "order_direction", "in": "query", "description": "Order direction", "required": false, "schema": { "$ref": "#/components/schemas/WorkspaceOrderDirection" } } ], "responses": { "200": { "description": "Paginated list of workspaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorkspacesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not a member of organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "post": { "tags": [ "Workspaces" ], "summary": "Create a new workspace in an organization", "description": "Creates a new workspace within the specified organization. The authenticated user must\nbe a member of the organization to create workspaces.", "operationId": "create_workspace", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } }, "required": true }, "responses": { "201": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not a member of organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Workspace name already exists in organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/privacy/classify": { "post": { "tags": [ "Privacy" ], "operationId": "privacy_classify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyClassifyRequestDoc" } } }, "required": true }, "responses": { "200": { "description": "Privacy classification completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyClassifyResponseDoc" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or overloaded — retry with backoff. Check error.type: rate_limit_exceeded or service_overloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/privacy/redact": { "post": { "tags": [ "Privacy" ], "operationId": "privacy_redact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyRedactRequestDoc" } } }, "required": true }, "responses": { "200": { "description": "Privacy redaction completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyRedactResponseDoc" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or overloaded — retry with backoff. Check error.type: rate_limit_exceeded or service_overloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/rerank": { "post": { "tags": [ "Rerank" ], "summary": "Document reranking endpoint", "description": "Ranks documents by relevance to a query using a reranker model.\n\n**Concurrent Request Limits:** Each organization has a per-model concurrent request limit (default: 64).\nWhen the limit is reached, new requests will fail with 429 status code. Wait for in-flight requests to complete before retrying.", "operationId": "rerank", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful rerank", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankResponse" } } } }, "400": { "description": "Invalid request (empty documents, invalid model, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or overloaded — retry with backoff. Check error.type: rate_limit_exceeded or service_overloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error (billing failure, provider error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/responses": { "post": { "tags": [ "Responses" ], "summary": "Create response", "description": "Generate a single-turn, stateless AI response with optional streaming.", "operationId": "create_response", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatelessCreateResponseRequestSchema" } } }, "required": true }, "responses": { "200": { "description": "Response created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseObject" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/score": { "post": { "tags": [ "Score" ], "summary": "Text similarity scoring endpoint", "description": "Scores the similarity between two texts using a scoring/ranking model.\n\n**Concurrent Request Limits:** Each organization has a per-model concurrent request limit (default: 64).\nWhen the limit is reached, new requests will fail with 429 status code. Wait for in-flight requests to complete before retrying.", "operationId": "score", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } }, "400": { "description": "Invalid request (empty texts, invalid model, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or overloaded — retry with backoff. Check error.type: rate_limit_exceeded or service_overloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error (billing failure, provider error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/services": { "get": { "tags": [ "Services" ], "summary": "List platform services (public, no auth)", "operationId": "list_services", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Services list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceListResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/services/{service_name}": { "get": { "tags": [ "Services" ], "summary": "Get platform service by name (public, no auth)", "operationId": "get_service_by_name", "parameters": [ { "name": "service_name", "in": "path", "description": "Service name (e.g. web_search)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Service details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceResponse" } } } }, "404": { "description": "Service not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/signature/{chat_id}": { "get": { "tags": [ "Attestation" ], "summary": "Get completion or Responses API signature", "description": "Get a cryptographic signature for a chat completion or completed stateless\n`resp_*` response. Returns signature data on success, or an unavailable\nresponse if a chat-completion stream was disconnected.", "operationId": "get_signature", "parameters": [ { "name": "chat_id", "in": "path", "description": "Chat completion ID or resp_* Responses API ID", "required": true, "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "signing_algo", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Signature retrieved or unavailable due to disconnect", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Signature not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/staking/farm/config": { "get": { "tags": [ "Staking Farm" ], "summary": "Get staking farm configuration", "description": "Returns the active House of Stake farm configuration used to convert\non-chain staking reward units into NEAR AI Cloud credits.", "operationId": "get_staking_farm_config", "responses": { "200": { "description": "Staking farm configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakingFarmConfigResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/users/me": { "get": { "tags": [ "Users" ], "summary": "Get current user", "description": "Returns the profile of the currently authenticated user, including their organizations and workspaces.", "operationId": "get_current_user", "responses": { "200": { "description": "Current user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "patch": { "tags": [ "Users" ], "summary": "Update current user's profile", "description": "Updates the profile information for the currently authenticated user.", "operationId": "update_current_user_profile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/users/me/access-tokens": { "post": { "tags": [ "Users" ], "summary": "Create a new access token", "description": "Creates a new short-lived access token using the current refresh token.", "operationId": "create_access_token", "responses": { "200": { "description": "Access token created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessAndRefreshTokenResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "refresh_token": [] } ] } }, "/v1/users/me/invitations": { "get": { "tags": [ "Users" ], "summary": "List pending invitations for the current user", "description": "Returns all pending organization invitations for the authenticated user's email.", "operationId": "list_user_invitations", "responses": { "200": { "description": "List of pending invitations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationInvitationWithOrgResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/users/me/invitations/{invitation_id}/accept": { "post": { "tags": [ "Users" ], "summary": "Accept an organization invitation", "description": "Accepts a pending invitation and adds the user as a member of the organization.", "operationId": "accept_invitation", "parameters": [ { "name": "invitation_id", "in": "path", "description": "Invitation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invitation accepted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInvitationResponse" } } } }, "400": { "description": "Bad request - invitation expired or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - invitation belongs to another user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Invitation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "User is already a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/users/me/invitations/{invitation_id}/decline": { "post": { "tags": [ "Users" ], "summary": "Decline an organization invitation", "description": "Declines a pending invitation to join an organization.", "operationId": "decline_invitation", "parameters": [ { "name": "invitation_id", "in": "path", "description": "Invitation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invitation declined successfully" }, "400": { "description": "Bad request - invitation not pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - invitation belongs to another user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Invitation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/users/me/refresh-tokens": { "get": { "tags": [ "Users" ], "summary": "Get user's refresh tokens", "description": "Returns all active refresh tokens for the currently authenticated user.", "operationId": "get_user_refresh_tokens", "responses": { "200": { "description": "List of user refresh tokens", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RefreshTokenResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/users/me/refresh-tokens/{refresh_token_id}": { "delete": { "tags": [ "Users" ], "summary": "Revoke a user refresh token", "description": "Revokes a specific refresh token for the currently authenticated user.", "operationId": "revoke_user_refresh_token", "parameters": [ { "name": "refresh_token_id", "in": "path", "description": "Refresh token ID to revoke", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Refresh token revoked successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Refresh token not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/users/me/status": { "get": { "tags": [ "Users" ], "summary": "Get current user's account eligibility status", "description": "Returns a minimal eligibility response for frontend preflight checks. AML/KYT\nprovider details are never exposed in this public response.", "operationId": "get_user_status", "responses": { "200": { "description": "Current account is eligible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Current account is not eligible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/users/me/tokens": { "delete": { "tags": [ "Users" ], "summary": "Revoke all tokens for a user", "description": "Revokes all tokens (both refresh tokens and access tokens) for the currently authenticated user.\nThis deletes all refresh tokens from the database and invalidates all JWT access tokens\nby updating the user's tokens_revoked_at timestamp.", "operationId": "revoke_all_user_tokens", "responses": { "200": { "description": "All tokens revoked successfully", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/workspaces/{workspace_id}": { "get": { "tags": [ "Workspaces" ], "summary": "Get workspace by ID", "description": "Returns workspace details for a specific workspace ID.", "operationId": "get_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workspace details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "put": { "tags": [ "Workspaces" ], "summary": "Update workspace", "description": "Updates workspace details for a specific workspace ID.", "operationId": "update_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete workspace", "description": "Deletes (deactivates) a workspace. Only the workspace creator or organization admin/owner can delete.", "operationId": "delete_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workspace deleted successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/workspaces/{workspace_id}/api-keys": { "get": { "tags": [ "Workspaces" ], "summary": "List API keys for workspace", "description": "Returns a paginated list of all API keys for a workspace with usage information.", "operationId": "list_workspace_api_keys", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Maximum number of results (default: 20)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Number of results to skip (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "order_by", "in": "query", "description": "Field to order by: created_at or usage", "required": false, "schema": { "$ref": "#/components/schemas/ApiKeyOrderBy" } }, { "name": "order_direction", "in": "query", "description": "Sort direction: asc or desc", "required": false, "schema": { "$ref": "#/components/schemas/ApiKeyOrderDirection" } } ], "responses": { "200": { "description": "Paginated list of workspace API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "post": { "tags": [ "Workspaces" ], "summary": "Create API key for workspace", "description": "Creates a new API key for a workspace. Note: The key may take up to 10 seconds\nto become active for authentication due to internal caching.", "operationId": "create_workspace_api_key", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "201": { "description": "API key created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/workspaces/{workspace_id}/api-keys/{api_key_id}/usage/history": { "get": { "tags": [ "Usage" ], "summary": "Get API key usage history", "description": "Returns paginated usage history for a specific API key", "operationId": "get_api_key_usage_history", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } }, { "name": "api_key_id", "in": "path", "description": "API Key ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of records to return (default: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Usage history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageHistoryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/workspaces/{workspace_id}/api-keys/{key_id}": { "delete": { "tags": [ "Workspaces" ], "summary": "Revoke an API key", "description": "Revokes a specific API key from a workspace.", "operationId": "revoke_workspace_api_key", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "path", "description": "API Key ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "API key revoked successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] }, "patch": { "tags": [ "Workspaces" ], "summary": "Update API key", "description": "Updates an API key's name, expiration date, and/or spending limit. The user must be a member of the\norganization that owns the workspace. All fields are optional - only provided fields will be updated.", "operationId": "update_workspace_api_key", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "path", "description": "API Key ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRequest" } } }, "required": true }, "responses": { "200": { "description": "API key updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not authorized to update this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "API key or workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - API key with this name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } }, "/v1/workspaces/{workspace_id}/api-keys/{key_id}/spend-limit": { "patch": { "tags": [ "Workspaces" ], "summary": "Update API key spend limit", "description": "Updates the spending limit for a specific API key. The user must be a member of the\norganization that owns the workspace. Set spend_limit to null to remove the limit.", "operationId": "update_api_key_spend_limit", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "path", "description": "API Key ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeySpendLimitRequest" } } }, "required": true }, "responses": { "200": { "description": "Spend limit updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - not authorized to update this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "API key or workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "session_token": [] } ] } } }, "components": { "schemas": { "AcceptInvitationResponse": { "type": "object", "description": "Accept invitation response", "required": [ "organization_member", "message" ], "properties": { "message": { "type": "string" }, "organization_member": { "$ref": "#/components/schemas/OrganizationMemberResponse" } } }, "AccessAndRefreshTokenResponse": { "type": "object", "description": "Access token + refresh token response model", "required": [ "access_token", "refresh_token", "refresh_token_expiration" ], "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "refresh_token_expiration": { "type": "string", "format": "date-time" } } }, "AddOrganizationMemberRequest": { "type": "object", "description": "Request to add an organization member", "required": [ "user_id", "role" ], "properties": { "role": { "$ref": "#/components/schemas/MemberRole" }, "user_id": { "type": "string" } } }, "AdminAccessTokenResponse": { "type": "object", "description": "Admin access token response model", "required": [ "id", "access_token", "created_by_user_id", "created_at", "expires_at", "name", "reason" ], "properties": { "access_token": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string" } } }, "AdminFeatureRequestListResponse": { "type": "object", "required": [ "requests", "limit", "offset", "total" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/AdminFeatureRequestSummaryResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "AdminFeatureRequestSummaryResponse": { "type": "object", "required": [ "target", "uniqueUserCount", "uniqueOrganizationCount", "latestRequestedAt", "recentVotes" ], "properties": { "latestRequestedAt": { "type": "string", "format": "date-time" }, "recentVotes": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureRequestVoteResponse" } }, "target": { "$ref": "#/components/schemas/FeatureRequestTargetResponse" }, "uniqueOrganizationCount": { "type": "integer", "format": "int64" }, "uniqueUserCount": { "type": "integer", "format": "int64" } } }, "AdminInvitationEmailDeliveryResponse": { "type": "object", "description": "Admin view of invitation email delivery metadata.", "required": [ "organization_id", "organization_name", "invitation_id", "recipient_email", "role", "invitation_status", "email_status", "invited_by_user_id", "created_at", "expires_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "email_last_error": { "type": [ "string", "null" ] }, "email_message_id": { "type": [ "string", "null" ] }, "email_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "email_status": { "$ref": "#/components/schemas/InvitationEmailStatus" }, "expires_at": { "type": "string", "format": "date-time" }, "invitation_id": { "type": "string" }, "invitation_status": { "$ref": "#/components/schemas/InvitationStatus" }, "invited_by_display_name": { "type": [ "string", "null" ] }, "invited_by_email": { "type": [ "string", "null" ] }, "invited_by_user_id": { "type": "string" }, "organization_id": { "type": "string" }, "organization_name": { "type": "string" }, "recipient_email": { "type": "string" }, "responded_at": { "type": [ "string", "null" ], "format": "date-time" }, "role": { "$ref": "#/components/schemas/MemberRole" } } }, "AdminInvitationEmailResendResultResponse": { "type": "object", "description": "Admin invitation email resend result.", "required": [ "invitation_id", "recipient_email", "success", "email_sent", "email_status" ], "properties": { "email_last_error": { "type": [ "string", "null" ] }, "email_message_id": { "type": [ "string", "null" ] }, "email_sent": { "type": "boolean" }, "email_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "email_status": { "$ref": "#/components/schemas/InvitationEmailStatus" }, "error": { "type": [ "string", "null" ] }, "invitation_id": { "type": "string" }, "recipient_email": { "type": "string" }, "success": { "type": "boolean" } } }, "AdminModelListResponse": { "type": "object", "description": "Response for admin model list endpoint", "required": [ "models", "limit", "offset", "total" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/AdminModelWithPricing" } }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "AdminModelWithPricing": { "type": "object", "description": "Model with pricing information for admin listing", "required": [ "modelId", "inputCostPerToken", "outputCostPerToken", "costPerImage", "metadata", "isActive", "createdAt", "updatedAt" ], "properties": { "cacheReadCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice", "description": "Cost per cached input token. Omitted when cache pricing is disabled;\nan amount of 0 means cached tokens are genuinely free." } ] }, "costPerImage": { "$ref": "#/components/schemas/DecimalPrice" }, "createdAt": { "type": "string", "format": "date-time" }, "inputCostPerToken": { "$ref": "#/components/schemas/DecimalPrice" }, "isActive": { "type": "boolean" }, "metadata": { "$ref": "#/components/schemas/ModelMetadata" }, "modelId": { "type": "string" }, "outputCostPerToken": { "$ref": "#/components/schemas/DecimalPrice" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AdminOrganizationMemberResponse": { "type": "object", "description": "Admin organization member response (for owners/admins)\nContains member info with full user details including sensitive data", "required": [ "id", "organization_id", "role", "joined_at", "user" ], "properties": { "id": { "type": "string" }, "invited_by": { "type": [ "string", "null" ] }, "joined_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string" }, "role": { "$ref": "#/components/schemas/MemberRole" }, "user": { "$ref": "#/components/schemas/AdminUserResponse" } } }, "AdminOrganizationResponse": { "type": "object", "description": "Organization details for admin organization listing", "required": [ "id", "name", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "currentUsage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationUsage" } ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "spendLimit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpendLimit" } ] } } }, "AdminServiceListResponse": { "type": "object", "description": "Response for admin service list endpoint", "required": [ "services", "limit", "offset", "total" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/AdminServiceResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "AdminServiceResponse": { "type": "object", "description": "Platform service (admin CRUD) — single item", "required": [ "id", "serviceName", "displayName", "unit", "costPerUnit", "isActive", "createdAt", "updatedAt" ], "properties": { "costPerUnit": { "type": "integer", "format": "int64", "description": "Price per unit in nano-USD (scale 9)." }, "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "isActive": { "type": "boolean" }, "serviceName": { "type": "string" }, "unit": { "$ref": "#/components/schemas/ServiceUnit" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AdminUserOrganizationDetails": { "type": "object", "description": "Organization details with spend limit and usage (for admin user listing)", "required": [ "id", "name" ], "properties": { "currentUsage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationUsage" } ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "spendLimit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpendLimit" } ] } } }, "AdminUserResponse": { "type": "object", "description": "Admin user response model (for owners/admins)\nContains sensitive information only visible to organization owners/admins", "required": [ "id", "email", "created_at", "is_active", "auth_provider", "provider_user_id" ], "properties": { "auth_provider": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "display_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "organizations": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AdminUserOrganizationDetails" } }, "provider_user_id": { "type": "string" }, "username": { "type": [ "string", "null" ] } } }, "ApiKeyResponse": { "type": "object", "description": "API Key response model", "required": [ "id", "key_prefix", "workspace_id", "created_by_user_id", "created_at", "is_active" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "key": { "type": [ "string", "null" ] }, "key_prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "spend_limit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice" } ] }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice" } ] }, "workspace_id": { "type": "string" } } }, "AttestationResponse": { "type": "object", "required": [ "gateway_attestation" ], "properties": { "gateway_attestation": { "$ref": "#/components/schemas/DstackCpuQuote" }, "model_attestations": { "type": "array", "items": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } } }, "ohttp_attestation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OhttpAttestation", "description": "OHTTP key attestation payload. Includes an Ed25519 signature over the decoded\n`key_config` bytes so clients can verify the HPKE key is bound to the TEE." } ] }, "ohttp_key_config": { "type": [ "string", "null" ], "description": "Hex-encoded OHTTP key configuration (RFC 9458). Present only when OHTTP_ENABLED=true.\nLegacy flat field; mirrors `ohttp_attestation.key_config` when present." }, "tls_certificate": { "type": [ "string", "null" ], "description": "TLS certificate file (PEM) from TLS_CERT_PATH; report_data binds via SHA256 of these exact bytes" } } }, "AudioTranscriptionRequestSchema": { "type": "object", "description": "Audio transcription request schema for OpenAPI documentation\nThis represents the multipart/form-data fields", "required": [ "file", "model" ], "properties": { "file": { "type": "string", "description": "Audio file (required) - binary audio data" }, "language": { "type": [ "string", "null" ], "description": "Language code (optional) - e.g. \"en\", \"es\"" }, "model": { "type": "string", "description": "Model identifier (required) - e.g. \"openai/whisper-large-v3\"" }, "response_format": { "type": [ "string", "null" ], "description": "Response format (optional) - one of: \"json\", \"text\", \"verbose_json\"" }, "timestamp_granularities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Timestamp granularities (optional) - supports \"segment\" and \"word\" with verbose_json.\nMultipart requests may send repeated timestamp_granularities[] fields,\nrepeated timestamp_granularities fields, or comma-separated values." } } }, "AudioTranscriptionResponse": { "type": "object", "description": "Audio transcription response (with OpenAPI schema)", "required": [ "text" ], "properties": { "duration": { "type": [ "number", "null" ], "format": "double", "description": "Total audio duration in seconds" }, "language": { "type": [ "string", "null" ], "description": "Detected language code" }, "segments": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/TranscriptionSegment" }, "description": "Transcription segments with timing" }, "text": { "type": "string", "description": "Transcribed text" }, "words": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/TranscriptionWord" }, "description": "Word-level timing information" } } }, "BillingCostsRequest": { "type": "object", "description": "Billing costs request (HuggingFace compatible)", "required": [ "requestIds" ], "properties": { "requestIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of request IDs to get costs for: the UUID values of the\n`inference-id` response header returned by /v1/chat/completions and\n/v1/messages (not the `x-request-id` header)." } } }, "BillingCostsResponse": { "type": "object", "description": "Billing costs response (HuggingFace compatible)", "required": [ "requests" ], "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/RequestCost" }, "description": "Array of request costs" }, "warning": { "type": [ "string", "null" ], "description": "Present when some request IDs matched no usage record for this\norganization (those entries report costNanoUsd 0). Explains where the\ncorrect request IDs come from." } } }, "BillingSourceBreakdown": { "type": "object", "description": "Active credit limit by funding source (caps, not payments).", "required": [ "source", "paid_credit_limit_usd", "org_count" ], "properties": { "org_count": { "type": "integer", "format": "int64" }, "paid_credit_limit_usd": { "type": "number", "format": "double", "description": "Sum of active payment-type spend limits (caps) for this source, USD" }, "source": { "type": "string" } } }, "BillingSummary": { "type": "object", "description": "Platform billing summary — credit LIMITS (caps) and consumption.\n\nThese are spend-limit ceilings from `organization_limits_history`, NOT payments\nor cash received. Real money-in (Stripe top-ups) lives in the billing service\n(nearai-cloud-ui), not in cloud-api.", "required": [ "generated_at", "active_paid_credit_limit_usd", "active_grant_credit_limit_usd", "total_consumed_usd", "inference_consumed_usd", "service_consumed_usd", "paying_org_count", "granted_org_count", "by_source" ], "properties": { "active_grant_credit_limit_usd": { "type": "number", "format": "double", "description": "Sum of active grant-type spend limits (caps), USD" }, "active_paid_credit_limit_usd": { "type": "number", "format": "double", "description": "Sum of active payment-type spend limits (caps), USD" }, "by_source": { "type": "array", "items": { "$ref": "#/components/schemas/BillingSourceBreakdown" } }, "generated_at": { "type": "string", "format": "date-time" }, "granted_org_count": { "type": "integer", "format": "int64" }, "inference_consumed_usd": { "type": "number", "format": "double", "description": "All-time inference consumed cost, USD (organization_usage_log)" }, "paying_org_count": { "type": "integer", "format": "int64" }, "service_consumed_usd": { "type": "number", "format": "double", "description": "All-time service consumed cost, USD (organization_service_usage_log, e.g. web_search)" }, "total_consumed_usd": { "type": "number", "format": "double", "description": "All-time consumed cost across all orgs, USD — **all usage** (from\norganization_balance: inference + services). `inference_consumed_usd +\nservice_consumed_usd` reconcile to this." } } }, "ChatChoice": { "type": "object", "required": [ "index", "message" ], "properties": { "finish_reason": { "type": [ "string", "null" ] }, "index": { "type": "integer", "format": "int64" }, "message": { "$ref": "#/components/schemas/Message" } } }, "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "frequency_penalty": { "type": [ "number", "null" ], "format": "float" }, "max_tokens": { "type": [ "integer", "null" ], "format": "int64" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "model": { "type": "string" }, "n": { "type": [ "integer", "null" ], "format": "int64" }, "presence_penalty": { "type": [ "number", "null" ], "format": "float" }, "stop": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StopSequences", "description": "OpenAI `stop` accepts either a single string or an array of strings." } ] }, "stream": { "type": [ "boolean", "null" ] }, "temperature": { "type": [ "number", "null" ], "format": "float" }, "top_p": { "type": [ "number", "null" ], "format": "float" } }, "additionalProperties": {} }, "ChatCompletionResponse": { "type": "object", "required": [ "id", "object", "created", "model", "choices", "usage" ], "properties": { "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatChoice" } }, "created": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/CompletionUsage" } }, "additionalProperties": { "description": "Unknown top-level fields from the provider (e.g. system_fingerprint, prompt_logprobs).\nRe-emitted when serializing so we do not drop them." } }, "CheckApiKeyResponse": { "type": "object", "description": "Response from the check_api_key endpoint.\n\n`organization_id`, `workspace_id`, and `api_key_id` are returned so\ndownstream gateways (e.g. inference-proxy) have a server-side\nauthoritative subject identity and don't have to trust caller-supplied\nheaders when populating logs / usage records / billing reports. In\nparticular, this lets a trusted gateway report usage to cloud-api with\na shared service token instead of forwarding the user's `sk-…`.", "required": [ "valid", "organization_id", "workspace_id", "api_key_id" ], "properties": { "api_key_id": { "type": "string", "description": "UUID of the API key itself. Used by trusted gateways to attribute\nper-key usage rows without holding the raw `sk-…` value." }, "organization_id": { "type": "string", "description": "Organization the API key belongs to" }, "valid": { "type": "boolean", "description": "Whether the API key is valid and authorized" }, "workspace_id": { "type": "string", "description": "Workspace the API key belongs to" } } }, "CompletionChoice": { "type": "object", "required": [ "index", "text" ], "properties": { "finish_reason": { "type": [ "string", "null" ] }, "index": { "type": "integer", "format": "int64" }, "logprobs": {}, "text": { "type": "string" } } }, "CompletionPrompt": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "integer", "format": "int64" } }, { "type": "array", "items": { "type": "array", "items": { "type": "integer", "format": "int64" } } } ], "description": "OpenAI `/v1/completions` `prompt`: a single string, a batch of strings, or\ntoken-ID array(s). This endpoint serves only the single-string form; the\nother shapes still deserialize (so the handler can return a clean 400 rather\nthan a framework deserialization error) and are rejected there." }, "CompletionRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "best_of": { "type": [ "integer", "null" ], "format": "int64" }, "echo": { "type": [ "boolean", "null" ] }, "frequency_penalty": { "type": [ "number", "null" ], "format": "float" }, "logprobs": { "type": [ "integer", "null" ], "format": "int64" }, "max_tokens": { "type": [ "integer", "null" ], "format": "int64" }, "model": { "type": "string" }, "n": { "type": [ "integer", "null" ], "format": "int64" }, "presence_penalty": { "type": [ "number", "null" ], "format": "float" }, "prompt": { "$ref": "#/components/schemas/CompletionPrompt" }, "stop": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StopSequences" } ] }, "stream": { "type": [ "boolean", "null" ] }, "temperature": { "type": [ "number", "null" ], "format": "float" }, "top_p": { "type": [ "number", "null" ], "format": "float" } }, "additionalProperties": {} }, "CompletionResponse": { "type": "object", "required": [ "id", "object", "created", "model", "choices", "usage" ], "properties": { "choices": { "type": "array", "items": { "$ref": "#/components/schemas/CompletionChoice" } }, "created": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/CompletionUsage" } } }, "CompletionUsage": { "type": "object", "description": "Usage for chat/completions endpoints.\nSerializes as prompt_tokens, completion_tokens, prompt_tokens_details, completion_tokens_details, total_tokens.", "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ], "properties": { "completion_tokens": { "type": "integer", "format": "int32" }, "completion_tokens_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputTokensDetails" } ] }, "prompt_tokens": { "type": "integer", "format": "int32" }, "prompt_tokens_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InputTokensDetails" } ] }, "total_tokens": { "type": "integer", "format": "int32" } } }, "ConversationResponseReference": { "type": "object", "description": "Conversation reference in response object", "required": [ "id" ], "properties": { "id": { "type": "string" } } }, "CreateAdminAccessTokenRequest": { "type": "object", "description": "Admin access token request model", "required": [ "expires_in_hours", "name", "reason" ], "properties": { "expires_in_hours": { "type": "integer", "format": "int64", "description": "Number of hours until the token expires (required)" }, "name": { "type": "string", "description": "Name for the token (required)" }, "reason": { "type": "string", "description": "Reason for creating the token (required)" } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "spendLimit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] } } }, "CreateOrganizationRequest": { "type": "object", "description": "Request to create a new organization", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "additionalProperties": false }, "CreateReportingTokenRequest": { "type": "object", "required": [ "name" ], "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional expiration time. Must be in the future." }, "name": { "type": "string", "description": "Human-readable name for the reporting token." } }, "additionalProperties": false }, "CreateReportingTokenResponse": { "type": "object", "required": [ "id", "organization_id", "name", "token", "token_prefix", "created_by_user_id", "created_at", "scope" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Approximate last-authentication timestamp, refreshed at most once every 15 minutes." }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "scope": { "$ref": "#/components/schemas/ReportingTokenScope" }, "token": { "type": "string", "description": "Raw reporting token. Returned only once when the token is created." }, "token_prefix": { "type": "string", "description": "Non-secret token prefix for display and audit correlation." } } }, "CreateServiceRequest": { "type": "object", "description": "Request to create a platform service (admin)", "required": [ "serviceName", "displayName", "unit", "costPerUnit" ], "properties": { "costPerUnit": { "type": "integer", "format": "int64", "description": "Price per unit in nano-USD (scale 9)." }, "description": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "serviceName": { "type": "string" }, "unit": { "$ref": "#/components/schemas/ServiceUnit" } } }, "CreateWorkspaceRequest": { "type": "object", "description": "Request to create a new workspace", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "CreditLimitBreakdownResponse": { "type": "object", "required": [ "type", "amount", "currency" ], "properties": { "amount": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "type": { "type": "string" } } }, "CreditType": { "type": "string", "description": "Credit type for organization limits\n- grant: Free credits provided by the platform\n- payment: Credits purchased by the organization\n- staking_farm: House of Stake farm reward units converted into credits", "enum": [ "grant", "payment", "staking_farm" ] }, "Datacenter": { "type": "object", "description": "OpenRouter `datacenters` entry: a single datacenter the model runs in.\n\nThe provider spec\n(https://openrouter.ai/docs/guides/community/for-providers) models\n`datacenters` as an array of objects, each with an ISO 3166 Alpha-2\n`country_code`. We store only the country codes (a `TEXT[]`) and\nreconstruct this object wrapper at serialization time.", "required": [ "country_code" ], "properties": { "country_code": { "type": "string", "description": "ISO 3166 Alpha-2 country code (e.g. \"US\"), uppercase." } } }, "DecimalPrice": { "type": "object", "description": "Decimal price for API responses\n\nThe system uses a fixed scale of 9 (nano-dollars = 1 billionth of a dollar).\nThe scale field is included in responses for client convenience.", "required": [ "amount", "scale", "currency" ], "properties": { "amount": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "scale": { "type": "integer", "format": "int64" } } }, "DecimalPriceRequest": { "type": "object", "description": "Decimal price for API requests\n\nThe system internally uses a fixed scale of 9 (nano-dollars = 1 billionth of a dollar).\nClients must provide amounts in nano-dollars.\n\nExamples:\n $100.00 USD: amount=100000000000, currency=\"USD\"\n $1.00 USD: amount=1000000000, currency=\"USD\"\n $0.01 USD: amount=10000000, currency=\"USD\"", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "integer", "format": "int64", "description": "Amount in nano-dollars (scale 9). For example, $1.00 = 1000000000 nano-dollars." }, "currency": { "type": "string" } } }, "DeleteAdminAccessTokenRequest": { "type": "object", "description": "Delete admin access token request model", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Reason for revoking the token (required)" } } }, "DeleteModelRequest": { "type": "object", "description": "Delete model request - optional reason for deletion", "properties": { "changeReason": { "type": [ "string", "null" ] } } }, "DeprecateModelRequest": { "type": "object", "description": "Request to deprecate one model in favor of another.\n\nAtomically:\n- adds `modelId` as an alias of `successorModelId` (so existing clients\n continue to work, with their request-side `model` rewritten to the\n successor at resolution time),\n- re-points any existing inbound aliases of `modelId` at the successor,\n- sets `modelId.isActive = false` so it is hidden from `GET /v1/models`\n and `GET /v1/admin/models` (unless `include_inactive` is set).", "required": [ "modelId", "successorModelId" ], "properties": { "changeReason": { "type": [ "string", "null" ], "description": "Optional reason recorded in the model history." }, "modelId": { "type": "string", "description": "Canonical model_name of the model being deprecated." }, "successorModelId": { "type": "string", "description": "Canonical model_name of the replacement model. Must be active." } } }, "DeprecateModelResponse": { "type": "object", "description": "Response from a deprecation operation.\n\nBoth sides use the public `ModelWithPricing` shape (no `isActive` /\ntimestamps). Confirmation that the deprecation took effect is implicit:\nthe deprecated model is hidden from `GET /v1/admin/models` (default\nlisting) and from public `GET /v1/models`. To inspect `isActive`\ndirectly, call `GET /v1/admin/models?include_inactive=true`.", "required": [ "deprecated", "successor", "aliasesCarried" ], "properties": { "aliasesCarried": { "type": "integer", "format": "int32", "description": "Number of pre-existing **active** inbound aliases of the deprecated\nmodel that were re-pointed at the successor. Does not include the\ndeprecated model's own canonical name (which is added unconditionally\nas a new alias) and does not include inactive inbound aliases (which\nare left untouched — see repository docs).", "minimum": 0 }, "deprecated": { "$ref": "#/components/schemas/ModelWithPricing", "description": "State of the deprecated model after the operation (canonical name\nechoed back in `modelId`; merged alias list reflects the moves)." }, "successor": { "$ref": "#/components/schemas/ModelWithPricing", "description": "State of the successor model after the operation. Its `metadata.aliases`\nincludes the deprecated `modelId` plus any inbound aliases that were\nre-pointed." } } }, "DstackCpuQuote": { "type": "object", "description": "Response for attestation report endpoint", "required": [ "signing_address", "signing_algo", "intel_quote", "event_log", "report_data", "request_nonce", "info" ], "properties": { "event_log": { "type": "string", "description": "The event log associated with the quote" }, "info": { "description": "Application info from Dstack" }, "intel_quote": { "type": "string", "description": "The attestation quote in hexadecimal format" }, "report_data": { "type": "string", "description": "The report data that contains signing address and nonce" }, "request_nonce": { "type": "string", "description": "The nonce used in the attestation request" }, "signing_address": { "type": "string", "description": "The signing address used for the attestation" }, "signing_algo": { "type": "string", "description": "The signing algorithm used for the attestation (ecdsa or ed25519)" }, "tls_cert_fingerprint": { "type": [ "string", "null" ], "description": "SHA-256 hash of the TLS certificate's SPKI, if requested via include_tls_fingerprint." }, "vpc": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VpcInfo", "description": "VPC information (optional)" } ] } } }, "ErrorDetail": { "type": "object", "required": [ "message", "type" ], "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "Evidence": { "type": "object", "description": "Evidence item in NVIDIA payload", "required": [ "certificate" ], "properties": { "certificate": { "type": "string" } } }, "FeatureRequestKind": { "type": "string", "enum": [ "model", "feature" ] }, "FeatureRequestTargetResponse": { "type": "object", "required": [ "id", "kind", "key", "title", "status", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "FeatureRequestVoteResponse": { "type": "object", "required": [ "userId", "userEmail", "updatedAt" ], "properties": { "note": { "type": [ "string", "null" ] }, "organizationId": { "type": [ "string", "null" ], "format": "uuid" }, "organizationName": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" }, "userDisplayName": { "type": [ "string", "null" ] }, "userEmail": { "type": "string" }, "userId": { "type": "string", "format": "uuid" } } }, "FunctionCall": { "type": "object", "required": [ "name", "arguments" ], "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } } }, "FunctionCallOutputType": { "type": "string", "description": "Type marker for function call output input", "enum": [ "function_call_output" ] }, "GetOrganizationConcurrentLimitResponse": { "type": "object", "description": "Response for getting organization concurrent limit", "required": [ "organizationId", "effectiveLimit" ], "properties": { "concurrentLimit": { "type": [ "integer", "null" ], "format": "int32", "description": "Current concurrent limit. Null means default (64) is used.", "minimum": 0 }, "effectiveLimit": { "type": "integer", "format": "int32", "description": "The effective limit (either custom or default)", "minimum": 0 }, "organizationId": { "type": "string" } } }, "HashMap": { "type": "object", "additionalProperties": { "type": "object", "description": "Request to update model pricing (admin endpoint)", "properties": { "aliases": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowFree": { "type": [ "boolean", "null" ], "description": "If true, this model may be activated even when both cost fields are 0.\nRequired to be set explicitly when activating a zero-price model." }, "attestationSupported": { "type": [ "boolean", "null" ], "description": "Whether this model supports TEE attestation" }, "cacheReadCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest", "description": "Cost per cached input token.\n\nTri-state PATCH semantics:\n- omitted → leave unchanged\n- `null` → disable cache pricing (cached tokens billed at the full\n input rate; `cacheReadCostPerToken` / `input_cache_read` omitted from\n catalog responses)\n- a price → set verbatim (an amount of 0 = genuinely free cache reads)" } ] }, "changeReason": { "type": [ "string", "null" ] }, "contextLength": { "type": [ "integer", "null" ], "format": "int32" }, "costPerImage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] }, "datacenters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Datacenter" }, "description": "Datacenters the model runs in (OpenRouter `datacenters`), as\n`[{ \"country_code\": \"US\" }]`. Country codes must be 2-letter\nuppercase ISO 3166 Alpha-2." }, "deprecationDate": { "type": [ "string", "null" ], "description": "OpenRouter `deprecation_date`: ISO 8601 string (`YYYY-MM-DD` or\n`YYYY-MM-DDTHH:00:00Z`). Validated at the write path; rejected if it\ndoes not parse.\n\nTri-state PATCH semantics:\n- omitted → leave unchanged\n- `null` → clear back to \"no planned deprecation\" (column set to NULL)\n- a string → set to the normalized deprecation timestamp" }, "huggingFaceId": { "type": [ "string", "null" ], "description": "HuggingFace identifier (required by OpenRouter when the model is on HF)." }, "inferenceUrl": { "type": [ "string", "null" ], "description": "Base URL for the model's inference endpoint" }, "inputCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] }, "inputModalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Input modalities the model accepts, e.g., [\"text\"], [\"text\", \"image\"]" }, "isActive": { "type": [ "boolean", "null" ] }, "isReady": { "type": [ "boolean", "null" ], "description": "OpenRouter `is_ready`. Stored and exposed verbatim on `GET /v1/models`.\n\nTri-state PATCH semantics:\n- omitted → leave unchanged\n- `null` → clear back to \"unset\" (column set to NULL)\n- `true`/`false` → set verbatim" }, "maxOutputLength": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of output tokens the model can produce in a single response." }, "modelDescription": { "type": [ "string", "null" ] }, "modelDisplayName": { "type": [ "string", "null" ] }, "modelIcon": { "type": [ "string", "null" ] }, "openrouterSlug": { "type": [ "string", "null" ], "description": "OpenRouter `openrouter.slug` override (lowercase `author/slug`, e.g.\n`z-ai/glm-5.1`). Set when our canonical `model_name` does not match\nOpenRouter's slug; surfaced as the nested `openrouter: { slug }` object\non `GET /v1/models`. Validated at the write path; rejected if it does\nnot match the `author/slug` shape.\n\nTri-state PATCH semantics:\n- omitted → leave unchanged\n- `null` → clear back to \"unset\" (column set to NULL)\n- a string → set verbatim" }, "outputCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] }, "outputModalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Output modalities the model produces, e.g., [\"text\"], [\"image\"]" }, "ownedBy": { "type": [ "string", "null" ] }, "providerConfig": { "description": "JSON config for external providers (backend, base_url, etc.)" }, "providerType": { "type": [ "string", "null" ], "description": "Provider type: \"vllm\" (default, TEE-enabled) or \"external\" (3rd party)" }, "quantization": { "type": [ "string", "null" ], "description": "Quantization label (int4/int8/fp4/fp6/fp8/fp16/bf16/fp32)." }, "supportedFeatures": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Feature capabilities (OpenRouter vocabulary)." }, "supportedSamplingParameters": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Sampling parameters accepted by the model (OpenRouter vocabulary)." }, "verifiable": { "type": [ "boolean", "null" ] } } }, "propertyNames": { "type": "string" } }, "HealthResponse": { "type": "object", "description": "Health check response", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Service status" }, "version": { "type": [ "string", "null" ], "description": "Service version (optional)" } } }, "ImageData": { "type": "object", "description": "Individual generated image", "properties": { "b64_json": { "type": [ "string", "null" ], "description": "Base64-encoded image data (when response_format is \"b64_json\")" }, "revised_prompt": { "type": [ "string", "null" ], "description": "Revised prompt used for generation (if model modified it)" }, "url": { "type": [ "string", "null" ], "description": "URL to the generated image (when response_format is \"url\")" } } }, "ImageEditRequestSchema": { "type": "object", "description": "Schema for image edit request documentation in OpenAPI", "required": [ "image", "model", "prompt" ], "properties": { "image": { "type": "string", "format": "binary", "description": "Image file to edit (file upload)" }, "model": { "type": "string", "description": "Model ID to use for editing (e.g., \"Qwen/Qwen-Image-2512\")" }, "prompt": { "type": "string", "description": "Text prompt describing the edits to make" }, "response_format": { "type": [ "string", "null" ], "description": "Response format (\"b64_json\" or \"url\")" }, "size": { "type": [ "string", "null" ], "description": "Image size in WxH format (e.g., \"512x512\")" } } }, "ImageGenerationRequest": { "type": "object", "description": "Request for image generation", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Model ID to use for generation" }, "n": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of images to generate (1-10, default: 1)" }, "prompt": { "type": "string", "description": "Text prompt describing the image to generate" }, "quality": { "type": [ "string", "null" ], "description": "Quality of the generated image: \"standard\" or \"hd\" (\"quality\" parameter is not supported for verifiable models)" }, "response_format": { "type": [ "string", "null" ], "description": "Response format: \"b64_json\" or \"url\" (only \"b64_json\" is supported for verifiable models)" }, "size": { "type": [ "string", "null" ], "description": "Size of the generated images in WxH format (e.g., \"1024x1024\", \"512x512\")" }, "style": { "type": [ "string", "null" ], "description": "Style of the generated image: \"vivid\" or \"natural\" (\"style\" parameter is not supported for verifiable models)" } } }, "ImageGenerationResponse": { "type": "object", "description": "Response from image generation", "required": [ "created", "data" ], "properties": { "created": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the generation was created" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageData" }, "description": "Generated images" } } }, "ImageOutputData": { "type": "object", "properties": { "b64_json": { "type": [ "string", "null" ] }, "revised_prompt": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "InfraSummary": { "type": "object", "description": "Fleet burn summary returned by the admin endpoint.\n\nExposes only counts and burn — never host IPs or per-host model lists.", "required": [ "total_hosts", "active_hosts", "idle_hosts", "cost_per_host_usd_month", "monthly_burn_usd", "daily_burn_usd", "fetched_at", "stale" ], "properties": { "active_hosts": { "type": "integer", "format": "int64", "description": "Hosts serving ≥1 model." }, "cost_per_host_usd_month": { "type": "number", "format": "double" }, "daily_burn_usd": { "type": "number", "format": "double" }, "fetched_at": { "type": "string", "format": "date-time" }, "idle_hosts": { "type": "integer", "format": "int64", "description": "Hosts serving no models (idle capacity we still pay for)." }, "monthly_burn_usd": { "type": "number", "format": "double" }, "stale": { "type": "boolean", "description": "True when this is last-known / fallback data because the live fetch failed." }, "total_hosts": { "type": "integer", "format": "int64" } } }, "InputTokensDetails": { "type": "object", "required": [ "cached_tokens" ], "properties": { "cached_tokens": { "type": "integer", "format": "int64" } } }, "InvitationEmailStatus": { "type": "string", "enum": [ "not_attempted", "sent", "failed", "skipped" ] }, "InvitationEntry": { "type": "object", "description": "Individual invitation entry with email and role", "required": [ "email", "role" ], "properties": { "email": { "type": "string" }, "role": { "$ref": "#/components/schemas/MemberRole" } } }, "InvitationResult": { "type": "object", "description": "Result of a single invitation attempt", "required": [ "email", "success", "email_sent" ], "properties": { "email": { "type": "string" }, "email_error": { "type": [ "string", "null" ] }, "email_sent": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "member": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationMemberResponse" } ] }, "success": { "type": "boolean" } } }, "InvitationStatus": { "type": "string", "description": "Organization invitation status", "enum": [ "pending", "accepted", "declined", "expired" ] }, "InviteOrganizationMemberByEmailRequest": { "type": "object", "description": "Request to invite organization members by email", "required": [ "invitations" ], "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationEntry" } } } }, "InviteOrganizationMemberByEmailResponse": { "type": "object", "description": "Response for batch invitation requests", "required": [ "results", "total", "successful", "failed" ], "properties": { "failed": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationResult" } }, "successful": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "ItaModelAliasResolved": { "type": "object", "required": [ "requested", "canonical" ], "properties": { "canonical": { "type": "string" }, "requested": { "type": "string" } } }, "ItaModelTokenItem": { "type": "object", "required": [ "model", "token", "token_type", "attestation_type", "token_signing_alg" ], "properties": { "attestation_type": { "type": "string" }, "ita_request_id": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "token": { "type": "string" }, "token_signing_alg": { "type": "string" }, "token_type": { "type": "string" } } }, "ItaTokenItem": { "type": "object", "required": [ "token", "token_type", "attestation_type", "token_signing_alg" ], "properties": { "attestation_type": { "type": "string" }, "ita_request_id": { "type": [ "string", "null" ] }, "token": { "type": "string" }, "token_signing_alg": { "type": "string" }, "token_type": { "type": "string" } } }, "ItaTokenResponse": { "type": "object", "required": [ "gateway", "models", "jwks_url", "policy_ids", "policy_must_match", "nonce" ], "properties": { "gateway": { "$ref": "#/components/schemas/ItaTokenItem" }, "jwks_url": { "type": "string" }, "model_alias_resolved": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ItaModelAliasResolved" } ] }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ItaModelTokenItem" } }, "nonce": { "type": "string" }, "policy_ids": { "type": "array", "items": { "type": "string" } }, "policy_must_match": { "type": "boolean" } } }, "ListAdminInvitationEmailDeliveriesResponse": { "type": "object", "description": "Paginated admin invitation email delivery response.", "required": [ "deliveries", "total", "limit", "offset" ], "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/AdminInvitationEmailDeliveryResponse" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "ListAdminOrganizationMembersResponse": { "type": "object", "description": "List organization members response model (admin only).\nExposes full user details (email, last login, active status) for each member.", "required": [ "members", "total", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/AdminOrganizationMemberResponse" } }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "ListApiKeysResponse": { "type": "object", "description": "Paginated API keys list response", "required": [ "api_keys", "total", "limit", "offset" ], "properties": { "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyResponse" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "ListOrganizationMembersResponse": { "type": "object", "description": "List organization members response with pagination", "required": [ "members", "total", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOrganizationMemberResponse" } }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "ListOrganizationsResponse": { "type": "object", "description": "Paginated organizations list response", "required": [ "organizations", "total", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "ListPricingChangesResponse": { "type": "object", "required": [ "changes", "total" ], "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledPricingChangeDto" } }, "total": { "type": "integer", "format": "int64" } } }, "ListReportingTokensResponse": { "type": "object", "required": [ "reporting_tokens", "total" ], "properties": { "reporting_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingTokenResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "ListUsersResponse": { "type": "object", "description": "List users response model (admin only)", "required": [ "users", "total", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUserResponse" } } } }, "ListWorkspacesResponse": { "type": "object", "description": "Paginated workspaces list response", "required": [ "workspaces", "total", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" }, "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "McpApprovalMode": { "type": "string", "enum": [ "always", "never" ], "description": "Simple MCP approval mode" }, "McpApprovalRequirement": { "oneOf": [ { "$ref": "#/components/schemas/McpApprovalMode" }, { "type": "object", "required": [ "never" ], "properties": { "never": { "$ref": "#/components/schemas/McpToolNameFilter" } } } ], "description": "Approval requirement for MCP tool calls" }, "McpDiscoveredTool": { "type": "object", "required": [ "name" ], "properties": { "annotations": {}, "description": { "type": [ "string", "null" ] }, "input_schema": {}, "name": { "type": "string" } } }, "McpToolNameFilter": { "type": "object", "required": [ "tool_names" ], "properties": { "tool_names": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } }, "description": "Filter for tool names that don't require approval" }, "MemberRole": { "type": "string", "description": "Member role enum for API", "enum": [ "owner", "admin", "member" ] }, "Message": { "type": "object", "required": [ "role" ], "properties": { "content": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MessageContent" } ] }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "tool_call_id": { "type": [ "string", "null" ] }, "tool_calls": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ToolCall" } } } }, "MessageAudioUrl": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } ], "description": "vLLM format: audio_url with url field" }, "MessageContent": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/MessageContentPart" } } ], "description": "Content can be text or array of content parts" }, "MessageContentPart": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "cache_control": { "description": "Anthropic prompt-caching breakpoint (`{\"type\":\"ephemeral\"}`), forwarded\nverbatim (#666). Without this field serde drops the breakpoint at\ndeserialization, so it never survives the re-serialize in\n`From for ChatMessage` to reach the Anthropic converter.\nStripped before any non-Anthropic upstream sees it (see\n`inference_providers::strip_cache_control`). Omitted on the wire when\nabsent so the common (uncached) request is byte-identical to before." }, "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "required": [ "image_url", "type" ], "properties": { "cache_control": { "description": "Prompt-caching breakpoint on an image content part (#666). Same\nverbatim forwarding and same non-Anthropic stripping as `Text`." }, "detail": { "type": [ "string", "null" ] }, "image_url": { "$ref": "#/components/schemas/MessageImageUrl" }, "type": { "type": "string", "enum": [ "image_url" ] } } }, { "type": "object", "required": [ "input_audio", "type" ], "properties": { "input_audio": { "$ref": "#/components/schemas/MessageInputAudio" }, "type": { "type": "string", "enum": [ "input_audio" ] } } }, { "type": "object", "required": [ "audio_url", "type" ], "properties": { "audio_url": { "$ref": "#/components/schemas/MessageAudioUrl" }, "type": { "type": "string", "enum": [ "audio_url" ] } } }, { "type": "object", "required": [ "video_url", "type" ], "properties": { "type": { "type": "string", "enum": [ "video_url" ] }, "video_url": { "$ref": "#/components/schemas/MessageVideoUrl" } } }, { "type": "object", "required": [ "file_id", "type" ], "properties": { "file_id": { "type": "string" }, "type": { "type": "string", "enum": [ "file" ] } } } ], "description": "Content part (text, image, audio, video, file)\nSupports both OpenAI format (input_audio) and vLLM format (audio_url, video_url)" }, "MessageImageUrl": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } ] }, "MessageInputAudio": { "type": "object", "description": "OpenAI format: input_audio with data + format", "required": [ "data" ], "properties": { "data": { "type": "string" }, "format": { "type": [ "string", "null" ] } } }, "MessageVideoUrl": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } ], "description": "vLLM format: video_url with url field" }, "ModelArchitecture": { "type": "object", "description": "Model architecture describing input/output modalities", "required": [ "inputModalities", "outputModalities" ], "properties": { "inputModalities": { "type": "array", "items": { "type": "string" }, "description": "Input modalities the model accepts, e.g., [\"text\"], [\"text\", \"image\"]" }, "outputModalities": { "type": "array", "items": { "type": "string" }, "description": "Output modalities the model produces, e.g., [\"text\"], [\"image\"]" } } }, "ModelDeprecationConfirmResponse": { "type": "object", "required": [ "modelId", "successorModelId", "deprecationDate", "recipientCount", "organizationCount", "sentCount", "failedCount", "skippedCount" ], "properties": { "deprecationDate": { "type": "string" }, "failedCount": { "type": "integer", "format": "int64" }, "modelId": { "type": "string" }, "organizationCount": { "type": "integer", "format": "int64" }, "recipientCount": { "type": "integer", "format": "int64" }, "sentCount": { "type": "integer", "format": "int64" }, "skippedCount": { "type": "integer", "format": "int64" }, "successorModelId": { "type": "string" } } }, "ModelDeprecationPreviewResponse": { "type": "object", "required": [ "recipientCount", "organizationCount", "usageWindowDays" ], "properties": { "organizationCount": { "type": "integer", "format": "int64" }, "recipientCount": { "type": "integer", "format": "int64" }, "usageWindowDays": { "type": "integer", "format": "int64" } } }, "ModelDeprecationRequest": { "type": "object", "description": "Request to mark an active model with a planned deprecation date and notify affected admins.", "required": [ "successorModelId", "deprecationDate" ], "properties": { "changeReason": { "type": [ "string", "null" ], "description": "Optional reason recorded in model history." }, "deprecationDate": { "type": "string", "description": "Planned deprecation date (`YYYY-MM-DD` or `YYYY-MM-DDTHH:00:00Z`)." }, "successorModelId": { "type": "string", "description": "Active replacement model to recommend in the email. Does not affect routing." } } }, "ModelHistoryEntry": { "type": "object", "description": "Model history entry - includes pricing, context length, and other model attributes", "required": [ "id", "modelId", "inputCostPerToken", "outputCostPerToken", "costPerImage", "contextLength", "modelName", "modelDisplayName", "modelDescription", "verifiable", "isActive", "ownedBy", "effectiveFrom", "createdAt", "allowFree" ], "properties": { "allowFree": { "type": "boolean", "description": "If true, this model was allowed to serve without pricing at this point in time." }, "cacheReadCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice", "description": "Omitted when cache pricing was disabled at this point in time." } ] }, "changeReason": { "type": [ "string", "null" ] }, "changedByUserEmail": { "type": [ "string", "null" ] }, "changedByUserId": { "type": [ "string", "null" ] }, "contextLength": { "type": "integer", "format": "int32" }, "costPerImage": { "$ref": "#/components/schemas/DecimalPrice" }, "createdAt": { "type": "string" }, "datacenters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Datacenter" }, "description": "Datacenters the model ran in (OpenRouter `datacenters`), e.g.\n`[{ \"country_code\": \"US\" }]`. Omitted when unset." }, "deprecationDate": { "type": [ "string", "null" ] }, "effectiveFrom": { "type": "string" }, "effectiveUntil": { "type": [ "string", "null" ] }, "huggingFaceId": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "inferenceUrl": { "type": [ "string", "null" ], "description": "Base URL for the model's inference endpoint" }, "inputCostPerToken": { "$ref": "#/components/schemas/DecimalPrice" }, "inputModalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Input modalities the model accepts, e.g., [\"text\"], [\"text\", \"image\"]" }, "isActive": { "type": "boolean" }, "isReady": { "type": [ "boolean", "null" ] }, "maxOutputLength": { "type": [ "integer", "null" ], "format": "int32" }, "modelDescription": { "type": "string" }, "modelDisplayName": { "type": "string" }, "modelIcon": { "type": [ "string", "null" ] }, "modelId": { "type": "string" }, "modelName": { "type": "string" }, "openrouterSlug": { "type": [ "string", "null" ], "description": "OpenRouter `openrouter.slug` override the model carried at this point." }, "outputCostPerToken": { "$ref": "#/components/schemas/DecimalPrice" }, "outputModalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Output modalities the model produces, e.g., [\"text\"], [\"image\"]" }, "ownedBy": { "type": "string" }, "quantization": { "type": [ "string", "null" ] }, "supportedFeatures": { "type": "array", "items": { "type": "string" } }, "supportedSamplingParameters": { "type": "array", "items": { "type": "string" } }, "verifiable": { "type": "boolean" } } }, "ModelHistoryResponse": { "type": "object", "description": "Model history response - complete history of model changes", "required": [ "modelName", "history", "total", "limit", "offset" ], "properties": { "history": { "type": "array", "items": { "$ref": "#/components/schemas/ModelHistoryEntry" } }, "limit": { "type": "integer", "format": "int64" }, "modelName": { "type": "string" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "ModelInfo": { "type": "object", "required": [ "id", "object", "created", "owned_by", "supported_sampling_parameters", "supported_features" ], "properties": { "architecture": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelArchitecture", "description": "Model architecture (input/output modalities), legacy nested camelCase shape." } ] }, "context_length": { "type": [ "integer", "null" ], "format": "int32", "description": "Context length in tokens." }, "created": { "type": "integer", "format": "int64" }, "datacenters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Datacenter" }, "description": "Datacenters the model runs in (OpenRouter `datacenters`), e.g.\n`[{ \"country_code\": \"US\" }]`. Omitted when unset." }, "deprecation_date": { "type": [ "string", "null" ], "description": "OpenRouter `deprecation_date`: planned deprecation date as an ISO 8601\nstring. Omitted when there is no planned deprecation." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description (OpenRouter `description`)." }, "hugging_face_id": { "type": [ "string", "null" ], "description": "HuggingFace identifier (OpenRouter `hugging_face_id`)." }, "id": { "type": "string" }, "input_modalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "OpenRouter `input_modalities`: flat snake_case duplicate of architecture.input." }, "is_ready": { "type": [ "boolean", "null" ], "description": "OpenRouter `is_ready`: `false` keeps the model hidden on OpenRouter's\nside, `true` enables auto-staging. Exposed verbatim; omitted when unset." }, "max_output_length": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum output tokens (OpenRouter `max_output_length`)." }, "name": { "type": [ "string", "null" ], "description": "Human-readable model name (OpenRouter `name`)." }, "object": { "type": "string" }, "openrouter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenRouter", "description": "OpenRouter slug override: `{ \"slug\": \"\" }`. Present only when an\noverride is set (our `id` does not match OpenRouter's canonical slug).\nOmitted entirely when unset." } ] }, "output_modalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "OpenRouter `output_modalities`: flat snake_case duplicate of architecture.output." }, "owned_by": { "type": "string" }, "pricing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelPricing", "description": "Pricing information (HuggingFace + OpenRouter compatible)." } ] }, "quantization": { "type": [ "string", "null" ], "description": "Quantization label (OpenRouter `quantization`):\nint4/int8/fp4/fp6/fp8/fp16/bf16/fp32." }, "supported_features": { "type": "array", "items": { "type": "string" }, "description": "Feature capabilities (OpenRouter `supported_features`)." }, "supported_sampling_parameters": { "type": "array", "items": { "type": "string" }, "description": "Sampling parameters accepted by the model (OpenRouter `supported_sampling_parameters`)." }, "top_provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TopProvider", "description": "OpenRouter `top_provider`: per-provider context/output limits." } ] } } }, "ModelListResponse": { "type": "object", "description": "Response for model list endpoint.\n\nThe full catalog (a few dozen entries) is loaded once and cached\nin-process for a short TTL; `limit` / `offset` slice the cached list\nin memory, so successive pages are consistent within a cache window\nand DB load is independent of caller pagination.\n\n`limit` and `offset` echo back the request values (defaults: 100, 0).\n`total` is the full catalog size, used by clients to compute page\ncounts.", "required": [ "models", "limit", "offset", "total" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelWithPricing" } }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "ModelMetadata": { "type": "object", "description": "Model metadata", "required": [ "verifiable", "contextLength", "modelDisplayName", "modelDescription", "ownedBy", "providerType", "attestationSupported" ], "properties": { "aliases": { "type": "array", "items": { "type": "string" } }, "architecture": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelArchitecture", "description": "Model architecture (input/output modalities)" } ] }, "attestationSupported": { "type": "boolean", "description": "Whether this model supports TEE attestation" }, "contextLength": { "type": "integer", "format": "int32" }, "datacenters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Datacenter" }, "description": "Datacenters the model runs in (OpenRouter `datacenters`), e.g.\n`[{ \"country_code\": \"US\" }]`. Omitted when unset." }, "deprecationDate": { "type": [ "string", "null" ], "description": "OpenRouter `deprecation_date`: planned deprecation date as an ISO 8601\nstring. Omitted when there is no planned deprecation." }, "huggingFaceId": { "type": [ "string", "null" ], "description": "HuggingFace identifier (OpenRouter `hugging_face_id`)." }, "inferenceUrl": { "type": [ "string", "null" ], "description": "Base URL for the model's inference endpoint" }, "isReady": { "type": [ "boolean", "null" ], "description": "OpenRouter `is_ready`: stored/exposed verbatim. Omitted when unset." }, "maxOutputLength": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum output tokens per response (OpenRouter `max_output_length`)." }, "modelDescription": { "type": "string" }, "modelDisplayName": { "type": "string" }, "modelIcon": { "type": [ "string", "null" ] }, "openrouterSlug": { "type": [ "string", "null" ], "description": "OpenRouter `openrouter.slug` override (lowercase `author/slug`). Omitted\nwhen unset. On public `GET /v1/models` this surfaces as the nested\n`openrouter: { slug }` object; the admin view exposes the raw value." }, "ownedBy": { "type": "string" }, "providerConfig": { "description": "JSON config for external providers (backend, base_url, etc.)" }, "providerType": { "type": "string", "description": "Provider type: \"vllm\" (TEE-enabled) or \"external\" (3rd party)" }, "quantization": { "type": [ "string", "null" ], "description": "Quantization label (int4/int8/fp4/fp6/fp8/fp16/bf16/fp32)." }, "supportedFeatures": { "type": "array", "items": { "type": "string" }, "description": "Feature capabilities (OpenRouter `supported_features`)." }, "supportedSamplingParameters": { "type": "array", "items": { "type": "string" }, "description": "Sampling parameters accepted by the model (OpenRouter `supported_sampling_parameters`)." }, "verifiable": { "type": "boolean" } } }, "ModelPricing": { "type": "object", "description": "Model pricing information.\n\n`input` / `output` are the legacy HuggingFace-style fields (USD per million\ntokens, as floats). The remaining fields match OpenRouter's provider spec\n(USD per single token, serialized as strings to avoid float precision\nissues): https://openrouter.ai/docs/guides/community/for-providers", "required": [ "input", "output", "prompt", "completion", "image", "request" ], "properties": { "completion": { "type": "string", "description": "OpenRouter: USD per output token, as a string." }, "image": { "type": "string", "description": "OpenRouter: USD per image, as a string (\"0\" when not applicable)." }, "input": { "type": "number", "format": "double", "description": "Price per million input tokens in USD (legacy field, kept for back-compat)." }, "input_cache_read": { "type": [ "string", "null" ], "description": "OpenRouter: USD per cached input token, as a string. Omitted when cache-read\npricing is disabled; `\"0\"` means cached input tokens are genuinely free." }, "output": { "type": "number", "format": "double", "description": "Price per million output tokens in USD (legacy field, kept for back-compat)." }, "prompt": { "type": "string", "description": "OpenRouter: USD per input token, as a string." }, "request": { "type": "string", "description": "OpenRouter: USD per request, as a string (\"0\" when not applicable)." } } }, "ModelProviderRevenueBreakdown": { "type": "object", "required": [ "served_via_fallback", "requests", "tokens", "consumed_cost_usd" ], "properties": { "consumed_cost_usd": { "type": "number", "format": "double" }, "provider_tier": { "type": [ "string", "null" ] }, "provider_type": { "type": [ "string", "null" ] }, "requests": { "type": "integer", "format": "int64" }, "served_via_fallback": { "type": "boolean" }, "tokens": { "type": "integer", "format": "int64" } } }, "ModelRevenueEntry": { "type": "object", "description": "Per-model consumption breakdown entry", "required": [ "model_name", "consumed_cost_usd", "requests", "tokens", "unique_orgs", "verifiable", "served_provider_breakdown", "fallback_requests", "fallback_consumed_cost_usd" ], "properties": { "avg_ttft_ms": { "type": [ "number", "null" ], "format": "double" }, "consumed_cost_usd": { "type": "number", "format": "double", "description": "Consumed usage cost, USD" }, "fallback_consumed_cost_usd": { "type": "number", "format": "double" }, "fallback_requests": { "type": "integer", "format": "int64" }, "model_name": { "type": "string" }, "p95_ttft_ms": { "type": [ "number", "null" ], "format": "double" }, "provider_type": { "type": [ "string", "null" ] }, "requests": { "type": "integer", "format": "int64" }, "served_provider_breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/ModelProviderRevenueBreakdown" } }, "tokens": { "type": "integer", "format": "int64" }, "unique_orgs": { "type": "integer", "format": "int64" }, "verifiable": { "type": "boolean", "description": "Current model metadata (may differ from when the usage occurred)." } } }, "ModelRevenueReport": { "type": "object", "description": "Paginated per-model consumption ranking for a period", "required": [ "period_start", "period_end", "data", "total", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelRevenueEntry" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "period_end": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" }, "total": { "type": "integer", "format": "int64", "description": "Total matching models (before limit/offset)" } } }, "ModelWithPricing": { "type": "object", "description": "Model with pricing information", "required": [ "modelId", "inputCostPerToken", "outputCostPerToken", "costPerImage", "metadata" ], "properties": { "cacheReadCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice", "description": "Cost per cached input token. Omitted when cache pricing is disabled;\nan amount of 0 means cached tokens are genuinely free." } ] }, "costPerImage": { "$ref": "#/components/schemas/DecimalPrice" }, "inputCostPerToken": { "$ref": "#/components/schemas/DecimalPrice" }, "metadata": { "$ref": "#/components/schemas/ModelMetadata" }, "modelId": { "type": "string" }, "outputCostPerToken": { "$ref": "#/components/schemas/DecimalPrice" } } }, "ModelsResponse": { "type": "object", "required": [ "object", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelInfo" } }, "object": { "type": "string" } } }, "NvidiaPayload": { "type": "object", "description": "NVIDIA attestation payload", "required": [ "nonce", "evidence_list" ], "properties": { "evidence_list": { "type": "array", "items": { "$ref": "#/components/schemas/Evidence" } }, "nonce": { "type": "string" } } }, "OhttpAttestation": { "type": "object", "description": "OHTTP attestation payload included in `GET /v1/attestation/report`.\n\nClients verify `signature` (Ed25519 over decoded `key_config` bytes) against\nthe attested `signing_key` to confirm the OHTTP public key is bound to the TEE.", "required": [ "signing_algo", "signing_key", "key_config", "signature" ], "properties": { "key_config": { "type": "string", "description": "Hex-encoded OHTTP key configuration bytes (RFC 9458)." }, "signature": { "type": "string", "description": "Ed25519 signature over the decoded `key_config` bytes." }, "signing_algo": { "type": "string" }, "signing_key": { "type": "string" } } }, "OpenRouter": { "type": "object", "description": "OpenRouter slug-override block.\n\nOpenRouter's provider spec\n(https://openrouter.ai/docs/guides/community/for-providers) requires the\nmodel `id` to EXACTLY match OpenRouter's canonical slug, OR for the provider\nto supply an explicit override via a nested `openrouter` object carrying the\ncanonical slug. We emit this object only when an override is configured.", "required": [ "slug" ], "properties": { "slug": { "type": "string", "description": "OpenRouter's canonical slug for this model (lowercase `author/slug`)." } } }, "OrgLimitsHistoryEntry": { "type": "object", "description": "Organization limits history entry", "required": [ "id", "organizationId", "type", "spendLimit", "effectiveFrom", "createdAt" ], "properties": { "changeReason": { "type": [ "string", "null" ] }, "changedBy": { "type": [ "string", "null" ] }, "changedByUserEmail": { "type": [ "string", "null" ] }, "changedByUserId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "effectiveFrom": { "type": "string" }, "effectiveUntil": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "organizationId": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "spendLimit": { "$ref": "#/components/schemas/SpendLimit" }, "type": { "$ref": "#/components/schemas/CreditType" } } }, "OrgLimitsHistoryResponse": { "type": "object", "description": "Organization limits history response", "required": [ "history", "total", "limit", "offset" ], "properties": { "history": { "type": "array", "items": { "$ref": "#/components/schemas/OrgLimitsHistoryEntry" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "OrgRevenueEntry": { "type": "object", "description": "Per-organization consumption breakdown entry", "required": [ "organization_id", "organization_name", "consumed_cost_usd", "verifiable_consumed_usd", "non_verifiable_consumed_usd", "requests", "tokens", "models_used", "is_paying" ], "properties": { "consumed_cost_usd": { "type": "number", "format": "double", "description": "Consumed usage cost, USD" }, "is_paying": { "type": "boolean", "description": "Current snapshot: org has an active payment-type credit (not historical;\ndoes not yet count postpaid — see #704)." }, "last_usage_at": { "type": [ "string", "null" ], "format": "date-time" }, "models_used": { "type": "integer", "format": "int64" }, "non_verifiable_consumed_usd": { "type": "number", "format": "double" }, "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "requests": { "type": "integer", "format": "int64" }, "tokens": { "type": "integer", "format": "int64" }, "verifiable_consumed_usd": { "type": "number", "format": "double" } } }, "OrgRevenueReport": { "type": "object", "description": "Paginated per-organization consumption ranking for a period", "required": [ "period_start", "period_end", "data", "total", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgRevenueEntry" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "period_end": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" }, "total": { "type": "integer", "format": "int64", "description": "Total matching organizations (before limit/offset)" } } }, "OrganizationBalanceResponse": { "type": "object", "description": "Get organization balance response\nAll costs use fixed scale of 9 (nano-dollars) and USD currency", "required": [ "organization_id", "total_spent", "total_spent_display", "total_requests", "total_tokens", "updated_at", "credit_limits" ], "properties": { "credit_limits": { "type": "array", "items": { "$ref": "#/components/schemas/CreditLimitBreakdownResponse" } }, "last_usage_at": { "type": [ "string", "null" ] }, "organization_id": { "type": "string" }, "remaining": { "type": [ "integer", "null" ], "format": "int64" }, "remaining_display": { "type": [ "string", "null" ] }, "spend_limit": { "type": [ "integer", "null" ], "format": "int64" }, "spend_limit_display": { "type": [ "string", "null" ] }, "total_requests": { "type": "integer", "format": "int64" }, "total_spent": { "type": "integer", "format": "int64" }, "total_spent_display": { "type": "string" }, "total_tokens": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string" } } }, "OrganizationInvitationResponse": { "type": "object", "description": "Organization invitation response", "required": [ "id", "organization_id", "email", "role", "invited_by_user_id", "status", "created_at", "expires_at", "email_status" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string" }, "email_last_error": { "type": [ "string", "null" ] }, "email_message_id": { "type": [ "string", "null" ] }, "email_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "email_status": { "$ref": "#/components/schemas/InvitationEmailStatus" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "invited_by_user_id": { "type": "string" }, "organization_id": { "type": "string" }, "responded_at": { "type": [ "string", "null" ], "format": "date-time" }, "role": { "$ref": "#/components/schemas/MemberRole" }, "status": { "$ref": "#/components/schemas/InvitationStatus" } } }, "OrganizationInvitationWithOrgResponse": { "allOf": [ { "$ref": "#/components/schemas/OrganizationInvitationResponse" }, { "type": "object", "required": [ "organization_name" ], "properties": { "invited_by_display_name": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" } } } ], "description": "Organization invitation with organization details" }, "OrganizationMemberResponse": { "type": "object", "description": "Organization member response model (non-sensitive)", "required": [ "id", "organization_id", "user_id", "role", "joined_at" ], "properties": { "id": { "type": "string" }, "invited_by": { "type": [ "string", "null" ] }, "joined_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string" }, "role": { "$ref": "#/components/schemas/MemberRole" }, "user_id": { "type": "string" } } }, "OrganizationResponse": { "type": "object", "description": "Organization response model", "required": [ "id", "name", "owner_id", "settings", "role", "is_active", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "owner_id": { "type": "string" }, "role": { "$ref": "#/components/schemas/MemberRole" }, "settings": {}, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationUsage": { "type": "object", "description": "Organization usage information (for admin user listing)\nAll costs use fixed scale of 9 (nano-dollars) and USD currency", "required": [ "total_spent", "total_spent_display", "total_requests", "total_tokens" ], "properties": { "total_requests": { "type": "integer", "format": "int64", "description": "Total number of API requests" }, "total_spent": { "type": "integer", "format": "int64", "description": "Total amount spent in nano-dollars (scale 9)" }, "total_spent_display": { "type": "string", "description": "Human readable total spent, e.g., \"$12.50\"" }, "total_tokens": { "type": "integer", "format": "int64", "description": "Total number of tokens used" } } }, "OutputTokensDetails": { "type": "object", "required": [ "reasoning_tokens" ], "properties": { "reasoning_tokens": { "type": "integer", "format": "int64" } } }, "PlatformMetrics": { "type": "object", "description": "Platform-wide metrics for admin dashboard", "required": [ "period_start", "period_end", "generated_at", "total_users", "total_organizations", "total_requests", "total_consumed_usd", "total_tokens", "total_cache_read_tokens", "new_users", "new_organizations", "active_organizations", "paying_organizations", "verifiable_consumed_usd", "verifiable_requests", "non_verifiable_consumed_usd", "non_verifiable_requests", "provider_error_or_timeout_rate", "provider_usage", "top_models", "top_organizations" ], "properties": { "active_organizations": { "type": "integer", "format": "int64", "description": "Organizations that issued ≥1 request in the period" }, "generated_at": { "type": "string", "format": "date-time", "description": "When this response was computed. The `total_users`/`total_organizations`/\n`paying_organizations` fields are **current snapshots as of this time**, not\nperiod-bound like the rest." }, "new_organizations": { "type": "integer", "format": "int64", "description": "Organizations created in the period" }, "new_users": { "type": "integer", "format": "int64", "description": "Users created in the period" }, "non_verifiable_consumed_usd": { "type": "number", "format": "double", "description": "Consumed cost on non-verifiable models, USD (NOT necessarily third-party)" }, "non_verifiable_requests": { "type": "integer", "format": "int64" }, "p95_ttft_ms": { "type": [ "number", "null" ], "format": "double", "description": "95th percentile time-to-first-token across the platform (ms)" }, "paying_organizations": { "type": "integer", "format": "int64", "description": "Snapshot (as of `generated_at`): orgs with an active payment-type credit.\nNOTE: does not yet count postpaid/invoiced customers (see #704)." }, "period_end": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" }, "provider_error_or_timeout_rate": { "type": "number", "format": "double", "description": "Share of requests whose stop_reason ∈ {provider_error, timeout}, 0.0–1.0" }, "provider_usage": { "$ref": "#/components/schemas/PlatformProviderUsage" }, "top_models": { "type": "array", "items": { "$ref": "#/components/schemas/TopModelMetrics" } }, "top_organizations": { "type": "array", "items": { "$ref": "#/components/schemas/TopOrganizationMetrics" } }, "total_cache_read_tokens": { "type": "integer", "format": "int64" }, "total_consumed_usd": { "type": "number", "format": "double", "description": "Total **consumed usage cost** in USD over the period (inference only).\nNOT recognized revenue: grant/payment funding is not separable without\nper-request attribution (tracked in #704)." }, "total_organizations": { "type": "integer", "format": "int64", "description": "Snapshot (as of `generated_at`)." }, "total_requests": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" }, "total_users": { "type": "integer", "format": "int64", "description": "Snapshot (as of `generated_at`)." }, "verifiable_consumed_usd": { "type": "number", "format": "double", "description": "Consumed cost on verifiable (TEE-attested) models, USD" }, "verifiable_requests": { "type": "integer", "format": "int64" } } }, "PlatformProviderUsage": { "type": "object", "required": [ "fallback", "non_fallback", "by_provider_type", "by_provider_tier" ], "properties": { "by_provider_tier": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderTierUsage" } }, "by_provider_type": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderTypeUsage" } }, "fallback": { "$ref": "#/components/schemas/ProviderUsageTotals" }, "non_fallback": { "$ref": "#/components/schemas/ProviderUsageTotals" } } }, "PlatformTimeSeriesMetrics": { "type": "object", "description": "Platform-wide time series response", "required": [ "period_start", "period_end", "granularity", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformTimeSeriesPoint" } }, "granularity": { "type": "string" }, "period_end": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" } } }, "PlatformTimeSeriesPoint": { "type": "object", "description": "One bucket of platform-wide time-series data", "required": [ "date", "requests", "tokens", "cost_usd", "verifiable_cost_usd", "non_verifiable_cost_usd", "active_organizations", "new_organizations", "new_users" ], "properties": { "active_organizations": { "type": "integer", "format": "int64" }, "cost_usd": { "type": "number", "format": "double", "description": "Consumed usage cost for the bucket, USD" }, "date": { "type": "string" }, "new_organizations": { "type": "integer", "format": "int64" }, "new_users": { "type": "integer", "format": "int64" }, "non_verifiable_cost_usd": { "type": "number", "format": "double", "description": "Non-verifiable consumed cost (NOT necessarily third-party), USD" }, "requests": { "type": "integer", "format": "int64" }, "tokens": { "type": "integer", "format": "int64" }, "verifiable_cost_usd": { "type": "number", "format": "double" } } }, "PricingChangeBatchRequest": { "type": "object", "description": "Request to preview or confirm a batch of scheduled pricing changes.", "required": [ "changes" ], "properties": { "batchId": { "type": [ "string", "null" ], "format": "uuid", "description": "Idempotency key for the batch. Generate once client-side and reuse on\nretries so a re-confirm never sends duplicate emails. Confirm\ngenerates one when omitted." }, "changeReason": { "type": [ "string", "null" ], "description": "Optional reason recorded in model history when the change is applied." }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/PricingChangeItemRequest" } } } }, "PricingChangeConfirmResponse": { "type": "object", "required": [ "batchId", "recipientCount", "organizationCount", "sentCount", "failedCount", "skippedCount", "changes" ], "properties": { "batchId": { "type": "string" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledPricingChangeDto" } }, "failedCount": { "type": "integer", "format": "int64" }, "organizationCount": { "type": "integer", "format": "int64" }, "recipientCount": { "type": "integer", "format": "int64" }, "sentCount": { "type": "integer", "format": "int64" }, "skippedCount": { "type": "integer", "format": "int64" } } }, "PricingChangeItemRequest": { "type": "object", "description": "One model's entry in a scheduled pricing change batch.\nOmitted pricing fields are left unchanged; at least one is required.", "required": [ "modelId", "effectiveAt" ], "properties": { "cacheReadCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] }, "costPerImage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] }, "effectiveAt": { "type": "string", "description": "When the new pricing takes effect (`YYYY-MM-DD`, defaults to 13:00\nUTC, or a whole-hour UTC instant `YYYY-MM-DDTHH:00:00Z`). Must be at\nleast one hour in the future." }, "inputCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] }, "modelId": { "type": "string" }, "outputCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] } } }, "PricingChangeModelPreviewDto": { "type": "object", "required": [ "modelId", "modelDisplayName", "effectiveAt", "recipientCount", "organizationCount", "oldPricing", "newPricing" ], "properties": { "effectiveAt": { "type": "string" }, "modelDisplayName": { "type": "string" }, "modelId": { "type": "string" }, "newPricing": { "$ref": "#/components/schemas/PricingFieldUpdates" }, "oldPricing": { "$ref": "#/components/schemas/PricingFields" }, "organizationCount": { "type": "integer", "format": "int64" }, "recipientCount": { "type": "integer", "format": "int64" } } }, "PricingChangePreviewResponse": { "type": "object", "required": [ "recipientCount", "organizationCount", "usageWindowDays", "models" ], "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/PricingChangeModelPreviewDto" } }, "organizationCount": { "type": "integer", "format": "int64" }, "recipientCount": { "type": "integer", "format": "int64", "description": "Distinct recipient emails across the whole batch." }, "usageWindowDays": { "type": "integer", "format": "int64" } } }, "PricingFieldUpdates": { "type": "object", "description": "Partial pricing update; omitted fields are unchanged.", "properties": { "cacheReadCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice" } ] }, "costPerImage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice" } ] }, "inputCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice" } ] }, "outputCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice" } ] } } }, "PricingFields": { "type": "object", "description": "Full pricing snapshot. `cacheReadCostPerToken` is omitted when cache\npricing was disabled at snapshot time.", "required": [ "inputCostPerToken", "outputCostPerToken", "costPerImage" ], "properties": { "cacheReadCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPrice" } ] }, "costPerImage": { "$ref": "#/components/schemas/DecimalPrice" }, "inputCostPerToken": { "$ref": "#/components/schemas/DecimalPrice" }, "outputCostPerToken": { "$ref": "#/components/schemas/DecimalPrice" } } }, "PrivacyClassifyRequestDoc": { "type": "object", "description": "Privacy classification endpoint (passthrough)\n\nProxies privacy classification requests to a token-classification model\n(e.g. `openai/privacy-filter`) that returns PII spans with categories and scores.\nOnly the `model` field is read from the request for routing; the rest is forwarded as-is.\n\nThese documentation-only types approximate the request and response bodies\nfor OpenAPI schema generation. The runtime handler still accepts a raw\n`Bytes` body and forwards it transparently to the provider.", "required": [ "model" ], "properties": { "input": { "description": "Text or list of texts to classify. Either a string or array of strings." }, "model": { "type": "string", "description": "ID of the model to use for privacy classification." }, "threshold": { "type": [ "number", "null" ], "format": "double", "description": "Optional minimum confidence score for returned spans (0.0–1.0)." } } }, "PrivacyClassifyResponseDoc": { "type": "object", "properties": { "data": { "description": "Per-input classification results; each entry contains `spans` and per-input `usage`." }, "model": { "type": "string", "description": "Model identifier that produced the classification." } } }, "PrivacyRedactDataEntryDoc": { "type": "object", "required": [ "index", "redacted" ], "properties": { "index": { "type": "integer", "description": "Index of this entry into the input list (matches input order).", "minimum": 0 }, "redacted": { "type": "string", "description": "Input text rewritten with placeholders in place of detected PII." }, "usage": { "description": "Per-input usage (input_tokens billed for this entry)." } } }, "PrivacyRedactRequestDoc": { "type": "object", "description": "Privacy redaction endpoint\n\nSends each input text through the privacy-filter model and returns it\nrewritten with realistic-looking dummies in place of detected PII\n(e.g. `redacted1@example.com`, `+1-555-0100`, `Redacted001`). Useful as\na one-shot sanitizer ahead of calling a third-party LLM. The original\nPII is **never** echoed back; only the redacted form is returned.\n\nInternally this is a `/v1/privacy/classify` call plus local span-apply\n— same billing (one input_tokens charge per input), same concurrency\nlimits, same model routing.", "required": [ "model" ], "properties": { "input": { "description": "Text or list of texts to redact. Either a string or array of strings." }, "model": { "type": "string", "description": "ID of the model to use for redaction (typically `openai/privacy-filter`)." }, "threshold": { "type": [ "number", "null" ], "format": "double", "description": "Optional minimum confidence score for redacted spans (0.0–1.0)." } } }, "PrivacyRedactResponseDoc": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyRedactDataEntryDoc" }, "description": "Per-input redaction results." }, "model": { "type": "string", "description": "Model identifier that produced the redaction." } } }, "ProviderTierUsage": { "type": "object", "required": [ "requests", "input_tokens", "output_tokens", "total_tokens", "cache_read_tokens", "consumed_cost_usd" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64" }, "consumed_cost_usd": { "type": "number", "format": "double" }, "input_tokens": { "type": "integer", "format": "int64" }, "output_tokens": { "type": "integer", "format": "int64" }, "provider_tier": { "type": [ "string", "null" ] }, "requests": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } }, "ProviderTypeUsage": { "type": "object", "required": [ "requests", "input_tokens", "output_tokens", "total_tokens", "cache_read_tokens", "consumed_cost_usd" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64" }, "consumed_cost_usd": { "type": "number", "format": "double" }, "input_tokens": { "type": "integer", "format": "int64" }, "output_tokens": { "type": "integer", "format": "int64" }, "provider_type": { "type": [ "string", "null" ] }, "requests": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } }, "ProviderUsageTotals": { "type": "object", "required": [ "requests", "input_tokens", "output_tokens", "total_tokens", "cache_read_tokens", "consumed_cost_usd" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64" }, "consumed_cost_usd": { "type": "number", "format": "double" }, "input_tokens": { "type": "integer", "format": "int64" }, "output_tokens": { "type": "integer", "format": "int64" }, "requests": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } }, "PublicOrganizationMemberResponse": { "type": "object", "description": "Public organization member response (for regular members)\nContains member info with limited user details", "required": [ "id", "organization_id", "role", "joined_at", "user" ], "properties": { "id": { "type": "string" }, "joined_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string" }, "role": { "$ref": "#/components/schemas/MemberRole" }, "user": { "$ref": "#/components/schemas/PublicUserResponse" } } }, "PublicUserResponse": { "type": "object", "description": "Public user response model (for regular members)\nOnly contains non-sensitive information visible to all organization members", "required": [ "id", "created_at" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "display_name": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "username": { "type": [ "string", "null" ] } } }, "QuoteResponse": { "type": "object", "description": "Quote response containing gateway quote and allowlist", "required": [ "intel_quote", "event_log" ], "properties": { "event_log": { "type": "string", "description": "The event log associated with the quote" }, "intel_quote": { "type": "string", "description": "The attestation quote in hexadecimal format" } } }, "RecordUsageResponse": { "oneOf": [ { "type": "object", "description": "Response for token-based chat completion usage", "required": [ "id", "model", "input_tokens", "output_tokens", "total_tokens", "cache_read_tokens", "input_cost", "output_cost", "total_cost", "total_cost_display", "created_at", "type" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int32", "description": "Number of prompt tokens that were cache hits (subset of input_tokens)" }, "created_at": { "type": "string", "description": "Timestamp of the recorded entry (RFC3339)" }, "id": { "type": "string", "description": "Unique ID of the recorded usage entry" }, "input_cost": { "type": "integer", "format": "int64", "description": "Input cost in nano-dollars (scale 9)" }, "input_tokens": { "type": "integer", "format": "int32", "description": "Input tokens recorded" }, "model": { "type": "string", "description": "Model name" }, "output_cost": { "type": "integer", "format": "int64", "description": "Output cost in nano-dollars (scale 9)" }, "output_tokens": { "type": "integer", "format": "int32", "description": "Output tokens recorded" }, "total_cost": { "type": "integer", "format": "int64", "description": "Total cost in nano-dollars (scale 9)" }, "total_cost_display": { "type": "string", "description": "Human-readable total cost (e.g., \"$0.00123\")" }, "total_tokens": { "type": "integer", "format": "int32", "description": "Total tokens (input + output)" }, "type": { "type": "string", "enum": [ "chat_completion" ] } } }, { "type": "object", "description": "Response for image generation usage", "required": [ "id", "model", "image_count", "total_cost", "total_cost_display", "created_at", "type" ], "properties": { "created_at": { "type": "string", "description": "Timestamp of the recorded entry (RFC3339)" }, "id": { "type": "string", "description": "Unique ID of the recorded usage entry" }, "image_count": { "type": "integer", "format": "int32", "description": "Number of images generated" }, "model": { "type": "string", "description": "Model name" }, "total_cost": { "type": "integer", "format": "int64", "description": "Total cost in nano-dollars (scale 9)" }, "total_cost_display": { "type": "string", "description": "Human-readable total cost (e.g., \"$5.00\")" }, "type": { "type": "string", "enum": [ "image_generation" ] } } } ], "description": "Usage-recording response body — tagged union matching the request type.\nReturned by `POST /v1/internal/usage`. All costs use fixed scale of 9\n(nano-dollars) and USD currency." }, "RefreshTokenResponse": { "type": "object", "description": "Refresh token response model", "required": [ "id", "user_id", "created_at", "expires_at", "user_agent" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "ip_address": { "type": [ "string", "null" ] }, "user_agent": { "type": "string" }, "user_id": { "type": "string" } } }, "ReportingApiKeySummary": { "type": "object", "required": [ "api_key_id", "request_count", "service_usage_count", "total_cost_nano_usd" ], "properties": { "api_key_id": { "type": "string", "format": "uuid" }, "request_count": { "type": "integer", "format": "int64" }, "service_usage_count": { "type": "integer", "format": "int64" }, "total_cost_nano_usd": { "type": "integer", "format": "int64" } } }, "ReportingDaySummary": { "type": "object", "required": [ "day", "request_count", "service_usage_count", "input_tokens", "output_tokens", "cache_read_tokens", "total_tokens", "inference_cost_nano_usd", "service_cost_nano_usd", "total_cost_nano_usd" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64" }, "day": { "type": "string" }, "inference_cost_nano_usd": { "type": "integer", "format": "int64" }, "input_tokens": { "type": "integer", "format": "int64" }, "output_tokens": { "type": "integer", "format": "int64" }, "request_count": { "type": "integer", "format": "int64" }, "service_cost_nano_usd": { "type": "integer", "format": "int64" }, "service_usage_count": { "type": "integer", "format": "int64" }, "total_cost_nano_usd": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } }, "ReportingInferenceUsage": { "type": "object", "required": [ "model", "inference_type", "input_tokens", "output_tokens", "cache_read_tokens", "total_tokens", "input_cost_nano_usd", "output_cost_nano_usd", "total_cost_nano_usd" ], "properties": { "cache_read_cost_nano_usd": { "type": [ "integer", "null" ], "format": "int64", "description": "Omitted when Cloud API has not persisted a separate cache-read cost split." }, "cache_read_tokens": { "type": "integer", "format": "int64" }, "image_count": { "type": [ "integer", "null" ], "format": "int32" }, "inference_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer-facing request correlation id for v1 reporting.\n\nReporting intentionally excludes upstream provider request ids and provider-attribution fields." }, "inference_type": { "type": "string" }, "input_cost_nano_usd": { "type": "integer", "format": "int64" }, "input_tokens": { "type": "integer", "format": "int64" }, "model": { "type": "string" }, "output_cost_nano_usd": { "type": "integer", "format": "int64" }, "output_tokens": { "type": "integer", "format": "int64" }, "response_id": { "type": [ "string", "null" ], "format": "uuid" }, "total_cost_nano_usd": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } }, "ReportingModelSummary": { "type": "object", "required": [ "model", "request_count", "input_tokens", "output_tokens", "cache_read_tokens", "total_tokens", "total_cost_nano_usd" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64" }, "input_tokens": { "type": "integer", "format": "int64" }, "model": { "type": "string" }, "output_tokens": { "type": "integer", "format": "int64" }, "request_count": { "type": "integer", "format": "int64" }, "total_cost_nano_usd": { "type": "integer", "format": "int64" }, "total_tokens": { "type": "integer", "format": "int64" } } }, "ReportingServiceSummary": { "type": "object", "required": [ "service_name", "usage_count", "quantity", "total_cost_nano_usd" ], "properties": { "quantity": { "type": "integer", "format": "int64" }, "service_name": { "type": "string" }, "total_cost_nano_usd": { "type": "integer", "format": "int64" }, "usage_count": { "type": "integer", "format": "int64" } } }, "ReportingServiceUsage": { "type": "object", "required": [ "service_name", "quantity", "total_cost_nano_usd" ], "properties": { "inference_id": { "type": [ "string", "null" ], "format": "uuid" }, "quantity": { "type": "integer", "format": "int64" }, "service_name": { "type": "string" }, "total_cost_nano_usd": { "type": "integer", "format": "int64" } } }, "ReportingTokenResponse": { "type": "object", "required": [ "id", "organization_id", "name", "token_prefix", "created_by_user_id", "created_at", "scope" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Approximate last-authentication timestamp, refreshed at most once every 15 minutes." }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "scope": { "$ref": "#/components/schemas/ReportingTokenScope" }, "token_prefix": { "type": "string", "description": "Non-secret token prefix for display and audit correlation." } } }, "ReportingTokenScope": { "type": "string", "enum": [ "usage:read" ] }, "ReportingUsageDetails": { "oneOf": [ { "type": "object", "required": [ "inference", "source" ], "properties": { "inference": { "$ref": "#/components/schemas/ReportingInferenceUsage" }, "source": { "type": "string", "enum": [ "inference" ] } } }, { "type": "object", "required": [ "service", "source" ], "properties": { "service": { "$ref": "#/components/schemas/ReportingServiceUsage" }, "source": { "type": "string", "enum": [ "service" ] } } } ] }, "ReportingUsageExportResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingUsageExportRow" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ReportingUsageExportRow": { "allOf": [ { "$ref": "#/components/schemas/ReportingUsageDetails" }, { "type": "object", "required": [ "id", "created_at", "workspace_id", "api_key_id", "total_cost_nano_usd" ], "properties": { "api_key_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "total_cost_nano_usd": { "type": "integer", "format": "int64" }, "total_cost_usd": { "type": [ "string", "null" ] }, "workspace_id": { "type": "string", "format": "uuid" } } } ] }, "ReportingUsageRowSource": { "type": "string", "enum": [ "inference", "service" ] }, "ReportingUsageSource": { "type": "string", "enum": [ "all", "inference", "service" ] }, "ReportingUsageSummaryResponse": { "type": "object", "required": [ "source", "start_time", "end_time", "totals", "by_workspace", "by_api_key", "by_model", "by_service", "by_day" ], "properties": { "by_api_key": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingApiKeySummary" } }, "by_day": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingDaySummary" } }, "by_model": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingModelSummary" } }, "by_service": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingServiceSummary" } }, "by_workspace": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingWorkspaceSummary" } }, "end_time": { "type": "string", "format": "date-time" }, "source": { "$ref": "#/components/schemas/ReportingUsageSource" }, "start_time": { "type": "string", "format": "date-time" }, "totals": { "$ref": "#/components/schemas/ReportingUsageTotals" } } }, "ReportingUsageTotals": { "type": "object", "required": [ "request_count", "service_usage_count", "input_tokens", "output_tokens", "cache_read_tokens", "total_tokens", "inference_cost_nano_usd", "service_cost_nano_usd", "total_cost_nano_usd" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64" }, "inference_cost_nano_usd": { "type": "integer", "format": "int64" }, "input_tokens": { "type": "integer", "format": "int64" }, "output_tokens": { "type": "integer", "format": "int64" }, "request_count": { "type": "integer", "format": "int64" }, "service_cost_nano_usd": { "type": "integer", "format": "int64" }, "service_usage_count": { "type": "integer", "format": "int64" }, "total_cost_nano_usd": { "type": "integer", "format": "int64" }, "total_cost_usd": { "type": [ "string", "null" ] }, "total_tokens": { "type": "integer", "format": "int64" } } }, "ReportingWorkspaceSummary": { "type": "object", "required": [ "workspace_id", "request_count", "service_usage_count", "total_cost_nano_usd" ], "properties": { "request_count": { "type": "integer", "format": "int64" }, "service_usage_count": { "type": "integer", "format": "int64" }, "total_cost_nano_usd": { "type": "integer", "format": "int64" }, "workspace_id": { "type": "string", "format": "uuid" } } }, "RequestCost": { "type": "object", "description": "Individual request cost", "required": [ "requestId", "costNanoUsd" ], "properties": { "costNanoUsd": { "type": "integer", "format": "int64", "description": "Cost in nano-USD (10^-9 USD)" }, "requestId": { "type": "string", "format": "uuid", "description": "The request ID" } } }, "RerankRequest": { "type": "object", "description": "Request for document reranking", "required": [ "model", "query", "documents" ], "properties": { "documents": { "type": "array", "items": { "type": "string" }, "description": "Documents to rerank" }, "model": { "type": "string", "description": "Model ID to use for reranking" }, "query": { "type": "string", "description": "Query to rerank documents against" }, "return_documents": { "type": [ "boolean", "null" ], "description": "Whether to include document text in each result. Defaults to true." }, "top_n": { "type": [ "integer", "null" ], "description": "Maximum number of ranked results to return", "minimum": 0 } } }, "RerankResponse": { "type": "object", "description": "Response from document reranking", "required": [ "id", "model", "results" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the rerank request" }, "model": { "type": "string", "description": "Model used for reranking" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RerankResult" }, "description": "Reranked results" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RerankUsage", "description": "Usage information (optional)" } ] } } }, "RerankResult": { "type": "object", "description": "Individual reranked result", "required": [ "index", "relevance_score" ], "properties": { "document": { "description": "The document (can be string or object depending on provider)" }, "index": { "type": "integer", "format": "int32", "description": "Index of the document in the original input" }, "relevance_score": { "type": "number", "format": "double", "description": "Relevance score (typically 0.0 to 1.0)" } } }, "RerankUsage": { "type": "object", "description": "Usage information for rerank request", "properties": { "prompt_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Input tokens" }, "total_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Total number of tokens used" } } }, "ResponseContentItem": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "input_text" ] } } }, { "type": "object", "required": [ "image_url", "type" ], "properties": { "detail": { "type": [ "string", "null" ] }, "image_url": { "$ref": "#/components/schemas/ResponseImageUrl" }, "type": { "type": "string", "enum": [ "input_image" ] } } }, { "type": "object", "required": [ "file_id", "type" ], "properties": { "detail": { "type": [ "string", "null" ] }, "file_id": { "type": "string" }, "type": { "type": "string", "enum": [ "input_file" ] } } }, { "type": "object", "required": [ "text", "annotations", "type" ], "properties": { "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/TextAnnotation" } }, "logprobs": { "type": "array", "items": {} }, "text": { "type": "string" }, "type": { "type": "string", "enum": [ "output_text" ] } } }, { "type": "object", "required": [ "tool_calls", "type" ], "properties": { "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseOutputToolCall" } }, "type": { "type": "string", "enum": [ "tool_calls" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageOutputData" }, "description": "Image data array (matches OpenAI format)" }, "type": { "type": "string", "enum": [ "output_image" ] }, "url": { "type": [ "string", "null" ], "description": "Optional URL (future support)" } } } ], "description": "Unified content item that can represent both user inputs and assistant outputs\nThis replaces ResponseOutputContent and correctly represents semantic types" }, "ResponseError": { "type": "object", "required": [ "message", "type" ], "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } } }, "ResponseImageUrl": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } ] }, "ResponseIncompleteDetails": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } }, "ResponseItemStatus": { "type": "string", "enum": [ "completed", "failed", "in_progress", "cancelled" ] }, "ResponseObject": { "type": "object", "description": "Complete response object", "required": [ "id", "object", "created_at", "status", "model", "output", "parallel_tool_calls", "store", "temperature", "tool_choice", "tools", "top_p", "usage" ], "properties": { "background": { "type": "boolean" }, "conversation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConversationResponseReference" } ] }, "created_at": { "type": "integer", "format": "int64" }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseError" } ] }, "id": { "type": "string" }, "incomplete_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseIncompleteDetails" } ] }, "instructions": { "type": [ "string", "null" ] }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int64" }, "max_tool_calls": { "type": [ "integer", "null" ], "format": "int64" }, "metadata": {}, "model": { "type": "string" }, "next_response_ids": { "type": "array", "items": { "type": "string" } }, "object": { "type": "string" }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseOutputItem" } }, "parallel_tool_calls": { "type": "boolean" }, "previous_response_id": { "type": [ "string", "null" ] }, "prompt_cache_key": { "type": [ "string", "null" ] }, "prompt_cache_retention": { "type": [ "string", "null" ] }, "reasoning": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseReasoningOutput" } ] }, "safety_identifier": { "type": [ "string", "null" ] }, "service_tier": { "type": "string" }, "status": { "$ref": "#/components/schemas/ResponseStatus" }, "store": { "type": "boolean" }, "temperature": { "type": "number", "format": "float" }, "tool_choice": { "$ref": "#/components/schemas/ResponseToolChoiceOutput" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ClientManagedResponseTool" } }, "top_logprobs": { "type": "integer", "format": "int32" }, "top_p": { "type": "number", "format": "float" }, "truncation": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" }, "user": { "type": [ "string", "null" ] } } }, "ResponseOutputContent": { "oneOf": [ { "type": "object", "required": [ "text", "annotations", "type" ], "properties": { "annotations": { "type": "array", "items": {} }, "text": { "type": "string" }, "type": { "type": "string", "enum": [ "output_text" ] } } }, { "type": "object", "required": [ "tool_calls", "type" ], "properties": { "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseOutputToolCall" } }, "type": { "type": "string", "enum": [ "tool_calls" ] } } } ], "description": "Output content from assistant (output-only variants).\n\nThis type is used for type-safe operations on assistant outputs only.\nIt cannot contain input variants, providing compile-time safety.\nUsed in streaming events and response output items in the API layer." }, "ResponseOutputFunction": { "type": "object", "required": [ "name", "arguments" ], "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } } }, "ResponseOutputItem": { "oneOf": [ { "type": "object", "required": [ "id", "status", "role", "content", "model", "type" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseContentItem" } }, "created_at": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "metadata": {}, "model": { "type": "string" }, "next_response_ids": { "type": "array", "items": { "type": "string" } }, "previous_response_id": { "type": [ "string", "null" ] }, "response_id": { "type": "string" }, "role": { "type": "string" }, "status": { "$ref": "#/components/schemas/ResponseItemStatus" }, "type": { "type": "string", "enum": [ "message" ] } } }, { "type": "object", "required": [ "id", "status", "tool_type", "function", "model", "type" ], "properties": { "created_at": { "type": "integer", "format": "int64" }, "function": { "$ref": "#/components/schemas/ResponseOutputFunction" }, "id": { "type": "string" }, "model": { "type": "string" }, "next_response_ids": { "type": "array", "items": { "type": "string" } }, "previous_response_id": { "type": [ "string", "null" ] }, "response_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/ResponseItemStatus" }, "tool_type": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_call" ] } } }, { "type": "object", "required": [ "id", "status", "action", "model", "type" ], "properties": { "action": { "$ref": "#/components/schemas/WebSearchAction" }, "created_at": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "model": { "type": "string" }, "next_response_ids": { "type": "array", "items": { "type": "string" } }, "previous_response_id": { "type": [ "string", "null" ] }, "response_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/ResponseItemStatus" }, "type": { "type": "string", "enum": [ "web_search_call" ] } } }, { "type": "object", "required": [ "id", "status", "summary", "content", "model", "type" ], "properties": { "content": { "type": "string" }, "created_at": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "model": { "type": "string" }, "next_response_ids": { "type": "array", "items": { "type": "string" } }, "previous_response_id": { "type": [ "string", "null" ] }, "response_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/ResponseItemStatus" }, "summary": { "type": "string" }, "type": { "type": "string", "enum": [ "reasoning" ] } } }, { "type": "object", "description": "MCP tool list - emitted after connecting to an MCP server.\nClients can include this in subsequent requests to skip tool discovery.", "required": [ "id", "server_label", "tools", "type" ], "properties": { "error": { "type": [ "string", "null" ], "description": "Error message if the server could not list tools" }, "id": { "type": "string" }, "server_label": { "type": "string" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpDiscoveredTool" } }, "type": { "type": "string", "enum": [ "mcp_list_tools" ] } } }, { "type": "object", "description": "MCP tool call - emitted after executing a tool on an MCP server", "required": [ "id", "server_label", "name", "arguments", "model", "type" ], "properties": { "approval_request_id": { "type": [ "string", "null" ] }, "arguments": { "type": "string" }, "created_at": { "type": "integer", "format": "int64" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "model": { "type": "string" }, "name": { "type": "string" }, "next_response_ids": { "type": "array", "items": { "type": "string" } }, "output": { "type": [ "string", "null" ] }, "previous_response_id": { "type": [ "string", "null" ] }, "response_id": { "type": "string" }, "server_label": { "type": "string" }, "status": { "type": [ "string", "null" ], "description": "Status of the tool call: in_progress, completed, incomplete, calling, or failed" }, "type": { "type": "string", "enum": [ "mcp_call" ] } } }, { "type": "object", "description": "MCP approval request - emitted when a tool requires approval", "required": [ "id", "server_label", "name", "arguments", "model", "type" ], "properties": { "arguments": { "type": "string" }, "created_at": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "model": { "type": "string" }, "name": { "type": "string" }, "next_response_ids": { "type": "array", "items": { "type": "string" } }, "previous_response_id": { "type": [ "string", "null" ] }, "response_id": { "type": "string" }, "server_label": { "type": "string" }, "type": { "type": "string", "enum": [ "mcp_approval_request" ] } } }, { "type": "object", "description": "Function call requiring client execution\nEmitted when the LLM calls an external function that must be executed by the client.\nThe client should execute the function and submit a FunctionCallOutput input.", "required": [ "id", "call_id", "name", "arguments", "status", "model", "type" ], "properties": { "arguments": { "type": "string", "description": "JSON-encoded arguments" }, "call_id": { "type": "string", "description": "The LLM's tool_call_id for correlation with FunctionCallOutput" }, "created_at": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "model": { "type": "string" }, "name": { "type": "string", "description": "Function name" }, "next_response_ids": { "type": "array", "items": { "type": "string" } }, "previous_response_id": { "type": [ "string", "null" ] }, "response_id": { "type": "string" }, "status": { "type": "string", "description": "Status: \"in_progress\" when pending client execution" }, "thought_signature": { "type": [ "string", "null" ], "description": "Provider-specific metadata that clients must echo unchanged when\nreplaying the function call (for example Gemini's thought signature)." }, "type": { "type": "string", "enum": [ "function_call" ] } } }, { "type": "object", "description": "Result of a client-executed function call.\nStored when the client submits a FunctionCallOutput input item.", "required": [ "id", "call_id", "output", "type" ], "properties": { "call_id": { "type": "string", "description": "The call_id from the FunctionCall this is a response to" }, "created_at": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "next_response_ids": { "type": "array", "items": { "type": "string" } }, "output": { "type": "string", "description": "Result of the function execution" }, "previous_response_id": { "type": [ "string", "null" ] }, "response_id": { "type": "string" }, "type": { "type": "string", "enum": [ "function_call_output" ] } } } ], "description": "Output item from response" }, "ResponseOutputToolCall": { "type": "object", "required": [ "id", "type", "function" ], "properties": { "function": { "$ref": "#/components/schemas/ResponseOutputFunction" }, "id": { "type": "string" }, "type": { "type": "string" } } }, "ResponseReasoningConfig": { "type": "object", "description": "Reasoning configuration", "properties": { "effort": { "type": [ "string", "null" ] } } }, "ResponseReasoningOutput": { "type": "object", "properties": { "effort": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] } } }, "ResponseStatus": { "type": "string", "enum": [ "completed", "failed", "in_progress", "cancelled", "queued", "incomplete" ] }, "ResponseTextConfig": { "type": "object", "description": "Text format configuration", "required": [ "format" ], "properties": { "format": { "$ref": "#/components/schemas/ResponseTextFormat" } } }, "ResponseTextFormat": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "json_object" ] } } }, { "type": "object", "required": [ "json_schema", "type" ], "properties": { "json_schema": {}, "type": { "type": "string", "enum": [ "json_schema" ] } } } ] }, "ResponseTool": { "oneOf": [ { "type": "object", "required": [ "name", "type" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "parameters": {}, "type": { "type": "string", "enum": [ "function" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_context_search" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file_search" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "code_interpreter" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "computer" ] } } }, { "type": "object", "required": [ "server_label", "server_url", "type" ], "properties": { "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" } }, "authorization": { "type": [ "string", "null" ] }, "require_approval": { "$ref": "#/components/schemas/McpApprovalRequirement" }, "server_description": { "type": [ "string", "null" ] }, "server_label": { "type": "string" }, "server_url": { "type": "string" }, "type": { "type": "string", "enum": [ "mcp" ] } } } ], "description": "Tool configuration for responses" }, "ResponseToolChoice": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "type", "function" ], "properties": { "function": { "$ref": "#/components/schemas/ResponseToolChoiceFunction" }, "type": { "type": "string" } } } ], "description": "Tool choice configuration" }, "ResponseToolChoiceFunction": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "ResponseToolChoiceOutput": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "type", "function" ], "properties": { "function": { "$ref": "#/components/schemas/ResponseToolChoiceFunction" }, "type": { "type": "string" } } } ] }, "ScheduledPricingChangeDto": { "type": "object", "required": [ "id", "batchId", "modelId", "modelDisplayName", "status", "effectiveAt", "oldPricing", "newPricing", "createdAt" ], "properties": { "appliedAt": { "type": [ "string", "null" ] }, "batchId": { "type": "string" }, "changeReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "createdByUserEmail": { "type": [ "string", "null" ] }, "effectiveAt": { "type": "string" }, "id": { "type": "string" }, "lastError": { "type": [ "string", "null" ] }, "modelDisplayName": { "type": "string" }, "modelId": { "type": "string" }, "newPricing": { "$ref": "#/components/schemas/PricingFieldUpdates" }, "oldPricing": { "$ref": "#/components/schemas/PricingFields" }, "status": { "type": "string", "description": "One of: pending, applying, applied, cancelled, failed." } } }, "ScoreRequest": { "type": "object", "description": "Request for text similarity scoring", "required": [ "model", "text_1", "text_2" ], "properties": { "model": { "type": "string", "description": "Model ID to use for scoring" }, "text_1": { "type": "string", "description": "First text to compare" }, "text_2": { "type": "string", "description": "Second text to compare" } } }, "ScoreResponse": { "type": "object", "description": "Response from text similarity scoring", "required": [ "id", "object", "created", "model", "data" ], "properties": { "created": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the score was created" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreResult" }, "description": "Score results" }, "id": { "type": "string", "description": "Unique identifier for the score request" }, "model": { "type": "string", "description": "Model used for scoring" }, "object": { "type": "string", "description": "Object type" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScoreUsage", "description": "Token usage information" } ] } } }, "ScoreResult": { "type": "object", "description": "Individual score result", "required": [ "index", "score", "object" ], "properties": { "index": { "type": "integer", "format": "int32", "description": "Index of the result (always 0 for single score)" }, "object": { "type": "string", "description": "Type of result" }, "score": { "type": "number", "format": "double", "description": "The similarity score between 0.0 and 1.0" } } }, "ScoreUsage": { "type": "object", "description": "Token usage for score response", "properties": { "completion_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of completion tokens" }, "prompt_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of tokens in the prompt" }, "prompt_tokens_details": { "description": "Prompt tokens details" }, "total_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Total number of tokens" } } }, "ServiceListResponse": { "type": "object", "description": "Response for public service list endpoint", "required": [ "services", "limit", "offset", "total" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "ServiceResponse": { "type": "object", "description": "Platform service (public) — single item.\n\nStructurally identical to `AdminServiceResponse` today, but kept separate so that\nadmin vs public representations can evolve independently without breaking clients.", "required": [ "id", "serviceName", "displayName", "unit", "costPerUnit", "isActive", "createdAt", "updatedAt" ], "properties": { "costPerUnit": { "type": "integer", "format": "int64", "description": "Price per unit in nano-USD (scale 9)." }, "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "isActive": { "type": "boolean" }, "serviceName": { "type": "string" }, "unit": { "$ref": "#/components/schemas/ServiceUnit" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ServiceUnit": { "type": "string", "description": "Billing unit for platform services.", "enum": [ "request" ] }, "ServiceUsageEntryResponse": { "type": "object", "description": "Service usage history entry (platform services like web_search).\nAll costs use fixed scale of 9 (nano-dollars) and USD currency.", "required": [ "id", "organization_id", "workspace_id", "api_key_id", "service_id", "quantity", "total_cost", "total_cost_display", "created_at" ], "properties": { "api_key_id": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "inference_id": { "type": [ "string", "null" ] }, "organization_id": { "type": "string" }, "quantity": { "type": "integer", "format": "int32" }, "service_id": { "type": "string" }, "total_cost": { "type": "integer", "format": "int64" }, "total_cost_display": { "type": "string" }, "workspace_id": { "type": "string" } } }, "ServiceUsageHistoryResponse": { "type": "object", "description": "Service usage history response", "required": [ "data", "total", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceUsageEntryResponse" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "minimum": 0 } } }, "SignatureResponse": { "type": "object", "description": "Response for signature endpoint", "required": [ "text", "signature", "signing_address", "signing_algo" ], "properties": { "signature": { "type": "string" }, "signature_kind": { "type": [ "string", "null" ], "description": "Which key produced this signature: `\"provider_tee\"` (model-serving TEE)\nor `\"gateway\"` (cloud-api gateway TEE, used when the gateway rewrites\nthe stream bytes — usage accounting/stripping, redaction — and for\nattested fallback providers without per-response signatures). Omitted\nfor signatures stored before the kind was recorded, whose provenance is\nunknown." }, "signing_address": { "type": "string" }, "signing_algo": { "type": "string" }, "text": { "type": "string", "description": "The signed payload. Its format depends on `signature_kind`:\n- `provider_tee`: `\"{model_id}:{request_hash}:{response_hash}\"` —\n signed inside the model-serving TEE over the bytes the model backend\n emitted.\n- `gateway`: `\"{request_hash}:{response_hash}\"` — signed by the\n cloud-api gateway TEE over the exact bytes the client received." } } }, "SpendLimit": { "type": "object", "description": "Spend limit for API responses\n\nThe system uses a fixed scale of 9 (nano-dollars = 1 billionth of a dollar).\nThe scale field is included in responses for client convenience.\n\nExamples:\n $100.00 USD: amount=100000000000, scale=9, currency=\"USD\"\n $0.01 USD: amount=10000000, scale=9, currency=\"USD\"", "required": [ "amount", "scale", "currency" ], "properties": { "amount": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "scale": { "type": "integer", "format": "int64" } } }, "SpendLimitRequest": { "type": "object", "description": "Spend limit for API requests\n\nThe system internally uses a fixed scale of 9 (nano-dollars = 1 billionth of a dollar).\nClients must provide amounts in nano-dollars.\n\nExamples:\n $100.00 USD: amount=100000000000, currency=\"USD\"\n $1.00 USD: amount=1000000000, currency=\"USD\"\n $0.01 USD: amount=10000000, currency=\"USD\"", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "integer", "format": "int64", "description": "Amount in nano-dollars (scale 9). For example, $1.00 = 1000000000 nano-dollars." }, "currency": { "type": "string" } } }, "StakingFarmConfigResponse": { "type": "object", "required": [ "enabled", "network_id", "contract_id", "farm_product_id", "credit_nano_usd_per_reward_unit", "sync_staleness_seconds" ], "properties": { "contract_id": { "type": "string" }, "credit_nano_usd_per_reward_unit": { "type": "integer", "format": "int64" }, "enabled": { "type": "boolean" }, "farm_price_id": { "type": [ "string", "null" ] }, "farm_product_id": { "type": "string" }, "network_id": { "type": "string" }, "sync_staleness_seconds": { "type": "integer", "format": "int64" } } }, "StakingFarmStateResponse": { "type": "object", "required": [ "organization_id", "near_account_id", "network_id", "contract_id", "farm_product_id", "credit_nano_usd_per_reward_unit", "sync_status", "active_positions" ], "properties": { "accumulated_reward_units_24": { "type": [ "string", "null" ] }, "active_positions": {}, "contract_id": { "type": "string" }, "credit_nano_usd_per_reward_unit": { "type": "integer", "format": "int64" }, "farm_credit_nano_usd": { "type": [ "integer", "null" ], "format": "int64" }, "farm_price_id": { "type": [ "string", "null" ] }, "farm_product_id": { "type": "string" }, "last_sync_error": { "type": [ "string", "null" ] }, "last_synced_at": { "type": [ "string", "null" ] }, "last_synced_credit_nano_usd": { "type": [ "integer", "null" ], "format": "int64" }, "last_synced_reward_units_24": { "type": [ "string", "null" ] }, "near_account_id": { "type": "string" }, "network_id": { "type": "string" }, "organization_id": { "type": "string" }, "pending_reward_units_24": { "type": [ "string", "null" ] }, "sync_status": { "type": "string" }, "total_earned_reward_units_24": { "type": [ "string", "null" ] } } }, "StopSequences": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "OpenAI `stop`: either a single string or an array of strings." }, "SubmitFeatureRequest": { "type": "object", "required": [ "kind", "key" ], "properties": { "key": { "type": "string" }, "kind": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "organizationId": { "type": [ "string", "null" ], "format": "uuid" }, "source": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } } }, "SubmitFeatureRequestResponse": { "type": "object", "required": [ "target", "uniqueUserCount" ], "properties": { "target": { "$ref": "#/components/schemas/FeatureRequestTargetResponse" }, "uniqueUserCount": { "type": "integer", "format": "int64" } } }, "TextAnnotation": { "oneOf": [ { "type": "object", "required": [ "start_index", "end_index", "title", "url", "type" ], "properties": { "end_index": { "type": "integer", "minimum": 0 }, "start_index": { "type": "integer", "minimum": 0 }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "url_citation" ] }, "url": { "type": "string" } } } ], "description": "Annotation for output text (citations, etc.)" }, "ToolCall": { "type": "object", "required": [ "id", "type", "function" ], "properties": { "function": { "$ref": "#/components/schemas/FunctionCall" }, "id": { "type": "string" }, "thought_signature": { "type": [ "string", "null" ], "description": "Gemini-3 thought_signature. The client must echo this verbatim on\nthe next turn or Gemini rejects the request with\n\"Function call is missing a thought_signature\"." }, "type": { "type": "string" } } }, "TopModelMetrics": { "type": "object", "description": "Top model by request count", "required": [ "model_name", "requests", "revenue_usd" ], "properties": { "model_name": { "type": "string" }, "requests": { "type": "integer", "format": "int64" }, "revenue_usd": { "type": "number", "format": "double" } } }, "TopOrganizationMetrics": { "type": "object", "description": "Top organization by spend", "required": [ "organization_id", "organization_name", "requests", "spend_usd" ], "properties": { "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "requests": { "type": "integer", "format": "int64" }, "spend_usd": { "type": "number", "format": "double" } } }, "TopProvider": { "type": "object", "description": "OpenRouter `top_provider` block: context length and max output tokens\nin the field names OpenRouter's `/api/v1/models` schema uses.", "required": [ "is_moderated" ], "properties": { "context_length": { "type": [ "integer", "null" ], "format": "int32", "description": "Context length in tokens (mirrors top-level `context_length`)." }, "is_moderated": { "type": "boolean", "description": "Whether the provider moderates content. We do not, so this is always false." }, "max_completion_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum output tokens per response (mirrors top-level `max_output_length`)." } } }, "TranscriptionSegment": { "type": "object", "description": "Transcription segment with optional metadata fields\nMatches the inference_providers version to ensure consistency with actual provider responses", "required": [ "id", "seek", "start", "end", "text", "tokens", "temperature" ], "properties": { "avg_logprob": { "type": [ "number", "null" ], "format": "double", "description": "Optional: may be null in some provider responses" }, "compression_ratio": { "type": [ "number", "null" ], "format": "double", "description": "Optional: may be null in some provider responses" }, "end": { "type": "number", "format": "double" }, "id": { "type": "integer", "format": "int32" }, "no_speech_prob": { "type": [ "number", "null" ], "format": "double", "description": "Optional: may be null in some provider responses" }, "seek": { "type": "integer", "format": "int32" }, "start": { "type": "number", "format": "double" }, "temperature": { "type": "number", "format": "double" }, "text": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "integer", "format": "int32" } } } }, "TranscriptionWord": { "type": "object", "description": "Word-level timing information", "required": [ "word", "start", "end" ], "properties": { "end": { "type": "number", "format": "double" }, "start": { "type": "number", "format": "double" }, "word": { "type": "string" } } }, "UpdateApiKeyRequest": { "type": "object", "description": "Request to update API key (general update for name, expires_at, and/or spend_limit)", "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_active": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "spendLimit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] } } }, "UpdateApiKeySpendLimitRequest": { "type": "object", "description": "Request to update API key spend limit", "properties": { "spendLimit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] } } }, "UpdateModelApiRequest": { "type": "object", "description": "Request to update model pricing (admin endpoint)", "properties": { "aliases": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowFree": { "type": [ "boolean", "null" ], "description": "If true, this model may be activated even when both cost fields are 0.\nRequired to be set explicitly when activating a zero-price model." }, "attestationSupported": { "type": [ "boolean", "null" ], "description": "Whether this model supports TEE attestation" }, "cacheReadCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest", "description": "Cost per cached input token.\n\nTri-state PATCH semantics:\n- omitted → leave unchanged\n- `null` → disable cache pricing (cached tokens billed at the full\n input rate; `cacheReadCostPerToken` / `input_cache_read` omitted from\n catalog responses)\n- a price → set verbatim (an amount of 0 = genuinely free cache reads)" } ] }, "changeReason": { "type": [ "string", "null" ] }, "contextLength": { "type": [ "integer", "null" ], "format": "int32" }, "costPerImage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] }, "datacenters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Datacenter" }, "description": "Datacenters the model runs in (OpenRouter `datacenters`), as\n`[{ \"country_code\": \"US\" }]`. Country codes must be 2-letter\nuppercase ISO 3166 Alpha-2." }, "deprecationDate": { "type": [ "string", "null" ], "description": "OpenRouter `deprecation_date`: ISO 8601 string (`YYYY-MM-DD` or\n`YYYY-MM-DDTHH:00:00Z`). Validated at the write path; rejected if it\ndoes not parse.\n\nTri-state PATCH semantics:\n- omitted → leave unchanged\n- `null` → clear back to \"no planned deprecation\" (column set to NULL)\n- a string → set to the normalized deprecation timestamp" }, "huggingFaceId": { "type": [ "string", "null" ], "description": "HuggingFace identifier (required by OpenRouter when the model is on HF)." }, "inferenceUrl": { "type": [ "string", "null" ], "description": "Base URL for the model's inference endpoint" }, "inputCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] }, "inputModalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Input modalities the model accepts, e.g., [\"text\"], [\"text\", \"image\"]" }, "isActive": { "type": [ "boolean", "null" ] }, "isReady": { "type": [ "boolean", "null" ], "description": "OpenRouter `is_ready`. Stored and exposed verbatim on `GET /v1/models`.\n\nTri-state PATCH semantics:\n- omitted → leave unchanged\n- `null` → clear back to \"unset\" (column set to NULL)\n- `true`/`false` → set verbatim" }, "maxOutputLength": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of output tokens the model can produce in a single response." }, "modelDescription": { "type": [ "string", "null" ] }, "modelDisplayName": { "type": [ "string", "null" ] }, "modelIcon": { "type": [ "string", "null" ] }, "openrouterSlug": { "type": [ "string", "null" ], "description": "OpenRouter `openrouter.slug` override (lowercase `author/slug`, e.g.\n`z-ai/glm-5.1`). Set when our canonical `model_name` does not match\nOpenRouter's slug; surfaced as the nested `openrouter: { slug }` object\non `GET /v1/models`. Validated at the write path; rejected if it does\nnot match the `author/slug` shape.\n\nTri-state PATCH semantics:\n- omitted → leave unchanged\n- `null` → clear back to \"unset\" (column set to NULL)\n- a string → set verbatim" }, "outputCostPerToken": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecimalPriceRequest" } ] }, "outputModalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Output modalities the model produces, e.g., [\"text\"], [\"image\"]" }, "ownedBy": { "type": [ "string", "null" ] }, "providerConfig": { "description": "JSON config for external providers (backend, base_url, etc.)" }, "providerType": { "type": [ "string", "null" ], "description": "Provider type: \"vllm\" (default, TEE-enabled) or \"external\" (3rd party)" }, "quantization": { "type": [ "string", "null" ], "description": "Quantization label (int4/int8/fp4/fp6/fp8/fp16/bf16/fp32)." }, "supportedFeatures": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Feature capabilities (OpenRouter vocabulary)." }, "supportedSamplingParameters": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Sampling parameters accepted by the model (OpenRouter vocabulary)." }, "verifiable": { "type": [ "boolean", "null" ] } } }, "UpdateOrganizationConcurrentLimitRequest": { "type": "object", "description": "Request to update organization concurrent request limit (Admin only)\n\nThe concurrent limit controls how many requests an organization can have\nin-flight simultaneously per model. Set to null to use the default (64).", "properties": { "concurrentLimit": { "type": [ "integer", "null" ], "format": "int32", "description": "Concurrent request limit per model. Set to null to use default (64).", "minimum": 0 } } }, "UpdateOrganizationConcurrentLimitResponse": { "type": "object", "description": "Response after updating organization concurrent limit", "required": [ "organizationId", "updatedAt" ], "properties": { "concurrentLimit": { "type": [ "integer", "null" ], "format": "int32", "description": "Current concurrent limit. Null means default (64) is used.", "minimum": 0 }, "organizationId": { "type": "string" }, "updatedAt": { "type": "string" } } }, "UpdateOrganizationLimitsRequest": { "type": "object", "description": "Request to update organization limits (Admin only)", "required": [ "type", "spendLimit" ], "properties": { "changeReason": { "type": [ "string", "null" ] }, "changedBy": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "spendLimit": { "$ref": "#/components/schemas/SpendLimitRequest" }, "type": { "$ref": "#/components/schemas/CreditType" } } }, "UpdateOrganizationLimitsResponse": { "type": "object", "description": "Response after updating organization limits", "required": [ "organization_id", "type", "spendLimit", "updated_at" ], "properties": { "organization_id": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "spendLimit": { "$ref": "#/components/schemas/SpendLimit" }, "type": { "$ref": "#/components/schemas/CreditType" }, "updated_at": { "type": "string" } } }, "UpdateOrganizationMemberRequest": { "type": "object", "description": "Request to update an organization member", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/MemberRole" } } }, "UpdateOrganizationRequest": { "type": "object", "description": "Request to update an organization", "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "rate_limit": { "type": [ "integer", "null" ], "format": "int32" }, "settings": {} }, "additionalProperties": false }, "UpdateServiceRequest": { "type": "object", "description": "Request to update a platform service (admin; display_name, description, cost_per_unit, is_active)", "properties": { "costPerUnit": { "type": [ "integer", "null" ], "format": "int64", "description": "Price per unit in nano-USD (scale 9)." }, "description": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "isActive": { "type": [ "boolean", "null" ] } } }, "UpdateUserProfileRequest": { "type": "object", "description": "User profile update request", "properties": { "avatar_url": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] } } }, "UpdateWorkspaceRequest": { "type": "object", "description": "Request to update a workspace", "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "settings": {} } }, "Usage": { "type": "object", "required": [ "input_tokens", "output_tokens", "total_tokens" ], "properties": { "input_tokens": { "type": "integer", "format": "int32" }, "input_tokens_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InputTokensDetails" } ] }, "output_tokens": { "type": "integer", "format": "int32" }, "output_tokens_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputTokensDetails" } ] }, "total_tokens": { "type": "integer", "format": "int32" } } }, "UsageByModelEntryResponse": { "type": "object", "description": "Per-model usage aggregation entry", "required": [ "model", "input_tokens", "output_tokens", "total_tokens", "total_cost", "total_cost_display", "request_count" ], "properties": { "input_tokens": { "type": "integer", "format": "int64" }, "model": { "type": "string" }, "output_tokens": { "type": "integer", "format": "int64" }, "request_count": { "type": "integer", "format": "int64" }, "total_cost": { "type": "integer", "format": "int64" }, "total_cost_display": { "type": "string" }, "total_tokens": { "type": "integer", "format": "int64" } } }, "UsageByModelResponse": { "type": "object", "description": "Per-model usage breakdown response", "required": [ "period", "start_date", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageByModelEntryResponse" } }, "period": { "type": "string" }, "start_date": { "type": "string" } } }, "UsageHistoryEntryResponse": { "type": "object", "description": "Usage history entry\nAll costs use fixed scale of 9 (nano-dollars) and USD currency.\n`cache_read_tokens` is meaningful only for token-based chat-style models; for other\ninference types (e.g., rerank, audio transcription, image), it will typically be 0\nand is not used in billing calculations.", "required": [ "id", "workspace_id", "api_key_id", "model", "input_tokens", "output_tokens", "cache_read_tokens", "total_tokens", "total_cost", "total_cost_display", "inference_type", "created_at" ], "properties": { "api_key_id": { "type": "string" }, "cache_read_tokens": { "type": "integer", "format": "int32", "description": "Number of prompt tokens that were cache hits" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "image_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of images generated (for image generation requests)" }, "inference_id": { "type": [ "string", "null" ], "description": "Inference UUID (hashed from provider_request_id)" }, "inference_type": { "type": "string" }, "input_tokens": { "type": "integer", "format": "int32" }, "model": { "type": "string" }, "output_tokens": { "type": "integer", "format": "int32" }, "provider_request_id": { "type": [ "string", "null" ], "description": "Raw request ID from the inference provider" }, "response_id": { "type": [ "string", "null" ], "description": "Response ID when called from Responses API" }, "stop_reason": { "type": [ "string", "null" ], "description": "Why the inference ended (e.g., \"completed\", \"length\", \"client_disconnect\")" }, "total_cost": { "type": "integer", "format": "int64" }, "total_cost_display": { "type": "string" }, "total_tokens": { "type": "integer", "format": "int32" }, "workspace_id": { "type": "string" } } }, "UsageHistoryResponse": { "type": "object", "description": "Usage history response", "required": [ "data", "total", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageHistoryEntryResponse" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "minimum": 0 } } }, "UserMetricsSummary": { "type": "object", "required": [ "total_requests", "total_input_tokens", "total_output_tokens", "total_cache_read_tokens", "total_cost_usd" ], "properties": { "total_cache_read_tokens": { "type": "integer", "format": "int64" }, "total_cost_usd": { "type": "number", "format": "double" }, "total_input_tokens": { "type": "integer", "format": "int64" }, "total_output_tokens": { "type": "integer", "format": "int64" }, "total_requests": { "type": "integer", "format": "int64" } } }, "UserModelMetrics": { "type": "object", "required": [ "model_name", "requests", "input_tokens", "output_tokens", "cache_read_tokens", "cost_usd" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64" }, "cost_usd": { "type": "number", "format": "double" }, "input_tokens": { "type": "integer", "format": "int64" }, "model_name": { "type": "string" }, "output_tokens": { "type": "integer", "format": "int64" }, "requests": { "type": "integer", "format": "int64" } } }, "UserOrganizationMetrics": { "type": "object", "required": [ "organization_id", "period_start", "period_end", "summary", "by_model", "by_workspace" ], "properties": { "by_model": { "type": "array", "items": { "$ref": "#/components/schemas/UserModelMetrics" } }, "by_workspace": { "type": "array", "items": { "$ref": "#/components/schemas/UserWorkspaceMetrics" } }, "organization_id": { "type": "string" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "summary": { "$ref": "#/components/schemas/UserMetricsSummary" } } }, "UserOrganizationResponse": { "type": "object", "description": "User's organization with role (subset of OrganizationResponse)", "required": [ "id", "name", "role", "is_active", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "role": { "$ref": "#/components/schemas/MemberRole" } } }, "UserResponse": { "type": "object", "description": "User response model (full user profile)", "required": [ "id", "email", "username", "created_at", "updated_at", "is_active", "auth_provider" ], "properties": { "auth_provider": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "display_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "organizations": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UserOrganizationResponse" } }, "updated_at": { "type": "string", "format": "date-time" }, "username": { "type": "string" }, "workspaces": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UserWorkspaceResponse" } } } }, "UserStatusResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, "UserTimeSeriesMetrics": { "type": "object", "required": [ "organization_id", "period_start", "period_end", "granularity", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserTimeSeriesPoint" } }, "granularity": { "type": "string" }, "organization_id": { "type": "string" }, "period_end": { "type": "string" }, "period_start": { "type": "string" } } }, "UserTimeSeriesPoint": { "type": "object", "required": [ "date", "requests", "input_tokens", "output_tokens", "cache_read_tokens", "cost_usd" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64" }, "cost_usd": { "type": "number", "format": "double" }, "date": { "type": "string" }, "input_tokens": { "type": "integer", "format": "int64" }, "output_tokens": { "type": "integer", "format": "int64" }, "requests": { "type": "integer", "format": "int64" } } }, "UserWorkspaceMetrics": { "type": "object", "required": [ "workspace_id", "workspace_name", "requests", "input_tokens", "output_tokens", "cache_read_tokens", "cost_usd" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64" }, "cost_usd": { "type": "number", "format": "double" }, "input_tokens": { "type": "integer", "format": "int64" }, "output_tokens": { "type": "integer", "format": "int64" }, "requests": { "type": "integer", "format": "int64" }, "workspace_id": { "type": "string" }, "workspace_name": { "type": "string" } } }, "UserWorkspaceResponse": { "type": "object", "description": "User's workspace (subset of WorkspaceResponse)", "required": [ "id", "name", "organization_id", "is_active", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "organization_id": { "type": "string" } } }, "VerifyRequest": { "type": "object", "properties": { "request_hash": { "type": [ "string", "null" ] } } }, "VpcInfo": { "type": "object", "description": "VPC information in attestation", "properties": { "vpc_hostname": { "type": [ "string", "null" ], "description": "VPC hostname of this node" }, "vpc_server_app_id": { "type": [ "string", "null" ], "description": "VPC server app ID" } } }, "WebSearchAction": { "oneOf": [ { "type": "object", "required": [ "query", "type" ], "properties": { "query": { "type": "string" }, "type": { "type": "string", "enum": [ "search" ] } } } ], "description": "Web search action details" }, "WorkspaceResponse": { "type": "object", "description": "Workspace response model", "required": [ "id", "name", "organization_id", "created_by_user_id", "created_at", "updated_at", "is_active" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "organization_id": { "type": "string" }, "settings": {}, "updated_at": { "type": "string", "format": "date-time" } } }, "ClientManagedResponseTool": { "oneOf": [ { "type": "object", "required": [ "name", "type" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "parameters": {}, "type": { "type": "string", "enum": [ "function" ] } } } ], "description": "The only tool shape accepted from a public Responses request.\n\n`ResponseTool` retains legacy variants for dormant/internal code paths, but\nthe `CreateResponseRequest::tools` deserializer first parses this enum. That\nmakes unsupported builtin types ordinary request-deserialization failures,\nbefore the route or a provider can do any work." }, "StatelessResponseInputItemSchema": { "oneOf": [ { "type": "object", "required": [ "type", "call_id", "name", "arguments" ], "properties": { "arguments": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "thought_signature": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/FunctionCallType" } } }, { "type": "object", "required": [ "type", "call_id", "output" ], "properties": { "call_id": { "type": "string" }, "output": { "type": "string" }, "type": { "$ref": "#/components/schemas/FunctionCallOutputType" } } }, { "type": "object", "required": [ "role", "content" ], "properties": { "content": { "$ref": "#/components/schemas/StatelessResponseContentSchema" }, "metadata": {}, "role": { "type": "string" } } } ] }, "StatelessResponseContentSchema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/StatelessResponseContentPartSchema" } } ] }, "StatelessResponseInputSchema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/StatelessResponseInputItemSchema" } } ] }, "FunctionCallType": { "type": "string", "description": "Type marker for a client-replayed function call input item.", "enum": [ "function_call" ] }, "StatelessResponseToolSchema": { "oneOf": [ { "type": "object", "required": [ "name", "type" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "parameters": {}, "type": { "type": "string", "enum": [ "function" ] } } } ] }, "StatelessResponseContentPartSchema": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "input_text" ] } } }, { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "output_text" ] } } }, { "type": "object", "required": [ "image_url", "type" ], "properties": { "detail": { "type": [ "string", "null" ] }, "image_url": { "$ref": "#/components/schemas/ResponseImageUrl" }, "type": { "type": "string", "enum": [ "input_image" ] } } } ] }, "StatelessCreateResponseRequestSchema": { "type": "object", "description": "OpenAPI-only view of the stateless Responses request contract.\n\nThe runtime request type keeps legacy variants so it can return a precise\n`invalid_request_error` for them. The public endpoint schema should instead\nshow only the items accepted by the stateless implementation.", "required": [ "model" ], "properties": { "include": { "type": [ "array", "null" ], "items": { "type": "string" } }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StatelessResponseInputSchema" } ] }, "instructions": { "type": [ "string", "null" ] }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int64" }, "max_tool_calls": { "type": [ "integer", "null" ], "format": "int64" }, "metadata": {}, "model": { "type": "string" }, "parallel_tool_calls": { "type": [ "boolean", "null" ] }, "prompt_cache_key": { "type": [ "string", "null" ] }, "reasoning": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseReasoningConfig" } ] }, "safety_identifier": { "type": [ "string", "null" ] }, "service_tier": { "type": [ "string", "null" ] }, "store": { "type": "boolean", "description": "Must be `false` when supplied; omitted is normalized to `false`.", "default": false, "example": false, "const": false }, "stream": { "type": [ "boolean", "null" ] }, "temperature": { "type": [ "number", "null" ], "format": "float" }, "tool_choice": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseToolChoice" } ] }, "tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/StatelessResponseToolSchema" } }, "top_p": { "type": [ "number", "null" ], "format": "float" } } } }, "securitySchemes": { "api_key": { "type": "http", "scheme": "bearer", "bearerFormat": "api_key", "description": "API key for programmatic access (Authorization: Bearer sk-)" }, "refresh_token": { "type": "http", "scheme": "bearer", "bearerFormat": "refresh_token", "description": "Long-lived refresh token from OAuth login (Authorization: Bearer rt_). Use only with POST /users/me/access_tokens." }, "reporting_token": { "type": "http", "scheme": "bearer", "bearerFormat": "reporting_token", "description": "Read-only reporting token for usage reporting endpoints (Authorization: Bearer rpt-)" }, "session_token": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT access token for user authentication (Authorization: Bearer ). Create via POST /users/me/access_tokens." } } }, "security": [ { "session_token": [] }, { "api_key": [] } ], "tags": [ { "name": "Chat", "description": "Chat completion endpoints for AI model inference" }, { "name": "Images", "description": "Image generation endpoints" }, { "name": "Audio", "description": "Audio transcription endpoints" }, { "name": "Rerank", "description": "Document reranking endpoints" }, { "name": "Score", "description": "Text similarity scoring endpoints" }, { "name": "Privacy", "description": "Privacy classification (PII span detection) endpoints" }, { "name": "Models", "description": "Public model catalog and information" }, { "name": "Responses", "description": "Stateless response inference (`store: false` only). Raw request/response content, response items, and history are not persisted. Clients must include any prior context in each request. Every successful Responses inference makes exactly one Chat Completions call. Only custom `function` tools are supported. They are client-managed: Cloud returns `function_call` items but never executes them; a later `store: false` request replays the individual call (the raw item from output is accepted) with its matching `function_call_output`, alongside caller-managed message history and the same function tool definitions. The minimal replay path also accepts assistant `message` text parts of type `output_text`, but not reasoning or arbitrary full `response.output` items. Server-executed tools (`web_search`, `web_context_search`, `file_search`, `code_interpreter`, `computer`, and remote `mcp`) and image-generation/editing models are rejected. The separate `POST /mcp` endpoint continues to expose its `web_search` tool independently of Responses; use `/v1/images/*` for image generation/editing. Existing completed-response gateway attestation is preserved best-effort: when the signature write succeeds, `GET /v1/signature/resp_*` retrieves signatures over SHA-256 request/response digests, never raw content. Interrupted streams create no `resp_*` attestation record or legacy disconnect fallback. Conversations, response history, and file input are rejected." }, { "name": "Organizations", "description": "Organization management" }, { "name": "Organization Members", "description": "Organization member and invitation management" }, { "name": "Workspaces", "description": "Workspace and API key management" }, { "name": "Users", "description": "User profile and token management" }, { "name": "Invitations", "description": "Token-based invitation handling" }, { "name": "Usage", "description": "Usage tracking and billing information" }, { "name": "Reporting", "description": "Read-only customer usage reporting" }, { "name": "Billing", "description": "Billing costs endpoint (HuggingFace integration)" }, { "name": "Staking Farm", "description": "House of Stake farm credit configuration and synchronization" }, { "name": "Health", "description": "Health check endpoints" }, { "name": "Attestation", "description": "Attestation and verification endpoints" }, { "name": "Gateway", "description": "Model gateway integration endpoints" }, { "name": "Admin", "description": "Administrative endpoints (admin access required)" }, { "name": "Services", "description": "Public platform services (e.g. web_search pricing)" } ], "servers": [ { "url": "https://cloud-api.near.ai", "description": "NEAR AI Cloud" } ] }