{ "openapi": "3.1.0", "info": { "title": "Prem API", "description": "Reference documentation for the Prem API.", "version": "1.0.0", "termsOfService": "https://prem.io/terms", "contact": { "name": "API Support", "url": "https://help.prem.io", "email": "support@premai.io" } }, "externalDocs": { "description": "Full Prem API documentation", "url": "https://docs.prem.io" }, "servers": [ { "url": "https://gateway.prem.io", "description": "Production API server" } ], "paths": { "/developers/api_keys": { "post": { "summary": "Create a new API key", "description": "Create a new API key for the organization", "operationId": "createApiKey", "tags": [ "API Keys" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/createDeveloperApiKeyRequest" }, "responses": { "200": { "$ref": "#/components/responses/createDeveloperApiKeyResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "get": { "summary": "List API keys", "description": "List all API keys for the organization", "operationId": "listApiKeys", "tags": [ "API Keys", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/listDeveloperApiKeyResponse" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/developers/api_keys/me": { "get": { "summary": "Get current API key", "description": "Returns the validity and scopes of the API key used to authenticate the request", "operationId": "getMeApiKey", "tags": [ "API Keys", "dev-api" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/meDeveloperApiKeyResponse" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/developers/api_keys/{id}": { "get": { "summary": "Get an API key", "description": "Get details of a specific API key by ID", "operationId": "getApiKey", "tags": [ "API Keys", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API Key ID", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/viewDeveloperApiKeyResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "put": { "summary": "Update an API key", "description": "Update a specific API key by ID", "operationId": "updateApiKey", "tags": [ "API Keys" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API Key ID", "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/updateDeveloperApiKeyRequest" }, "responses": { "200": { "$ref": "#/components/responses/updateDeveloperApiKeyResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "delete": { "summary": "Delete an API key", "description": "Delete a specific API key by ID", "operationId": "deleteApiKey", "tags": [ "API Keys" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API Key ID", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/deleteDeveloperApiKeyResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/analytics/api_keys": { "get": { "summary": "Get API key analytics", "description": "Get analytics data for API key usage", "operationId": "getApiKeyAnalytics", "tags": [ "API Keys", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "name": "api_key_id", "in": "query", "description": "Scope every metric to one or more API keys. Repeat the parameter for several. Omitted = the whole organization.", "required": false, "style": "form", "explode": true, "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 25 } ] } }, { "name": "timezone", "in": "query", "description": "IANA zone name used to group day-grain buckets into calendar days, e.g. Europe/Rome. Shorter buckets are absolute time and are unaffected. Defaults to UTC, and falls back to UTC for an unknown zone.", "required": false, "schema": { "type": "string", "default": "UTC" } }, { "name": "period", "in": "query", "description": "Predefined analytics window. Defaults to last_30_days.", "required": false, "schema": { "type": "string", "enum": [ "last_hour", "last_2_hours", "last_6_hours", "last_12_hours", "last_day", "last_week", "last_30_days" ], "default": "last_30_days" } } ], "responses": { "200": { "$ref": "#/components/responses/apiKeyAnalyticsResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } } }, "/developers/api_keys/scopes": { "get": { "summary": "List API key scopes", "description": "List all available scopes for API keys", "operationId": "listApiKeyScopes", "tags": [ "API Keys", "dev-api" ], "security": [], "responses": { "200": { "$ref": "#/components/responses/listApiKeyScopesResponse" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/developers/api_keys/requests": { "post": { "summary": "List API key requests", "description": "Get a filtered list of API key requests/usage logs", "operationId": "listApiKeyRequests", "tags": [ "API Keys Requests", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/listDeveloperApiKeyRequestsRequest" }, "responses": { "200": { "$ref": "#/components/responses/listDeveloperApiKeyRequestsResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/developers/api_keys/requests/{id}": { "get": { "summary": "Get API key request", "description": "Get details of a specific API key request/usage log entry by ID", "operationId": "getApiKeyRequest", "tags": [ "API Keys Requests", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API Key Request ID", "schema": { "type": "integer" } } ], "responses": { "200": { "$ref": "#/components/responses/viewDeveloperApiKeyRequestResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/files/encrypted/upload": { "post": { "summary": "Upload an encrypted file", "description": "Upload a new encrypted file to the organization's secure file storage with client-side encryption", "operationId": "uploadFileEncrypted", "tags": [ "Files Encrypted", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/uploadFileEncryptedRequest" }, "responses": { "200": { "$ref": "#/components/responses/uploadFileEncryptedResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/files/encrypted": { "get": { "summary": "List encrypted files", "description": "Retrieve a paginated list of encrypted files for the authenticated organization and user", "operationId": "listFilesEncrypted", "tags": [ "Files Encrypted", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of files to return", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Number of files to skip for pagination", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "search", "in": "query", "description": "Search term to filter files by name", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter files by type", "required": false, "schema": { "type": "string", "enum": [ "image", "document", "video", "audio", "archive", "general" ] } }, { "name": "from", "in": "query", "description": "Minimum date to filter files", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Maximum date to filter files", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/listFilesEncryptedResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/files/encrypted/{id}": { "get": { "summary": "Get encrypted file details", "description": "Retrieve detailed information about a specific encrypted file by ID, optionally with a signed download URL. Supports shared chat file access without authentication.", "operationId": "getFileEncrypted", "tags": [ "Files Encrypted", "dev-api" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, {} ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Encrypted file ID", "schema": { "type": "string" } }, { "name": "url", "in": "query", "required": false, "description": "Include signed download URL in response", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } ], "responses": { "200": { "$ref": "#/components/responses/viewFileEncryptedResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "delete": { "summary": "Delete encrypted file", "description": "Permanently delete a specific encrypted file by ID", "operationId": "deleteFileEncrypted", "tags": [ "Files Encrypted", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Encrypted file ID", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/deleteFileEncryptedResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/files/encrypted/index": { "post": { "summary": "Index encrypted files", "description": "Index encrypted files so their content can be retrieved during chat.", "operationId": "indexFileEncrypted", "tags": [ "Files Encrypted", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/indexFileEncryptedRequest" }, "responses": { "200": { "$ref": "#/components/responses/indexFileEncryptedResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/files/encrypted/index-result": { "post": { "summary": "Report file indexing result", "description": "The Prem API Enclave sends file index results to this callback on the public Prem API Gateway. The callback updates the file's RAG status. The gateway checks the `X-Enclave-Secret` header before it accepts a result. To begin a file index job, use `POST /files/encrypted/index`. To read the file status, use `GET /files/encrypted/{id}`.", "operationId": "indexResultFileEncrypted", "tags": [ "Files Encrypted" ], "security": [ { "EnclaveCallbackAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/indexResultFileEncryptedRequest" }, "responses": { "200": { "$ref": "#/components/responses/indexResultFileEncryptedResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "description": "The callback secret is missing or invalid.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400, 401, 403, 404, 405, 409, 429, 500, 502, 503 ], "description": "Status code of the response" }, "data": { "type": [ "object", "null" ], "description": "Response data containing the requested object" }, "error": { "type": [ "string", "null" ], "examples": [ "Some error message" ], "description": "Error message of the response, human readable" }, "message": { "type": "null" }, "env": { "type": "string", "enum": [ "development", "production" ], "description": "API environment" }, "log": { "type": [ "string", "object", "null" ], "examples": [ { "request_id": "req_1234567890" }, "Some pertinent log message" ], "description": "Useful informaiton, not always present, to debug the response" }, "validator": { "type": [ "object", "array", "null" ], "examples": [ { "email": "Invalid email address", "password": "Password is required" } ], "description": "Validator response object, each key is the field name and value is the error message" }, "support_id": { "type": [ "string", "null" ], "format": "uuid", "examples": [ "req_support_01923f4e-7b2a-7c3d-9e8f-0a1b2c3d4e5f" ], "description": "Support ID linked to the response, used to identify it when talking with our team." } }, "required": [ "status", "error", "message", "env", "log", "support_id" ], "additionalProperties": false }, { "properties": { "status": { "type": "integer", "enum": [ 401 ] } } } ] } } } }, "404": { "$ref": "#/components/responses/404" } } } }, "/files/encrypted/delete-index": { "post": { "summary": "Delete index of encrypted files", "description": "Remove encrypted files from the retrieval index. The files themselves are kept.", "operationId": "deleteIndexFileEncrypted", "tags": [ "Files Encrypted", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/deleteIndexFileEncryptedRequest" }, "responses": { "200": { "$ref": "#/components/responses/deleteIndexFileEncryptedResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/rvenc/chat/completions": { "post": { "summary": "Encrypted Chat Completions (RVENC)", "description": "Create a chat completion from an end-to-end encrypted payload, decrypted only inside the confidential compute environment. Stateless: no chat history is kept and no files can be attached.", "operationId": "createRvencChatCompletion", "tags": [ "Chats", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/X-Queue-Timeout" } ], "requestBody": { "$ref": "#/components/requestBodies/createRvencChatCompletionRequest" }, "responses": { "200": { "$ref": "#/components/responses/createRvencChatCompletionResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "description": "Too many requests - concurrent stream limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "examples": [ 429 ] }, "error": { "type": "string", "examples": [ "You already have an active chat stream. Please wait for it to complete or try again in a few moments." ] } } } } } }, "502": { "description": "The confidential inference service failed to complete the request. `error` carries the reason reported by the model server whenever it returned one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "examples": [ 502 ] }, "error": { "type": "string", "examples": [ "The inference service failed to complete the request. Please try again." ] } } } } } } } } }, "/rvenc/models": { "get": { "summary": "List available models for confidential inference", "description": "Get a list of models available for confidential (rvenc) inference", "operationId": "listRvencModels", "tags": [ "Models" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "description": "Filter models by type", "required": false, "schema": { "type": "string", "enum": [ "CHAT", "DECISIONS", "AUDIO_TRANSCRIPTION", "AUDIO_SPEECH", "IMAGE" ] } } ], "responses": { "200": { "$ref": "#/components/responses/rvencModelsListResponse" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/openai/chat/completions": { "post": { "summary": "Create chat completion (OpenAI-compatible)", "description": "Create a chat completion. Compatible with the OpenAI Chat Completions API. Not end-to-end encrypted \u2014 use `/rvenc/chat/completions` for that.", "operationId": "createOpenAiChatCompletion", "tags": [ "Inference", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/X-Queue-Timeout" } ], "requestBody": { "$ref": "#/components/requestBodies/createOpenAiChatCompletionRequest" }, "responses": { "200": { "description": "A chat completion, or a server-sent events stream when `stream` is true.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "502": { "$ref": "#/components/responses/502" }, "503": { "$ref": "#/components/responses/503" } } } }, "/openai/models": { "get": { "summary": "List available models for standard inference", "description": "Get a list of models available for standard (OpenAI-compatible) inference", "operationId": "listOpenAiModels", "tags": [ "Models" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "description": "Filter models by type", "required": false, "schema": { "type": "string", "enum": [ "CHAT", "DECISIONS", "AUDIO_TRANSCRIPTION", "AUDIO_SPEECH", "IMAGE" ] } } ], "responses": { "200": { "$ref": "#/components/responses/openAiModelsListResponse" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/typesafe/v1/systemone": { "post": { "summary": "Create a structured decision", "description": "Answer typed questions (choice, noul, score) about a state. TypeSafe-compatible (SystemOne), so the official SDK can use this endpoint directly. Not end-to-end encrypted.", "operationId": "createSystemOneDecision", "tags": [ "Inference", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/X-Queue-Timeout" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "SystemOne decision request.", "properties": { "model": { "type": "string", "description": "Model name, as listed by `GET /typesafe/v1/models`." }, "state": { "type": [ "string", "object", "array", "number", "boolean", "null" ], "description": "Context the questions are asked about." }, "questions": { "type": "object", "description": "Map of question id to a typed question.", "additionalProperties": { "type": "object" } }, "images": { "type": "array", "description": "Optional. At most one base64 image data URL.", "items": { "type": "string" } }, "samples": { "type": "integer" }, "steps": { "type": "integer" }, "provider": { "type": "string", "description": "Optional. Pin the request to one of the model's configured backends. Omit to let the platform choose." }, "videos": { "type": "array", "maxItems": 1, "description": "Optional dgemma extension: one inline MP4, up to 10 MiB, 30 seconds and 1920 x 1080 pixels. Four frames are sampled; audio is not processed. Cannot be combined with images. Use a raw JSON request if your SDK does not expose this field.", "items": { "type": "string", "pattern": "^data:video/mp4;base64,", "example": "data:video/mp4;base64," } } }, "required": [ "model", "state", "questions" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "A decision with per-question answers and probabilities.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "502": { "$ref": "#/components/responses/502" }, "503": { "$ref": "#/components/responses/503" } } } }, "/typesafe/v1/models": { "get": { "summary": "List TypeSafe-compatible models", "description": "List available decision models and their release dates. Use a returned model name in `POST /typesafe/v1/systemone`.", "operationId": "listTypesafeModels", "tags": [ "Models" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Models available for SystemOne decisions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "type": "object", "required": [ "name", "description", "release_date" ], "properties": { "name": { "type": "string", "description": "Model name or alias accepted by the request's model field." }, "description": { "type": "string", "description": "Human-readable description of the model and its capabilities." }, "release_date": { "type": "string", "format": "date", "description": "Model release date, formatted as YYYY-MM-DD." } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/rvenc/audio/transcriptions": { "post": { "summary": "Encrypted Audio Transcriptions (RVENC)", "description": "Transcribe an end-to-end encrypted audio file into text, in the language spoken in the audio. Nothing is stored: neither the audio nor the transcript.", "operationId": "createRvencAudioTranscription", "tags": [ "Audio", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/X-Queue-Timeout" } ], "requestBody": { "$ref": "#/components/requestBodies/createRvencAudioTranscriptionRequest" }, "responses": { "200": { "$ref": "#/components/responses/createRvencAudioTranscriptionResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "413": { "description": "Request entity too large - audio file exceeds maximum allowed size", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "examples": [ 413 ] }, "error": { "type": "string", "examples": [ "Audio file size exceeds the maximum allowed limit of 25MB." ] } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "examples": [ 429 ] }, "error": { "type": "string", "examples": [ "Rate limit exceeded. Please try again later." ] } } } } } } } } }, "/rvenc/audio/translations": { "post": { "summary": "Encrypted Audio Translations (RVENC)", "description": "Translate an end-to-end encrypted audio file into English text, whatever the input language. Nothing is stored: neither the audio nor the translation.", "operationId": "createRvencAudioTranslation", "tags": [ "Audio", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/X-Queue-Timeout" } ], "requestBody": { "$ref": "#/components/requestBodies/createRvencAudioTranslationRequest" }, "responses": { "200": { "$ref": "#/components/responses/createRvencAudioTranslationResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "413": { "description": "Request entity too large - audio file exceeds maximum allowed size", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "examples": [ 413 ] }, "error": { "type": "string", "examples": [ "Audio file size exceeds the maximum allowed limit of 25MB." ] } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "examples": [ 429 ] }, "error": { "type": "string", "examples": [ "Rate limit exceeded. Please try again later." ] } } } } } } } } }, "/tools": { "get": { "summary": "List available tools", "description": "Get a list of all available tools that can be used by the AI assistant", "operationId": "listTools", "tags": [ "Chats", "dev-api" ], "responses": { "200": { "$ref": "#/components/responses/listToolsResponse" } } } }, "/tools/{id}": { "post": { "summary": "Execute Tool", "description": "Execute a specific tool by passing encrypted parameters.", "operationId": "executeTool", "tags": [ "Chats", "dev-api" ], "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tool identifier (e.g., generateImage, audioGenerateFromText, createFileForUser)", "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/executeToolRequest" }, "responses": { "200": { "$ref": "#/components/responses/executeToolResponse" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/attestation/attest": { "get": { "summary": "Get hardware attestation evidence", "description": "Fetch the standard v2 attestation report for the confidential environment that serves a model. Use Reticle to verify the report before sending protected inference requests.", "operationId": "getAttestation", "tags": [ "Attestation", "dev-api" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, {} ], "parameters": [ { "name": "nonce", "in": "query", "required": true, "description": "Fresh 64-byte nonce encoded as 128 hexadecimal characters.", "schema": { "type": "string", "minLength": 128, "maxLength": 128, "pattern": "^[0-9a-fA-F]{128}$", "example": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" } }, { "name": "model", "in": "query", "required": true, "description": "Confidential model ID to return the report for.", "schema": { "type": "string", "example": "deepseek-v4.1-flash-1017" } } ], "responses": { "200": { "description": "Standard confidential-VM attestation report containing the workload manifest, CPU evidence and optional GPU evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getCvmAttestationResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "429": { "$ref": "#/components/responses/429" }, "502": { "description": "Attestation report temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "examples": [ 502 ] }, "error": { "type": "string", "examples": [ "Attestation report temporarily unavailable." ] } } } } } } } } } }, "components": { "schemas": { "Pagination": { "type": "object", "description": "Pagination information for list responses", "properties": { "total": { "type": "integer", "description": "Total number of items" }, "page": { "type": "integer", "description": "Current page number" }, "limit": { "type": "integer", "description": "Number of items per page" }, "pages": { "type": "integer", "description": "Total number of pages" } }, "required": [ "total", "page", "limit", "pages" ], "additionalProperties": false }, "Response200": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 200, 201, 202 ], "description": "Status code of the response" }, "data": { "type": [ "object", "array", "null" ], "description": "Response data containing the requested object" }, "error": { "type": [ "string", "null" ], "examples": [ "Invalid email address" ], "description": "Error message of the response, human readable" }, "message": { "type": [ "string", "null" ], "examples": [ "Resource created successfully" ], "description": "Message of the response, human readable" }, "env": { "type": "string", "enum": [ "development", "production" ], "description": "API environment" }, "log": { "type": [ "string", "object", "null" ], "examples": [ { "request_id": "req_1234567890" }, "Some pertinent log message" ], "description": "Useful informaiton, not always present, to debug the response" }, "validator": { "type": [ "object", "array", "null" ], "examples": [ { "email": "Invalid email address", "password": "Password is required" } ], "description": "Validator response object, each key is the field name and value is the error message" }, "support_id": { "type": [ "string", "null" ], "format": "uuid", "examples": [ "req_support_01923f4e-7b2a-7c3d-9e8f-0a1b2c3d4e5f" ], "description": "Support ID linked to the response, used to identify it when talking with our team." } }, "required": [ "status", "data", "message", "env" ], "examples": [ { "status": 200, "data": { "id": "123" }, "error": null, "log": null, "validator": null, "support_id": null, "message": "Resource created successfully", "env": "development" } ] }, "apiKeyMetrics": { "type": "object", "properties": { "api_key_id": { "type": "string", "description": "Unique identifier for the webhook" }, "total_requests": { "type": "integer", "description": "Total number of webhook deliveries" }, "last_used_at": { "type": [ "string", "null" ], "format": "mysql-date-time", "examples": [ "2025-06-29 16:03:44" ], "description": "Timestamp when the API key was last used" } }, "additionalProperties": false }, "developersApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the API key" }, "label": { "type": "string", "description": "Human-readable label for the API key", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional description for the API key" }, "scopes": { "type": "array", "description": "List of scopes this API key has access to", "items": { "type": "string" } }, "ip_allow_list": { "type": "array", "description": "List of IP addresses allowed to use this API key", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "mysql-date-time", "examples": [ "2025-06-29 16:03:44" ], "description": "Timestamp when the API key expires" }, "secret": { "type": "string", "description": "Secret key value (only returned when creating a new API key)" }, "created_at": { "type": "string", "format": "mysql-date-time", "examples": [ "2025-06-29 16:03:44" ], "description": "Timestamp when the API key was created" }, "updated_at": { "type": [ "string", "null" ], "format": "mysql-date-time", "examples": [ "2025-06-29 16:03:44" ], "description": "Timestamp when the API key was last updated" }, "source": { "type": [ "string", "null" ], "description": "Integration that owns this key (e.g. \"sotto\"). Null for keys created directly in the dashboard." }, "billing_mode": { "type": "string", "description": "Billing mode for the API key. API usage is charged to the organization balance." }, "metrics": { "oneOf": [ { "$ref": "#/components/schemas/apiKeyMetrics" }, { "type": "null" } ] } }, "required": [ "id", "scopes", "created_at", "updated_at" ], "additionalProperties": false, "examples": [ { "id": "api_key_0197c0f1-9589-7990-b421-4b806f637b0c", "secret": "sk_live_MDFhMTkzNDctNmEyYS03YTMyLTllNTktZWU1MjA3NGY5ZGIxX3BjY2k", "scopes": [ "api_keys.read" ], "ip_allow_list": [ "127.0.0.1" ], "label": "My API Key", "description": "Key for reading API Keys", "expires_at": "2026-05-30 20:23:16", "created_at": "2025-06-30 15:05:47", "updated_at": null, "metrics": { "api_key_id": "api_key_0197c0f1-9589-7990-b421-4b806f637b0c", "total_requests": 150, "last_used_at": "2025-06-30 16:03:44" } } ] }, "developersApiKeyView": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the API key" }, "label": { "type": "string", "description": "Human-readable label for the API key", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Optional description for the API key" }, "scopes": { "type": "array", "description": "List of scopes this API key has access to", "items": { "type": "string" } }, "ip_allow_list": { "type": "array", "description": "List of IP addresses allowed to use this API key", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "mysql-date-time", "examples": [ "2025-06-29 16:03:44" ], "description": "Timestamp when the API key expires" }, "secret": { "type": "string", "description": "Secret key value (only returned when creating a new API key)" }, "created_at": { "type": "string", "format": "mysql-date-time", "examples": [ "2025-06-29 16:03:44" ], "description": "Timestamp when the API key was created" }, "updated_at": { "type": [ "string", "null" ], "format": "mysql-date-time", "examples": [ "2025-06-29 16:03:44" ], "description": "Timestamp when the API key was last updated" }, "source": { "type": [ "string", "null" ], "description": "Integration that owns this key (e.g. \"sotto\"). Null for keys created directly in the dashboard." }, "billing_mode": { "type": "string", "description": "Billing mode for the API key. API usage is charged to the organization balance." }, "metrics": { "oneOf": [ { "$ref": "#/components/schemas/apiKeyMetrics" }, { "type": "null" } ] } }, "required": [ "id", "scopes", "created_at", "updated_at" ], "additionalProperties": false, "examples": [ { "id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "secret": "sk_live_MDE5N2MwZWMt...GdwdA", "scopes": [ "api_keys.read" ], "ip_allow_list": [ "127.0.0.1" ], "label": "My API Key", "description": "Key for reading API Keys", "expires_at": "2026-05-30 20:23:16", "created_at": "2025-06-30 15:05:47", "updated_at": null, "metrics": { "api_key_id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "total_requests": 150, "last_used_at": "2025-06-30 16:03:44" } } ] }, "createDeveloperApiKeyRequest": { "type": "object", "description": "Request body for creating a new API key", "properties": { "label": { "type": "string", "description": "Human-readable label for the API key. Trimmed, and must contain at least one printable character.", "maxLength": 255, "minLength": 1 }, "description": { "type": "string", "description": "Human-readable description for the API key" }, "scopes": { "type": "array", "description": "List of scopes this API key has access to", "items": { "type": "string" } }, "ip_allow_list": { "type": "array", "description": "List of IP addresses allowed to use this API key", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "mysql-date-time", "examples": [ "2025-06-29 16:03:44" ], "description": "Timestamp when the API key expires" } }, "required": [ "label", "scopes" ], "additionalProperties": false, "examples": [ { "label": "Development API Key", "description": "Key for development environment", "scopes": [ "api_keys.read" ], "ip_allow_list": [ "192.168.1.1", "10.0.0.1" ], "expires_at": "2025-12-31 23:59:59" } ] }, "createDeveloperApiKeyResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/developersApiKey" } }, "required": [ "data" ], "examples": [ { "data": { "id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "secret": "sk_live_MDFhMTkzNDctNmEyYS03YTMyLTllNTktZWU1MjA3NGY5ZGIxX3BjY2k", "scopes": [ "api_keys.read" ], "ip_allow_list": [ "127.0.0.1" ], "label": "Development API Key", "description": "Key for development environment", "expires_at": "2026-05-30 20:23:16", "created_at": "2025-06-30 15:00:22", "updated_at": null }, "message": null } ] }, "listDeveloperApiKeyResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/developersApiKey" } } }, "required": [ "data" ], "examples": [ { "data": [ { "id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "secret": "sk_live_MDE5N2MwZWMt...GdwdA", "scopes": [ "api_keys.read" ], "ip_allow_list": [ "127.0.0.1" ], "label": "Development API Key", "description": "Key for development environment", "expires_at": "2026-05-30 20:23:16", "created_at": "2025-06-30 15:00:22", "updated_at": null }, { "id": "api_key_0197c0ef-6750-7e93-be70-32cef133b06a", "secret": "sk_live_MDE5N2MwZWYt...GdwdA", "scopes": [ "api_keys.read" ], "ip_allow_list": [ "127.0.0.1" ], "label": "My API Key", "description": "Key for reading API Keys", "expires_at": "2026-05-30 20:23:16", "created_at": "2025-06-30 15:03:24", "updated_at": null }, { "id": "api_key_0197c0f1-71ca-7fac-bece-9723783fb48b", "secret": "sk_live_MDE5N2MwZjEt...GdwdA", "scopes": [ "api_keys.read" ], "ip_allow_list": [ "127.0.0.1" ], "label": "My API Key 2", "description": "Key for reading API Keys", "expires_at": "2026-05-30 20:23:16", "created_at": "2025-06-30 15:05:38", "updated_at": null } ], "message": null } ] }, "meDeveloperApiKeyResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the API key" }, "description": { "type": [ "string", "null" ], "description": "Optional description for the API key" }, "scopes": { "type": "array", "description": "List of scopes this API key has access to", "items": { "type": "string" } }, "ip_allow_list": { "type": "array", "description": "List of IP addresses allowed to use this API key", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "mysql-date-time", "description": "Timestamp when the API key expires" }, "valid": { "type": "boolean", "description": "Whether the API key is valid" }, "billing_mode": { "type": "string", "description": "Billing mode for the API key. API usage is charged to the organization balance." } }, "required": [ "id", "scopes", "ip_allow_list", "valid" ] } }, "required": [ "data" ], "examples": [ { "data": { "id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "description": "Key for development environment", "scopes": [ "chats.completion", "api_keys.read" ], "ip_allow_list": [], "expires_at": "2026-05-30 20:23:16", "valid": true }, "message": null } ] }, "viewDeveloperApiKeyResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/developersApiKeyView" } }, "required": [ "data" ], "examples": [ { "data": { "id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "secret": "sk_live_MDE5N2MwZWMt...GdwdA", "scopes": [ "api_keys.read" ], "ip_allow_list": [ "127.0.0.1", "192.168.1.0/24" ], "label": "My API Key", "description": "Key for reading API Keys", "expires_at": "2026-05-30 20:23:16", "created_at": "2025-06-30 15:00:22", "updated_at": "2025-07-01 10:30:45", "metrics": { "api_key_id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "total_requests": 1250, "last_used_at": "2025-07-01 09:15:30" } }, "message": null } ] }, "updateDeveloperApiKeyRequest": { "type": "object", "description": "Request body for updating an API key", "properties": { "description": { "type": "string", "description": "Human-readable description for the API key" } }, "required": [ "description" ], "additionalProperties": false, "examples": [ { "description": "Key for production environment" } ] }, "updateDeveloperApiKeyResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "required": [ "message" ], "examples": [ { "data": { "id": "api_key_0197c0f1-9589-7990-b421-4b806f637b0c" }, "message": "API key updated" } ] }, "deleteDeveloperApiKeyResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "required": [ "message" ], "examples": [ { "data": { "id": "api_key_0197c0f1-9589-7990-b421-4b806f637b0c" }, "message": "API key deleted" } ] }, "apiKeyAnalyticsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "last_hour", "last_2_hours", "last_6_hours", "last_12_hours", "last_day", "last_week", "last_30_days" ], "description": "The window these metrics cover" }, "timezone": { "type": "string", "description": "Zone the day-grain buckets were grouped in. UTC unless a valid zone was requested." }, "bucket_seconds": { "type": "integer", "description": "Width of each hourly_metrics bucket in seconds" }, "core_metrics": { "type": "object", "properties": { "total_requests": { "type": [ "integer", "null" ], "description": "Total number of API requests" }, "requests_per_second": { "type": [ "number", "null" ], "description": "Average requests per second" }, "total_success": { "type": [ "integer", "null" ], "description": "Requests that answered 2xx" }, "total_errors": { "type": [ "integer", "null" ], "description": "Requests that answered 5xx. A 4xx is a rejected request rather than a failure to serve, so it counts toward neither this nor total_success" }, "success_rate_pct": { "type": [ "number", "null" ], "description": "2xx share of requests; 3xx and 4xx count toward neither success nor error" }, "avg_latency_ms": { "type": [ "number", "null" ], "description": "Mean gateway time in milliseconds" }, "under_10ms": { "type": "integer", "description": "Requests whose gateway time was under 10ms" }, "from_10_to_50ms": { "type": "integer", "description": "Requests whose gateway time was 10ms up to 50ms" }, "from_50_to_200ms": { "type": "integer", "description": "Requests whose gateway time was 50ms up to 200ms" }, "over_200ms": { "type": "integer", "description": "Requests whose gateway time was 200ms or more" }, "pct_under_10ms": { "type": [ "number", "null" ], "description": "Share of requests whose gateway time was under 10ms" }, "pct_under_50ms": { "type": [ "number", "null" ], "description": "Share of requests whose gateway time was under 50ms" }, "pct_under_200ms": { "type": [ "number", "null" ], "description": "Share of requests whose gateway time was under 200ms" }, "unique_endpoints": { "type": [ "integer", "null" ], "description": "Number of unique endpoints called" }, "distinct_api_keys": { "type": [ "integer", "null" ], "description": "Number of distinct API keys used" } }, "additionalProperties": false }, "prev_core_metrics": { "type": "object", "properties": { "total_requests": { "type": [ "integer", "null" ], "description": "Total number of API requests" }, "requests_per_second": { "type": [ "number", "null" ], "description": "Average requests per second" }, "total_success": { "type": [ "integer", "null" ], "description": "Requests that answered 2xx" }, "total_errors": { "type": [ "integer", "null" ], "description": "Requests that answered 5xx. A 4xx is a rejected request rather than a failure to serve, so it counts toward neither this nor total_success" }, "success_rate_pct": { "type": [ "number", "null" ], "description": "2xx share of requests; 3xx and 4xx count toward neither success nor error" }, "avg_latency_ms": { "type": [ "number", "null" ], "description": "Mean gateway time in milliseconds" }, "under_10ms": { "type": "integer", "description": "Requests whose gateway time was under 10ms" }, "from_10_to_50ms": { "type": "integer", "description": "Requests whose gateway time was 10ms up to 50ms" }, "from_50_to_200ms": { "type": "integer", "description": "Requests whose gateway time was 50ms up to 200ms" }, "over_200ms": { "type": "integer", "description": "Requests whose gateway time was 200ms or more" }, "pct_under_10ms": { "type": [ "number", "null" ], "description": "Share of requests whose gateway time was under 10ms" }, "pct_under_50ms": { "type": [ "number", "null" ], "description": "Share of requests whose gateway time was under 50ms" }, "pct_under_200ms": { "type": [ "number", "null" ], "description": "Share of requests whose gateway time was under 200ms" }, "unique_endpoints": { "type": [ "integer", "null" ], "description": "Number of unique endpoints called" }, "distinct_api_keys": { "type": [ "integer", "null" ], "description": "Number of distinct API keys used" } }, "additionalProperties": false }, "most_used_api_keys": { "type": "array", "items": { "type": "object", "properties": { "api_key_id": { "type": "string", "description": "API key id" }, "api_key_label": { "type": [ "string", "null" ], "description": "API key label, null when the key no longer exists" }, "usage_count": { "type": "integer", "description": "Number of requests made with this API key" }, "total_success": { "type": "integer", "description": "Number of 2xx responses served to this API key" }, "success_rate": { "type": "number", "description": "2xx share of requests made with this API key; 3xx and 4xx count toward neither success nor error" } }, "required": [ "api_key_id", "api_key_label", "usage_count", "total_success", "success_rate" ], "additionalProperties": false } }, "ip_metrics": { "type": "array", "description": "Metrics by IP address", "items": { "type": "object", "properties": { "ip": { "type": [ "string", "null" ], "description": "IP address" }, "total_requests": { "type": "integer", "description": "Total number of requests from this IP" }, "total_success": { "type": "integer", "description": "Number of 2xx responses served to this IP" }, "success_rate": { "type": "number", "description": "2xx share of requests from this IP; 3xx and 4xx count toward neither success nor error, so this and error_rate do not sum to 100" }, "total_errors": { "type": "integer", "description": "Number of 5xx responses served to this IP" }, "error_rate": { "type": "number", "description": "5xx share of requests from this IP" }, "country_code": { "type": [ "string", "null" ], "description": "ISO country code from the latest IP lookup, null when the address has never been looked up" }, "city": { "type": [ "string", "null" ], "description": "City from the latest IP lookup" }, "isp": { "type": [ "string", "null" ], "description": "ISP from the latest IP lookup" } }, "additionalProperties": false } }, "hourly_metrics": { "type": "array", "description": "Metrics per time bucket across the period; each bucket is bucket_seconds wide", "items": { "type": "object", "properties": { "hour": { "type": "string", "description": "Bucket start. An hour boundary at hour grain, the exact bucket start at finer grains." }, "total_requests": { "type": "integer", "description": "Total number of requests in this hour" }, "success_count": { "type": "integer", "description": "2xx responses in this bucket" }, "error_count": { "type": "integer", "description": "Number of 5xx responses in this bucket" }, "error_rate_pct": { "type": "number", "description": "5xx share of requests in this bucket" }, "avg_latency_ms": { "type": "number", "description": "Average latency in milliseconds for this hour" }, "success_rate_pct": { "type": "number", "description": "2xx share of requests in this bucket; 3xx and 4xx count toward neither success nor error, so this and error_rate_pct do not sum to 100" }, "unique_endpoints": { "type": "integer", "description": "Distinct paths seen in this bucket" }, "distinct_api_keys": { "type": "integer", "description": "Distinct API keys seen in this bucket" } }, "additionalProperties": false } }, "latency_breakdown": { "description": "Disjoint histogram of gateway time. For inference that is routing only; other routes measure the whole request.", "type": [ "object", "null" ], "properties": { "total_requests": { "type": "integer", "description": "Total number of requests" }, "under_10ms": { "type": "integer", "description": "Requests whose gateway time was under 10ms" }, "from_10_to_50ms": { "type": "integer", "description": "Requests whose gateway time was 10ms up to 50ms" }, "from_50_to_200ms": { "type": "integer", "description": "Requests whose gateway time was 50ms up to 200ms" }, "over_200ms": { "type": "integer", "description": "Requests whose gateway time was 200ms or more" } } }, "latency": { "description": "API Keys latency metrics", "type": [ "object", "null" ], "properties": { "min": { "type": "number", "format": "float", "description": "Minimum latency in milliseconds for API Request deliveries" }, "max": { "type": "number", "format": "float", "description": "Maximum latency in milliseconds for API Request deliveries" }, "avg": { "type": "number", "format": "float", "description": "Average latency in milliseconds for API Request deliveries" }, "p50": { "type": "number", "format": "float", "description": "50th percentile latency in milliseconds for API Request deliveries" }, "p90": { "type": "number", "format": "float", "description": "90th percentile latency in milliseconds for API Request deliveries" }, "p95": { "type": "number", "format": "float", "description": "95th percentile latency in milliseconds for API Request deliveries" }, "p99": { "type": "number", "format": "float", "description": "99th percentile latency in milliseconds for API Request deliveries" } }, "additionalProperties": false } }, "required": [ "period", "bucket_seconds", "timezone", "core_metrics", "prev_core_metrics", "most_used_api_keys", "ip_metrics", "hourly_metrics", "latency_breakdown", "latency" ], "additionalProperties": false } }, "required": [ "data" ], "examples": [ { "data": { "period": "last_30_days", "bucket_seconds": 86400, "timezone": "UTC", "core_metrics": { "total_requests": 4, "requests_per_second": 0, "total_success": 3, "total_errors": 1, "success_rate_pct": 75, "avg_latency_ms": 67.5, "under_10ms": 0, "from_10_to_50ms": 1, "from_50_to_200ms": 3, "over_200ms": 0, "pct_under_10ms": 0, "pct_under_50ms": 25, "pct_under_200ms": 100, "unique_endpoints": 1, "distinct_api_keys": 2 }, "prev_core_metrics": { "total_requests": 10, "requests_per_second": 0, "total_success": 8, "total_errors": 2, "success_rate_pct": 80, "avg_latency_ms": 120, "under_10ms": 0, "from_10_to_50ms": 2, "from_50_to_200ms": 7, "over_200ms": 1, "pct_under_10ms": 0, "pct_under_50ms": 20, "pct_under_200ms": 90, "unique_endpoints": 3, "distinct_api_keys": 4 }, "most_used_api_keys": [ { "api_key_id": "key_01HZX9", "api_key_label": "production", "usage_count": 3, "total_success": 3, "success_rate": 100 } ], "ip_metrics": [ { "ip": "203.0.113.7", "total_requests": 3, "total_success": 2, "success_rate": 66.67, "total_errors": 1, "error_rate": 33.33, "country_code": "IT", "city": "Rome", "isp": "Example ISP" }, { "ip": "2001:db8::1", "total_requests": 1, "total_success": 1, "success_rate": 100, "total_errors": 0, "error_rate": 0, "country_code": null, "city": null, "isp": null } ], "hourly_metrics": [ { "hour": "2025-07-30 00:00:00", "total_requests": 3, "success_count": 2, "error_count": 1, "error_rate_pct": 33.33, "success_rate_pct": 66.67, "avg_latency_ms": 71.33, "unique_endpoints": 1, "distinct_api_keys": 2 }, { "hour": "2025-07-31 00:00:00", "total_requests": 1, "success_count": 1, "error_count": 0, "error_rate_pct": 0, "success_rate_pct": 100, "avg_latency_ms": 56, "unique_endpoints": 1, "distinct_api_keys": 1 } ], "latency_breakdown": { "total_requests": 4, "under_10ms": 0, "from_10_to_50ms": 1, "from_50_to_200ms": 3, "over_200ms": 0 }, "latency": { "min": 42, "max": 110, "avg": 67.5, "p50": 59, "p90": 110, "p95": 110, "p99": 110 } }, "message": null } ] }, "listApiKeyScopesResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "type": "string" }, "description": "List of available API key scopes" } }, "required": [ "scopes" ], "additionalProperties": false } }, "required": [ "data" ], "examples": [ { "data": { "scopes": [ "api_key.create", "api_key.read", "api_key.update", "api_key.delete", "users.read", "users.update", "users_sessions.read", "chats.completion", "tools.execute", "files_encrypted.create", "files_encrypted.read", "audio.transcription", "audio.translation" ] }, "message": null } ] }, "developersApiKeyRequest": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the request log entry" }, "is_developer": { "type": "number", "description": "Whether this was a developer API request" }, "organization_id": { "type": [ "string", "null" ], "description": "Organization ID that made the request" }, "user_id": { "type": [ "string", "null" ], "description": "User ID that made the request" }, "api_key_id": { "type": [ "string", "null" ], "description": "API key used for the request" }, "session_id": { "type": [ "string", "null" ], "description": "Authentication session ID associated with the request" }, "support_id": { "type": [ "string", "null" ], "description": "Support ticket ID if applicable" }, "ip": { "type": [ "string", "null" ], "description": "IP address that made the request" }, "path": { "type": "string", "description": "Request path" }, "method": { "type": [ "string", "null" ], "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", null ], "description": "HTTP method used" }, "user_agent": { "type": [ "string", "null" ], "description": "User agent string" }, "ms": { "type": "number", "description": "Request duration in milliseconds" }, "overhead_ms": { "type": [ "number", "null" ], "description": "Proxy overhead in milliseconds: arrival to upstream dispatch, excluding queue wait. Null for requests logged before it was tracked" }, "response_code": { "type": "string", "description": "HTTP response status code" }, "response_body": { "type": [ "object", "string", "null" ], "description": "Response body as JSON" }, "request_body": { "type": [ "string", "null" ], "description": "Request body as text" }, "request_headers": { "type": [ "string", "null" ], "description": "Request headers as text" }, "memory_peak": { "type": [ "number", "null" ], "description": "Peak memory usage for the request" }, "created_at": { "type": "string", "format": "mysql-date-time", "description": "Timestamp when the request was logged" } }, "required": [ "id", "is_developer", "path", "ms", "response_code", "response_body", "created_at" ], "additionalProperties": false, "examples": [ { "id": 12345, "is_developer": 1, "organization_id": "org_0197c0ec-a197-719f-84a9-99270a79b42a", "user_id": null, "api_key_id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "session_id": null, "support_id": null, "ip": "127.0.0.1", "path": "/products", "method": "POST", "user_agent": "MyApp/1.0.0", "ms": 234.5678, "overhead_ms": 12.3456, "response_code": "201", "response_body": { "data": { "id": "prod_123", "name": "Test Product" } }, "request_body": "{\"name\": \"Test Product\", \"price\": 19.99}", "request_headers": "Content-Type: application/json\nAuthorization: REDACTED", "memory_peak": 2048, "created_at": "2025-07-01 12:34:56" } ] }, "listDeveloperApiKeyRequestsRequest": { "type": "object", "description": "Request body for filtering API key requests", "properties": { "api_key_id": { "type": "array", "description": "Filter by API key ID(s)", "items": { "type": "string" } }, "created_at_from": { "type": "string", "format": "mysql-date-time", "description": "Filter requests from this date" }, "created_at_to": { "type": "string", "format": "mysql-date-time", "description": "Filter requests until this date" }, "status": { "type": "array", "description": "Filter by HTTP response status code", "items": { "type": "string", "enum": [ "success", "failed" ] } }, "method": { "type": "array", "description": "Filter by HTTP method", "items": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD" ] } }, "search": { "type": "string", "description": "General search across path, ID, scope, and IP" }, "limit": { "type": "integer", "default": 50, "minimum": 1, "description": "Maximum number of results to return" }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Number of results to skip" } }, "additionalProperties": false }, "listDeveloperApiKeyRequestsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total count of matching requests" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/developersApiKeyRequest" }, "description": "Array of API key request log entries" } }, "required": [ "count", "items" ], "additionalProperties": false } }, "required": [ "data" ], "examples": [ { "data": { "count": 2, "items": [ { "id": 12345, "is_developer": 1, "organization_id": "org_0197c0ec-a197-719f-84a9-99270a79b42a", "user_id": null, "api_key_id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "session_id": null, "support_id": null, "ip": "127.0.0.1", "path": "/products", "method": "POST", "user_agent": "MyApp/1.0.0", "ms": 234.5678, "overhead_ms": 12.3456, "response_code": "201", "response_body": { "data": { "id": "prod_123", "name": "Test Product" } }, "request_body": "{\"name\": \"Test Product\", \"price\": 19.99}", "request_headers": "Content-Type: application/json", "memory_peak": 2048, "created_at": "2025-07-01 12:34:56" }, { "id": 12346, "is_developer": 1, "organization_id": "org_0197c0ec-a197-719f-84a9-99270a79b42a", "user_id": null, "api_key_id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "session_id": null, "support_id": null, "ip": "127.0.0.1", "path": "/products/prod_123", "method": "GET", "user_agent": "MyApp/1.0.0", "ms": 89.1234, "overhead_ms": null, "response_code": "200", "response_body": { "data": { "id": "prod_123", "name": "Test Product", "price": 19.99 } }, "request_body": null, "request_headers": "Authorization: REDACTED", "memory_peak": 1024, "created_at": "2025-07-01 12:35:30" } ] } } ] }, "viewDeveloperApiKeyRequestResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/developersApiKeyRequest" } }, "required": [ "data" ], "examples": [ { "data": { "id": 12345, "is_developer": 1, "organization_id": "org_0197c0ec-a197-719f-84a9-99270a79b42a", "user_id": null, "api_key_id": "api_key_0197c0ec-a197-719f-84a9-99270a79b42a", "session_id": null, "support_id": null, "ip": "127.0.0.1", "path": "/products", "method": "POST", "user_agent": "MyApp/1.0.0 (https://myapp.com)", "ms": 234.5678, "overhead_ms": 12.3456, "response_code": "201", "response_body": { "data": { "id": "prod_0197c0ec-a197-719f-84a9-99270a79b42a", "name": "Test Product", "price": 19.99, "currency": "USD", "created_at": "2025-07-01 12:34:56" } }, "request_body": "{\"name\": \"Test Product\", \"price\": 19.99, \"currency\": \"USD\"}", "request_headers": "Content-Type: application/json\nAuthorization: REDACTED\nUser-Agent: MyApp/1.0.0\nContent-Length: 67", "memory_peak": 2048.5, "created_at": "2025-07-01 12:34:56" } } ] }, "fileEncrypted": { "type": "object", "description": "Encrypted file object containing file identifier and encrypted metadata", "properties": { "id": { "type": "string", "description": "Unique identifier for the encrypted file", "examples": [ "file_0196b6e6-54e3-796d-9c6a-2862a5fef597" ] }, "user_id": { "type": [ "string", "null" ], "description": "User identifier that owns the file", "examples": [ "user_0196b0e9-11d8-7f26-b1d2-bd47054e4827" ] }, "organization_id": { "type": [ "string", "null" ], "description": "Organization identifier that owns the file", "examples": [ "org_0196b0e9-11d8-7f26-b1d2-bd47054e4827" ] }, "api_key_id": { "type": [ "string", "null" ], "description": "API Key identifier that owns the file", "examples": [ "api_key_019ae099-2a6f-755d-b356-6847c657fd63" ] }, "hash": { "type": [ "string", "null" ], "description": "File hash for duplicate detection", "examples": [ "04b9e2ec43133ae7287f97764c0beda19f304374e1d6bfe4fcc36ad54502e5dc" ] }, "version": { "type": "string", "description": "Encryption version", "examples": [ "1" ] }, "kid": { "type": "string", "description": "Key identifier used for encryption", "examples": [ "key_01234567-89ab-cdef-0123-456789abcdef" ] }, "wrapped_dek": { "type": "string", "description": "Wrapped data encryption key", "examples": [ "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" ] }, "original_name": { "type": "string", "description": "Original filename, encrypted by the client", "examples": [ "encrypted_filename_data" ] }, "mime_type": { "type": "string", "description": "MIME type, encrypted by the client", "examples": [ "encrypted_mime_type_data" ] }, "file_name": { "type": "string", "description": "Generated filename for storage", "examples": [ "0198042e-6dde-76e0-b817-3afb324e29ac.enc" ] }, "file_path": { "type": [ "string", "null" ], "description": "Full path to the encrypted file in storage", "examples": [ "encrypted/org_0196b0e9-11d8-7f26-b1d2-bd47054e4827/user_0196b0e9-11d8-7f26-b1d2-bd47054e4827/0198042e-6dde-76e0-b817-3afb324e29ac.enc" ] }, "file_size": { "type": "integer", "description": "File size in bytes", "examples": [ 1060793 ] }, "chat_id": { "type": [ "string", "null" ], "description": "ID of the chat this file belongs to", "examples": [ "chat_0197c0f1-9589-7990-b421-4b806f637b0c" ] }, "message_id": { "type": [ "string", "null" ], "description": "ID of the message this file belongs to", "examples": [ "message_0197c0f1-9589-7990-b421-4b806f637b0c" ] }, "type": { "type": "string", "description": "Type of the file - always 'encrypted' for fully encrypted files", "examples": [ "encrypted" ] }, "created_at": { "type": "string", "format": "mysql-date-time", "description": "Timestamp when the file was created", "examples": [ "2025-07-13 16:26:48.415" ] }, "rag_status": { "type": [ "string", "null" ], "enum": [ "running", "stopped", "failure", "success", "pending", null ], "description": "Status of the RAG processing", "examples": [ "pending", "completed", "failed", null ] }, "updated_at": { "type": [ "string", "null" ], "format": "mysql-date-time", "description": "Timestamp when the file was last updated", "examples": [ null ] }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Signed URL for accessing the encrypted file resource (only included when url=true query parameter is set)", "examples": [ "https://encrypted.prem.io/encrypted/org_0196b0e9-11d8-7f26-b1d2-bd47054e4827/user_0196b0e9-11d8-7f26-b1d2-bd47054e4827/0198042e-6dde-76e0-b817-3afb324e29ac.pdf.enc" ] }, "is_duplicate": { "type": "boolean", "description": "Indicates if the file is a duplicate (only included in upload response)", "examples": [ false ] }, "chat_wrapped_dek": { "type": [ "string", "null" ], "description": "File DEK encrypted with chat DEK (hex), for shared chat file access", "examples": [ null ] } }, "additionalProperties": false, "examples": [ { "id": "file_0198042e-6dde-7b9c-bc91-452a7e0c833b", "user_id": "user_0196b0e9-11d8-7f26-b1d2-bd47054e4827", "organization_id": "org_0196b0e9-11d8-7f26-b1d2-bd47054e4827", "api_key_id": "api_key_019ae099-2a6f-755d-b356-6847c657fd63", "hash": "04b9e2ec43133ae7287f97764c0beda19f304374e1d6bfe4fcc36ad54502e5dc", "version": "1", "kid": "key_01234567-89ab-cdef-0123-456789abcdef", "wrapped_dek": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "original_name": "encrypted_filename_data", "mime_type": "encrypted_mime_type_data", "file_name": "0198042e-6dde-76e0-b817-3afb324e29ac.enc", "file_path": "encrypted/org_0196b0e9-11d8-7f26-b1d2-bd47054e4827/user_0196b0e9-11d8-7f26-b1d2-bd47054e4827/0198042e-6dde-76e0-b817-3afb324e29ac.enc", "file_size": 1060793, "type": "encrypted", "rag_status": "pending", "created_at": "2025-07-13 16:26:48.415", "updated_at": null } ] }, "uploadFileEncryptedRequest": { "type": "object", "description": "Request body for uploading an encrypted file", "properties": { "encrypted_content": { "type": "string", "description": "The encrypted file content as hexadecimal string", "examples": [ "0123456789abcdef..." ] }, "encrypted_name": { "type": "string", "description": "The encrypted original filename", "maxLength": 1024, "examples": [ "encrypted_filename" ] }, "client_hash": { "type": "string", "description": "Client-side hash for duplicate detection", "examples": [ "04b9e2ec43133ae7287f97764c0beda19f304374e1d6bfe4fcc36ad54502e5dc" ] }, "kid": { "type": "string", "description": "Key identifier used for encryption", "examples": [ "key_01234567-89ab-cdef-0123-456789abcdef" ] }, "wrapped_dek": { "type": "string", "description": "Wrapped data encryption key", "examples": [ "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" ] }, "mime_type": { "type": "string", "description": "MIME type of the original file (encrypted on client side before sending)", "examples": [ "encrypted_mime_type_data" ] }, "incognito": { "type": "boolean", "description": "Whether the file is incognito (optional)", "examples": [ true ] }, "version": { "type": [ "integer", "string" ], "description": "Encryption version (optional)", "examples": [ 1 ] }, "encrypted_rag_dek": { "type": "string", "description": "Encrypted RAG data encryption key", "examples": [ "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" ] }, "rag_dek_nonce": { "type": "string", "description": "Nonce used for RAG DEK encryption", "examples": [ "0123456789abcdef0123456789abcdef" ] }, "cipher_text": { "type": "string", "description": "Cipher text for RAG encryption context", "examples": [ "cipher_text_data" ] }, "encrypted_file_dek": { "type": "string", "description": "Encrypted file data encryption key", "examples": [ "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" ] }, "file_nonce": { "type": "string", "description": "Nonce used for file encryption", "examples": [ "0123456789abcdef0123456789abcdef" ] } }, "required": [ "encrypted_content", "client_hash", "kid", "wrapped_dek", "encrypted_name", "mime_type" ], "additionalProperties": false }, "uploadFileEncryptedResponse": { "type": "object", "description": "Response containing the uploaded encrypted file information", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the encrypted file", "examples": [ "file_0198042e-6dde-7b9c-bc91-452a7e0c833b" ] }, "version": { "type": "string", "description": "Encryption version", "examples": [ "1", "2" ] }, "kid": { "type": "string", "description": "Key identifier used for encryption", "examples": [ "key_01234567-89ab-cdef-0123-456789abcdef" ] }, "wrapped_dek": { "type": "string", "description": "Wrapped data encryption key", "examples": [ "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" ] }, "file_name": { "type": "string", "description": "Generated filename for storage", "examples": [ "0198042e-6dde-76e0-b817-3afb324e29ac.enc" ] }, "file_path": { "type": "string", "description": "Full path to the encrypted file in storage", "examples": [ "encrypted/org_0196b0e9-11d8-7f26-b1d2-bd47054e4827/user_0196b0e9-11d8-7f26-b1d2-bd47054e4827/0198042e-6dde-76e0-b817-3afb324e29ac.enc" ] }, "file_size": { "type": "integer", "description": "File size in bytes", "examples": [ 1060793 ] }, "type": { "type": "string", "description": "Type of the file - always 'encrypted' for fully encrypted files", "examples": [ "encrypted" ] }, "mime_type": { "type": "string", "description": "MIME type, encrypted by the client", "examples": [ "encrypted_mime_type_data" ] }, "is_duplicate": { "type": "boolean", "description": "Indicates if the file is a duplicate", "examples": [ false ] }, "created_at": { "type": "string", "format": "mysql-date-time", "description": "Timestamp when the file was created", "examples": [ "2025-07-13 16:26:48.415" ] }, "updated_at": { "type": [ "string", "null" ], "format": "mysql-date-time", "description": "Timestamp when the file was last updated", "examples": [ null ] }, "original_name": { "type": "string", "description": "Original filename", "examples": [ "encrypted-original-filename" ] } }, "required": [ "id", "version", "kid", "wrapped_dek", "file_name", "file_path", "file_size", "type", "mime_type", "is_duplicate" ], "additionalProperties": false } }, "required": [ "data" ], "examples": [ { "data": { "id": "file_0198042e-6dde-7b9c-bc91-452a7e0c833b", "version": "1", "kid": "key_01234567-89ab-cdef-0123-456789abcdef", "wrapped_dek": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "file_name": "0198042e-6dde-76e0-b817-3afb324e29ac.enc", "file_path": "encrypted/org_0196b0e9-11d8-7f26-b1d2-bd47054e4827/user_0196b0e9-11d8-7f26-b1d2-bd47054e4827/0198042e-6dde-76e0-b817-3afb324e29ac.enc", "file_size": 1060793, "type": "encrypted", "mime_type": "encrypted_mime_type_data", "is_duplicate": false, "created_at": "2025-07-13 16:26:48.415", "updated_at": null, "original_name": "encrypted-original-filename" } } ] }, "listFilesEncryptedResponse": { "type": "object", "description": "Response containing a paginated list of encrypted files", "properties": { "data": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/fileEncrypted" }, "description": "Array of encrypted file objects" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "files", "pagination" ], "additionalProperties": false } }, "required": [ "data" ] }, "viewFileEncryptedResponse": { "type": "object", "description": "Response containing encrypted file details", "properties": { "data": { "$ref": "#/components/schemas/fileEncrypted" } }, "required": [ "data" ], "examples": [ { "data": { "id": "file_0198042e-6dde-7b9c-bc91-452a7e0c833b", "user_id": "user_0196b0e9-11d8-7f26-b1d2-bd47054e4827", "organization_id": "org_0196b0e9-11d8-7f26-b1d2-bd47054e4827", "hash": "04b9e2ec43133ae7287f97764c0beda19f304374e1d6bfe4fcc36ad54502e5dc", "version": "1", "kid": "key_01234567-89ab-cdef-0123-456789abcdef", "wrapped_dek": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "original_name": "document.pdf", "file_name": "0198042e-6dde-76e0-b817-3afb324e29ac.pdf.enc", "file_path": "encrypted/org_0196b0e9-11d8-7f26-b1d2-bd47054e4827/user_0196b0e9-11d8-7f26-b1d2-bd47054e4827/0198042e-6dde-76e0-b817-3afb324e29ac.pdf.enc", "mime_type": "application/pdf", "file_size": 1060793, "type": "document", "created_at": "2025-07-13 16:26:48.415", "updated_at": null, "url": "https://encrypted.prem.io/encrypted/org_0196b0e9-11d8-7f26-b1d2-bd47054e4827/user_0196b0e9-11d8-7f26-b1d2-bd47054e4827/0198042e-6dde-76e0-b817-3afb324e29ac.pdf.enc" } } ] }, "deleteFileEncryptedResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "required": [ "message" ], "examples": [ { "message": "File deleted successfully" } ] }, "indexFileEncryptedRequest": { "type": "object", "description": "Request body for indexing encrypted files for RAG", "properties": { "files": { "type": "array", "description": "Array of encrypted files to index", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "The ID of the encrypted file to index", "examples": [ "file_0198042e-6dde-7b9c-bc91-452a7e0c833b" ] }, "encrypted_file_dek": { "type": "string", "description": "Encrypted file data encryption key", "examples": [ "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" ] }, "encrypted_rag_dek": { "type": "string", "description": "Encrypted RAG data encryption key", "examples": [ "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" ] }, "file_nonce": { "type": "string", "description": "Nonce used for file encryption", "examples": [ "0123456789abcdef0123456789abcdef" ] }, "rag_dek_nonce": { "type": "string", "description": "Nonce used for RAG DEK encryption", "examples": [ "0123456789abcdef0123456789abcdef" ] }, "s3_r2_path": { "type": "string", "description": "Storage path of the encrypted file", "examples": [ "encrypted/org_0196b0e9-11d8-7f26-b1d2-bd47054e4827/user_0196b0e9-11d8-7f26-b1d2-bd47054e4827/0198042e-6dde-76e0-b817-3afb324e29ac.enc" ] }, "cipher_text": { "type": "string", "description": "Cipher text for encryption context", "examples": [ "cipher_text_data" ] } }, "required": [ "file_id", "encrypted_file_dek", "encrypted_rag_dek", "file_nonce", "rag_dek_nonce", "s3_r2_path", "cipher_text" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "files" ], "additionalProperties": false }, "indexFileEncryptedResponse": { "type": "object", "description": "Response containing the file indexing status", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of indexing results for each file", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "The ID of the encrypted file", "examples": [ "file_0198042e-6dde-7b9c-bc91-452a7e0c833b" ] }, "rag_status": { "type": [ "string", "null" ], "enum": [ "running", "stopped", "failure", "success", null ], "description": "Current RAG indexing status", "examples": [ "running", null ] }, "success": { "type": "boolean", "description": "Whether the file was successfully queued for indexing" }, "error": { "type": "string", "description": "Error message if file failed to be queued", "examples": [ "File not found" ] } }, "required": [ "file_id", "success" ], "additionalProperties": false } }, "enclave_response": { "type": "object", "description": "Details about the indexing request (optional)", "additionalProperties": true } }, "required": [ "results" ], "additionalProperties": false } }, "required": [ "data" ], "examples": [ { "data": { "results": [ { "file_id": "file_0198042e-6dde-7b9c-bc91-452a7e0c833b", "rag_status": "running", "success": true }, { "file_id": "file_0198042e-6dde-7b9c-bc91-452a7e0c833c", "rag_status": "running", "success": true } ], "enclave_response": {} } } ] }, "indexResultFileEncryptedRequest": { "type": "object", "description": "The file ID and RAG status that the Prem API Enclave sends to the callback on the public Prem API Gateway.", "properties": { "file_id": { "type": "string", "description": "The ID of the encrypted file", "examples": [ "file_0198042e-6dde-7b9c-bc91-452a7e0c833b" ] }, "rag_status": { "type": [ "string", "null" ], "enum": [ "running", "stopped", "failure", "success", null ], "description": "The RAG indexing status", "examples": [ "success", null ] } }, "required": [ "file_id", "rag_status" ], "additionalProperties": false }, "indexResultFileEncryptedResponse": { "type": "object", "description": "The response after the Prem API Gateway updates the file's RAG status.", "properties": { "data": { "type": "object", "properties": { "file_id": { "type": "string", "description": "The ID of the encrypted file", "examples": [ "file_0198042e-6dde-7b9c-bc91-452a7e0c833b" ] }, "rag_status": { "type": [ "string", "null" ], "enum": [ "running", "stopped", "failure", "success", null ], "description": "Updated RAG indexing status", "examples": [ "success", null ] }, "message": { "type": "string", "description": "Status message", "examples": [ "RAG status updated successfully" ] } }, "required": [ "file_id", "rag_status", "message" ], "additionalProperties": false } }, "required": [ "data" ], "examples": [ { "data": { "file_id": "file_0198042e-6dde-7b9c-bc91-452a7e0c833b", "rag_status": "success", "message": "RAG status updated successfully" } } ] }, "deleteIndexFileEncryptedRequest": { "type": "object", "description": "Request body for deleting index of encrypted files from RAG", "properties": { "cipher_text": { "type": "string", "description": "Cipher text for encryption context", "examples": [ "cipher_text_data" ] }, "encrypted_rag_dek": { "type": "string", "description": "Encrypted RAG data encryption key", "examples": [ "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" ] }, "rag_dek_nonce": { "type": "string", "description": "Nonce used for RAG DEK encryption", "examples": [ "0123456789abcdef0123456789abcdef" ] }, "fileIds": { "type": "array", "description": "Array of file IDs to delete from index", "items": { "type": "string", "description": "File ID", "examples": [ "file_0198042e-6dde-7b9c-bc91-452a7e0c833b" ] }, "minItems": 1 } }, "required": [ "cipher_text", "encrypted_rag_dek", "rag_dek_nonce", "fileIds" ], "additionalProperties": false }, "deleteIndexFileEncryptedResponse": { "type": "object", "description": "Response containing the file index deletion status", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of deletion results for each file", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "The ID of the encrypted file", "examples": [ "file_0198042e-6dde-7b9c-bc91-452a7e0c833b" ] }, "success": { "type": "boolean", "description": "Whether the file index was successfully queued for deletion" }, "error": { "type": "string", "description": "Error message if file failed to be queued", "examples": [ "File not found" ] } }, "required": [ "file_id", "success" ], "additionalProperties": false } }, "async_task_id": { "type": "string", "description": "ID of the async task that will clean up the Qdrant collection" } }, "required": [ "results" ], "additionalProperties": false } }, "required": [ "data" ], "examples": [ { "data": { "results": [ { "file_id": "file_0198042e-6dde-7b9c-bc91-452a7e0c833b", "success": true }, { "file_id": "file_0198042e-6dde-7b9c-bc91-452a7e0c833c", "success": true } ], "async_task_id": "task_0198042e-6dde-7b9c-bc91-452a7e0c833d" } } ] }, "rvencModel": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique public model identifier (slug)" }, "model": { "type": "string", "description": "Model slug to pass in the `model` field of confidential (rvenc) chat completion requests to select this model" }, "name": { "type": "string", "description": "Human-readable model name" }, "description": { "type": [ "string", "null" ], "description": "Model description" }, "type": { "type": "string", "description": "Model type", "enum": [ "CHAT", "DECISIONS", "AUDIO_TRANSCRIPTION", "AUDIO_SPEECH", "IMAGE" ] }, "metadata": { "$ref": "#/components/schemas/modelMetadata" }, "input_modalities": { "type": "array", "description": "Input modalities supported by the model", "items": { "type": "string" } }, "price_config": { "type": [ "object", "null" ], "description": "Pricing nested by inference type then region. Each type maps region codes to a rate object, plus a 'default' rate. Rate keys: prompt_price_per_k, cached_prompt_price_per_k, completion_price_per_k, reasoning_price_per_k, audio_price_per_min.", "properties": { "standard": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/chatsModelRate" } }, "confidential": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/chatsModelRate" } } }, "additionalProperties": false }, "regions": { "type": "array", "description": "Region codes the model can be served from for confidential (rvenc) inference.", "items": { "type": "string" } }, "requires_auth": { "type": "integer", "description": "Whether the model requires authentication (0 or 1)", "minimum": 0, "maximum": 1 }, "usage_mode": { "type": "string", "description": "Usage mode defining how the model can be accessed", "enum": [ "CHAT", "API", "ALL" ], "default": "ALL" }, "visible_in_dashboard": { "type": "integer", "description": "Whether the model is visible in the model pickers", "minimum": 0, "maximum": 1 }, "likes_count": { "type": "integer", "description": "Total number of likes across all users", "minimum": 0 }, "dislikes_count": { "type": "integer", "description": "Total number of dislikes across all users", "minimum": 0 }, "total_reviews": { "type": "integer", "description": "Total number of feedback entries (likes + dislikes) for this model", "minimum": 0 }, "rating_percent": { "type": [ "number", "null" ], "description": "Percentage of likes among total reviews (0-100), null when no reviews", "minimum": 0, "maximum": 100 } }, "required": [ "id", "metadata", "model", "name", "type", "input_modalities", "regions", "requires_auth", "usage_mode", "visible_in_dashboard", "likes_count", "dislikes_count", "total_reviews" ], "additionalProperties": false }, "modelMetadata": { "type": "object", "description": "Public model metadata.", "properties": { "attestation_version": { "type": "string", "examples": [ "v2" ], "description": "The standard attestation protocol is `v2`, which returns one confidential-VM report. See `/rvenc/models` for confidential availability." } }, "required": [ "attestation_version" ], "additionalProperties": false }, "chatsModelRate": { "type": "object", "description": "Per-model pricing rates. All values are USD.", "properties": { "prompt_price_per_k": { "type": "number" }, "cached_prompt_price_per_k": { "type": "number" }, "completion_price_per_k": { "type": "number" }, "reasoning_price_per_k": { "type": "number" }, "audio_price_per_min": { "type": "number" } }, "additionalProperties": false }, "chatsTool": { "type": "object", "properties": { "name": { "type": "string", "description": "Technical name of the tool" }, "normalizedName": { "type": "string", "description": "Human-readable display name of the tool" }, "description": { "type": "string", "description": "Description of what the tool does" }, "shortName": { "type": "string", "description": "Short name of the tool" } }, "required": [ "name", "normalizedName", "description", "shortName" ], "additionalProperties": false, "examples": [ { "name": "generateImage", "normalizedName": "Generate Image", "shortName": "Image", "description": "Generate Image through Diffusion Model" }, { "name": "webSearchTool", "normalizedName": "Web Search", "shortName": "Web", "description": "Search the web for information." } ] }, "rvencInferenceParams": { "type": "object", "description": "Structure of the JSON to encrypt and send as `encryptedInference`.", "properties": { "messages": { "type": "array", "description": "A list of messages comprising the conversation so far. Depending on the model you use, different message types (modalities) are supported, like text, images, and audio.", "items": { "oneOf": [ { "type": "object", "description": "Developer-provided instructions that the model should follow. With o1 models and newer, use developer messages for this purpose instead.", "properties": { "role": { "type": "string", "enum": [ "system" ], "description": "The role of the messages author, in this case system" }, "content": { "oneOf": [ { "type": "string", "description": "The contents of the system message" }, { "type": "array", "description": "An array of content parts with a defined type. For system messages, only type text is supported", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The text content" }, "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part" } }, "required": [ "text", "type" ] } } ], "description": "The contents of the system message" }, "name": { "type": "string", "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role" } }, "required": [ "role", "content" ] }, { "type": "object", "description": "Messages sent by an end user, containing prompts or additional context information", "properties": { "role": { "type": "string", "enum": [ "user" ], "description": "The role of the messages author, in this case user" }, "content": { "oneOf": [ { "type": "string", "description": "The text contents of the message" }, { "type": "array", "description": "An array of content parts with a defined type. Supported options differ based on the model being used to generate the response. Can contain text, image, or audio inputs", "items": { "oneOf": [ { "type": "object", "properties": { "text": { "type": "string", "description": "The text content" }, "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part" } }, "required": [ "text", "type" ] }, { "type": "object", "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "description": "Either a URL of the image or the base64 encoded image data" }, "detail": { "type": "string", "enum": [ "low", "high", "auto" ], "default": "auto", "description": "Specifies the detail level of the image" } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ], "description": "The type of the content part" } }, "required": [ "image_url", "type" ] }, { "type": "object", "properties": { "input_audio": { "type": "object", "properties": { "data": { "type": "string", "description": "Base64 encoded audio data" }, "format": { "type": "string", "enum": [ "wav", "mp3" ], "description": "The format of the encoded audio data" } }, "required": [ "data", "format" ] }, "type": { "type": "string", "enum": [ "input_audio" ], "description": "The type of the content part. Always input_audio" } }, "required": [ "input_audio", "type" ] }, { "type": "object", "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "description": "The base64 encoded file data, used when passing the file to the model as a string" }, "file_id": { "type": "string", "description": "The ID of an uploaded file to use as input" }, "filename": { "type": "string", "description": "The name of the file, used when passing the file to the model as a string" } } }, "type": { "type": "string", "enum": [ "file" ], "description": "The type of the content part. Always file" } }, "required": [ "file", "type" ] } ] } } ], "description": "The contents of the user message" }, "name": { "type": "string", "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role" } }, "required": [ "role", "content" ] }, { "type": "object", "description": "Messages sent by the model in response to user messages", "properties": { "role": { "type": "string", "enum": [ "assistant" ], "description": "The role of the messages author, in this case assistant" }, "audio": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for a previous audio response from the model" } }, "required": [ "id" ], "description": "Data about a previous audio response from the model" }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The text content" }, "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part" } }, "required": [ "text", "type" ] } } ], "description": "The contents of the assistant message. Required unless tool_calls or function_call is specified" }, "function_call": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function to call" }, "arguments": { "type": "string", "description": "The arguments to call the function with, as generated by the model in JSON format" } }, "required": [ "name", "arguments" ], "description": "Deprecated and replaced by tool_calls. The name and arguments of a function that should be called, as generated by the model" }, "name": { "type": "string", "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role" }, "refusal": { "type": "string", "description": "The refusal message by the assistant" }, "tool_calls": { "type": "array", "description": "The tool calls generated by the model, such as function calls", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the tool call" }, "type": { "type": "string", "description": "Type of tool call" }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the function to call" }, "arguments": { "type": "string", "description": "JSON string of function arguments" } }, "required": [ "name", "arguments" ] } }, "required": [ "id", "type", "function" ] } } }, "required": [ "role" ] }, { "type": "object", "description": "Tool message", "properties": { "role": { "type": "string", "enum": [ "tool" ], "description": "The role of the messages author, in this case tool" }, "content": { "oneOf": [ { "type": "string", "description": "The contents of the tool message" }, { "type": "array", "description": "An array of content parts with a defined type. For tool messages, only type text is supported", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The text content" }, "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part" } }, "required": [ "text", "type" ] } } ], "description": "The contents of the tool message" }, "tool_call_id": { "type": "string", "description": "Tool call that this message is responding to" } }, "required": [ "role", "content", "tool_call_id" ] }, { "type": "object", "description": "Deprecated function message", "properties": { "role": { "type": "string", "enum": [ "function" ], "description": "The role of the messages author, in this case function" }, "content": { "type": "string", "description": "The contents of the function message" }, "name": { "type": "string", "description": "The name of the function to call" } }, "required": [ "role", "content", "name" ] } ] }, "minItems": 1 }, "model": { "type": "string", "description": "The model identifier to use for completion" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Sampling temperature between 0 and 2. Higher values make output more random." }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "description": "Nucleus sampling parameter. Consider tokens with top_p probability mass." }, "max_tokens": { "type": [ "integer", "null" ], "description": "The maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API. This value is deprecated in favor of max_completion_tokens, and is not supported by reasoning models" }, "max_completion_tokens": { "type": [ "integer", "null" ], "description": "An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens" }, "stream": { "type": [ "boolean", "null" ], "default": false, "description": "If set to true, the model response data will be streamed to the client as it is generated using server-sent events" }, "tools": { "type": "array", "description": "A list of tools the model may call. You can provide either custom tools or function tools", "items": { "oneOf": [ { "type": "object", "description": "A function tool that can be used to generate a response", "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of the tool. Currently, only function is supported" }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64" }, "description": { "type": "string", "description": "A description of what the function does, used by the model to choose when and how to call the function" }, "parameters": { "type": "object", "description": "The parameters the functions accepts, described as a JSON Schema object. Omitting parameters defines a function with an empty parameter list" } }, "required": [ "name" ] } }, "required": [ "type", "function" ] }, { "type": "object", "description": "A custom tool that processes input using a specified format", "properties": { "type": { "type": "string", "enum": [ "custom" ], "description": "The type of the custom tool. Always custom" }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "type": "string", "description": "Optional description of the custom tool, used to provide more context" }, "format": { "type": "object", "description": "The input format for the custom tool. Default is unconstrained text" } }, "required": [ "name" ], "description": "Properties of the custom tool" } }, "required": [ "type", "custom" ] } ] } }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ], "description": "none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "For function calling, the type is always function" }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function to call" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "Specifies a tool the model should use. Use to force the model to call a specific function" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ], "description": "For custom tool calling, the type is always custom" }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool to call" } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "Specifies a tool the model should use. Use to force the model to call a specific custom tool" } ], "description": "Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool forces the model to call that tool" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The type of response format being defined. Always text" } }, "required": [ "type" ], "description": "Default response format. Used to generate text responses" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ], "description": "The type of response format being defined. Always json_schema" }, "json_schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64" }, "description": { "type": "string", "description": "A description of what the response format is for, used by the model to determine how to respond in the format" }, "schema": { "type": "object", "description": "The schema for the response format, described as a JSON Schema object" }, "strict": { "type": "boolean", "default": false, "description": "Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the schema field" } }, "required": [ "name" ], "description": "Structured Outputs configuration options, including a JSON Schema" } }, "required": [ "type", "json_schema" ], "description": "JSON Schema response format. Used to generate structured JSON responses" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ], "description": "The type of response format being defined. Always json_object" } }, "required": [ "type" ], "description": "JSON object response format. An older method of generating JSON responses. Using json_schema is recommended for models that support it" } ], "description": "An object specifying the format that the model must output" }, "audio": { "type": [ "object", "null" ], "description": "Parameters for audio output. Required when audio output is requested with modalities: [\"audio\"]", "properties": { "format": { "type": "string", "enum": [ "wav", "mp3", "flac", "opus", "pcm16" ], "description": "Specifies the output audio format" }, "voice": { "type": "string", "enum": [ "alloy", "ash", "ballad", "coral", "echo", "fable", "nova", "onyx", "sage", "shimmer" ], "description": "The voice the model uses to respond" } }, "required": [ "format", "voice" ] }, "frequency_penalty": { "type": [ "number", "null" ], "default": 0, "minimum": -2, "maximum": 2, "description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim" }, "function_call": { "oneOf": [ { "type": "string", "enum": [ "none", "auto" ], "description": "none means the model will not call a function and instead generates a message. auto means the model can pick between generating a message or calling a function" }, { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function to call" } }, "required": [ "name" ], "description": "Specifying a particular function via {\"name\": \"my_function\"} forces the model to call that function" } ], "description": "Deprecated in favor of tool_choice. Controls which (if any) function is called by the model" }, "functions": { "type": "array", "description": "Deprecated in favor of tools. A list of functions the model may generate JSON inputs for", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64" }, "description": { "type": "string", "description": "A description of what the function does, used by the model to choose when and how to call the function" }, "parameters": { "type": "object", "description": "The parameters the functions accepts, described as a JSON Schema object. Omitting parameters defines a function with an empty parameter list" } }, "required": [ "name" ] } }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number", "minimum": -100, "maximum": 100 }, "description": "Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100" }, "logprobs": { "type": [ "boolean", "null" ], "default": false, "description": "Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 512 }, "maxProperties": 16, "description": "Set of 16 key-value pairs that can be attached to an object. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters" }, "modalities": { "type": "array", "description": "Output types that you would like the model to generate", "items": { "type": "string", "enum": [ "text", "audio" ] }, "default": [ "text" ] }, "n": { "type": [ "integer", "null" ], "default": 1, "minimum": 1, "description": "How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep n as 1 to minimize costs" }, "prediction": { "type": "object", "description": "Configuration for a Predicted Output, which can greatly improve response times when large parts of the model response are known ahead of time", "properties": { "type": { "type": "string", "enum": [ "content" ], "description": "The type of the predicted content you want to provide. This type is currently always content" }, "content": { "oneOf": [ { "type": "string", "description": "The content used for a Predicted Output. This is often the text of a file you are regenerating with minor changes" }, { "type": "array", "description": "An array of content parts with a defined type. Supported options differ based on the model being used to generate the response. Can contain text inputs", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The text content" }, "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part" } }, "required": [ "text", "type" ] } } ], "description": "The content that should be matched when generating a model response" } }, "required": [ "type", "content" ] }, "presence_penalty": { "type": [ "number", "null" ], "default": 0, "minimum": -2, "maximum": 2, "description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics" }, "prompt_cache_key": { "type": "string", "description": "Used to cache responses for similar requests, to improve your cache hit rate. Replaces the user field" }, "prompt_cache_retention": { "type": "string", "description": "The retention policy for the prompt cache. Set to 24h to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours" }, "reasoning_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "default": "medium", "description": "Constrains effort on reasoning for reasoning models. The valid values depend on the model family: Qwen models accept xhigh, medium, and low; DeepSeek and Kimi models accept low, high, and max; Z.ai (GLM) models accept max, xhigh, high, medium, low, minimal, and none. The proxy forwards the value to the model unchanged, so the model rejects a value it does not support. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response" }, "safety_identifier": { "type": "string", "description": "A stable identifier used to help detect users of your application that may be violating the usage policies. The ID should be a string that uniquely identifies each end user" }, "seed": { "type": [ "integer", "null" ], "description": "This feature is in Beta. If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed" }, "service_tier": { "type": "string", "enum": [ "auto", "default", "flex", "priority" ], "default": "auto", "description": "Specifies the processing type used for serving the request" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 4 }, { "type": "null" } ], "default": null, "description": "Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence. Not supported by some reasoning models" }, "store": { "type": [ "boolean", "null" ], "default": false, "description": "Whether the model provider may store the output of this chat completion request. Supports text and image inputs. Note: image inputs over 8MB are dropped" }, "stream_options": { "type": "object", "description": "Options for streaming response. Only set this when you set stream: true", "properties": { "include_obfuscation": { "type": "boolean", "description": "When true, stream obfuscation will be enabled. Stream obfuscation adds random characters to an obfuscation field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks" }, "include_usage": { "type": "boolean", "description": "If set, an additional chunk will be streamed before the data: [DONE] message. The usage field on this chunk shows the token usage statistics for the entire request" } } }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability" }, "verbosity": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "Constrains the verbosity of the model's response. Lower values will result in more concise responses, while higher values will result in more verbose responses" }, "web_search_options": { "type": "object", "description": "This tool searches the web for relevant results to use in a response", "properties": { "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "High level guidance for the amount of context window space to use for the search" }, "user_location": { "oneOf": [ { "type": "object", "properties": { "approximate": { "type": "object", "properties": { "city": { "type": "string", "description": "Free text input for the city of the user, e.g. San Francisco" }, "country": { "type": "string", "description": "The two-letter ISO country code of the user, e.g. US" }, "region": { "type": "string", "description": "Free text input for the region of the user, e.g. California" }, "timezone": { "type": "string", "description": "The IANA timezone of the user, e.g. America/Los_Angeles" } } }, "type": { "type": "string", "enum": [ "approximate" ], "description": "The type of location approximation. Always approximate" } }, "required": [ "approximate", "type" ] }, { "type": "null" } ], "description": "Approximate location parameters for the search" } } } }, "required": [ "messages", "model" ], "additionalProperties": false, "examples": [ { "messages": [ { "role": "user", "content": "Hello, how are you?" } ], "model": "openai/gpt-oss-120b", "temperature": 0.7, "stream": true }, { "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "What's the weather like?" } ], "model": "openai/gpt-oss-120b", "temperature": 0.8, "top_p": 0.9, "max_tokens": 500, "stream": true, "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get the current weather for a location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA" } }, "required": [ "location" ] } } } ], "tool_choice": "auto" } ] }, "rvencChatCompletionChunk": { "type": "object", "description": "Decrypted chat completion chunk structure that matches OpenAI's streaming format. Each encrypted chunk in the SSE stream, when decrypted, matches this structure.", "properties": { "id": { "type": "string", "description": "A unique identifier for the chat completion. Each chunk has the same id.", "examples": [ "cd9d05b657a041a6a14ab2fc890a7d7e" ] }, "object": { "type": "string", "enum": [ "chat.completion.chunk" ], "description": "The object type, which is always 'chat.completion.chunk'", "examples": [ "chat.completion.chunk" ] }, "created": { "type": "integer", "description": "The Unix timestamp (in seconds) of when the chat completion was created", "examples": [ 1764004858 ] }, "model": { "type": "string", "description": "The model used for the chat completion", "examples": [ "openai/gpt-oss-120b" ] }, "system_fingerprint": { "type": [ "string", "null" ], "description": "This fingerprint represents the backend configuration that the model runs with (optional)", "examples": [ "fp_44709d6fcb" ] }, "choices": { "type": "array", "description": "A list of chat completion choices. Can contain more than one element if n is greater than 1.", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "The index of the choice in the list of choices", "examples": [ 0 ] }, "delta": { "type": "object", "description": "A chat completion delta generated by streamed model responses. The delta can contain 'role', 'content', 'reasoning_content', 'tool_calls', or be empty {} when finish_reason is set.", "properties": { "role": { "type": [ "string", "null" ], "enum": [ "assistant", null ], "description": "The role of the author of this message (only present in first chunk, can be null)", "examples": [ "assistant" ] }, "content": { "type": [ "string", "null" ], "description": "The contents of the chunk message (can be null or empty string)", "examples": [ "Hello" ] }, "reasoning_content": { "type": [ "string", "null" ], "description": "Reasoning content for models that support reasoning (optional, can be null)", "examples": [ ":" ] }, "tool_calls": { "type": [ "array", "null" ], "description": "Tool calls made by the assistant (optional, can be null)", "items": { "type": "object" } } } }, "logprobs": { "type": [ "object", "null" ], "description": "Log probability information for the choice", "default": null }, "finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", "content_filter", null ], "description": "The reason the model stopped generating tokens. This will be null if the model hasn't finished generating the tokens yet.", "examples": [ "stop" ] }, "matched_stop": { "type": [ "string", "null" ], "description": "The stop sequence that was matched (optional, can be null)", "default": null } }, "required": [ "index", "delta", "logprobs", "finish_reason" ] } }, "usage": { "type": [ "object", "null" ], "description": "Usage statistics for the completion (optional, can be null)", "properties": { "prompt_tokens": { "type": "integer", "description": "Number of tokens in the prompt" }, "completion_tokens": { "type": "integer", "description": "Number of tokens in the completion" }, "total_tokens": { "type": "integer", "description": "Total number of tokens used" } }, "default": null }, "error": { "type": "object", "description": "Error object if an error occurred (optional)", "properties": { "message": { "type": "string", "description": "Error message" }, "type": { "type": "string", "description": "Error type" } } } }, "required": [ "id", "object", "created", "model", "choices" ], "additionalProperties": false, "examples": [ { "id": "cd9d05b657a041a6a14ab2fc890a7d7e", "object": "chat.completion.chunk", "created": 1764004858, "model": "openai/gpt-oss-120b", "choices": [ { "index": 0, "delta": { "role": null, "content": null, "reasoning_content": "This ", "tool_calls": null }, "logprobs": null, "finish_reason": null, "matched_stop": null } ], "usage": null }, { "id": "cd9d05b657a041a6a14ab2fc890a7d7e", "object": "chat.completion.chunk", "created": 1764004858, "model": "openai/gpt-oss-120b", "choices": [ { "index": 0, "delta": { "role": "assistant", "content": "Hello", "reasoning_content": null, "tool_calls": null }, "logprobs": null, "finish_reason": null, "matched_stop": null } ], "usage": null }, { "id": "cd9d05b657a041a6a14ab2fc890a7d7e", "object": "chat.completion.chunk", "created": 1764004858, "model": "openai/gpt-oss-120b", "choices": [ { "index": 0, "delta": {}, "logprobs": null, "finish_reason": "stop", "matched_stop": null } ], "usage": null } ] }, "createRvencChatCompletionResponse": { "type": "object", "description": "Server-sent events (SSE) stream response structure. The actual response is a text stream, but this schema documents the structure for reference.", "properties": { "stream": { "type": "string", "description": "Server-sent events (SSE) stream with encrypted chat completion chunks. The stream contains four types of events:\n- `event: data` followed by `data: ` - Encrypted chunk that must be decrypted using the same shared secret and nonce from the request. When decrypted, each chunk matches the structure shown in the `_decryptedChunk` property below (reference only).\n- `event: heartbeat` followed by `data: {\"message\":\"processing\",\"timestamp\":}` - Keep-alive event sent every 5 seconds while waiting for the first inference token. Not encrypted; clients should ignore it.\n- `event: error` followed by `data: ` - Error event (can be encrypted or plain JSON). Emitted when inference fails or when no inference data is received within 10 minutes.\n- `event: done` followed by `data: [DONE]` - Stream completion marker\n\nEach encrypted `data:` line contains a hex-encoded string. Decrypt each chunk using XChaCha20-Poly1305 with the shared secret and nonce from your request." }, "_decryptedChunk": { "$ref": "#/components/schemas/rvencChatCompletionChunk", "description": "**Reference only** - This shows the structure that each encrypted chunk should contain when decrypted. Decrypt each chunk in the stream using the same shared secret and nonce from your request to get this structure.", "readOnly": true } }, "required": [ "stream" ], "examples": [ { "stream": "event: data\ndata: a1b2c3d4e5f67890abcdef1234567890abcdef123456...\n\nevent: data\ndata: f6e5d4c3b2a19876543210fedcba9876543210fedcba...\n\nevent: data\ndata: 1234567890abcdef1234567890abcdef1234567890...\n\nevent: done\ndata: [DONE]" }, { "stream": "event: heartbeat\ndata: {\"message\":\"processing\",\"timestamp\":1710000000000}\n\nevent: data\ndata: a1b2c3d4e5f67890abcdef1234567890abcdef123456...\n\nevent: error\ndata: {\"error\":{\"message\":\"Error occurred\",\"type\":\"api_error\"}}\n\nevent: done\ndata: [DONE]" } ] }, "rvencChatCompletionNonStreaming": { "type": "object", "description": "Encrypted non-streaming RVENC chat completion response. Contains the encrypted completion result that must be decrypted using the shared secret derived from the request's cipherText.", "properties": { "encryptedResponse": { "type": "string", "description": "Encrypted JSON string containing the chat completion result. Decrypt using XChaCha20-Poly1305 with the shared secret (derived from cipherText) and the response nonce." }, "nonce": { "type": "string", "description": "Hex-encoded nonce used for decrypting the encryptedResponse payload." }, "usage": { "type": "object", "description": "Token usage statistics for the completion request.", "properties": { "model": { "type": "string" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } }, "required": [ "encryptedResponse", "nonce" ], "examples": [ { "encryptedResponse": "a1b2c3d4e5f67890abcdef1234567890abcdef123456789012345678901234567890abcdef", "nonce": "f6e5d4c3b2a19876543210fedcba9876", "usage": { "model": "qwen36-27b", "prompt_tokens": 10, "completion_tokens": 5, "reasoning_tokens": 0, "total_tokens": 15 } } ] }, "createRvencChatCompletionRequest": { "type": "object", "description": "Chat completion request with an end-to-end encrypted payload and the key material needed to decrypt it.", "properties": { "encryptedInference": { "type": "string", "description": "Encrypted JSON string containing all chat completion parameters. When decrypted, this string must match the structure shown in the expandable `_decryptedInference` property below (reference only - do not send this property)." }, "_decryptedInference": { "$ref": "#/components/schemas/rvencInferenceParams", "description": "**Reference only - Do NOT send this property** - This shows the structure that `encryptedInference` should contain when decrypted. Encrypt a JSON object matching this structure and send it as the `encryptedInference` string.", "readOnly": true }, "cipherText": { "type": "string", "description": "Cipher text for shared secret generation (ECDH key exchange)" }, "nonce": { "type": "string", "description": "Nonce used for encrypting the inference payload" }, "model": { "type": "string", "description": "Model identifier to use for completion" }, "stream": { "type": "boolean", "default": false, "description": "If true, returns a server-sent events stream. If false, returns JSON with `encryptedResponse` and `nonce`. May also be set inside `encryptedInference`." } }, "required": [ "encryptedInference", "cipherText", "nonce", "model" ], "additionalProperties": false, "examples": [ { "encryptedInference": "encrypted_inference_payload_data", "cipherText": "cipher_text_for_key_exchange", "nonce": "nonce_value", "model": "deepseek-v4.1-flash" } ] }, "createOpenAiChatCompletionRequest": { "type": "object", "description": "Chat completion request in the OpenAI Chat Completions format.", "properties": { "model": { "type": "string", "description": "Model name, as listed by `GET /models`." }, "messages": { "type": "array", "description": "Conversation messages.", "items": { "type": "object" } }, "stream": { "type": "boolean", "default": false, "description": "If true, the response is a server-sent events stream." }, "provider": { "type": "string", "description": "Optional. Pin the request to one of the model's configured backends. Omit to let the platform choose." } }, "required": [ "model", "messages" ], "additionalProperties": true }, "rvencAudioTranscriptionInferenceParams": { "type": "object", "description": "Structure of the JSON to encrypt and send as `encryptedInference` for audio transcription.", "properties": { "model": { "type": "string", "description": "ID of the model to use. Only openai/whisper-large-v3 is currently available.", "enum": [ "openai/whisper-large-v3" ] }, "language": { "type": "string", "description": "The language of the input audio. Supplying the input language in ISO-639-1 format will improve accuracy and latency. Optional, not applicable for openai/whisper-large-v3 models which auto-detect language.", "examples": [ "en", "es", "fr", "de", "ja", "zh" ] }, "prompt": { "type": "string", "description": "An optional text to guide the model's style or continue a previous audio segment. The prompt should match the audio language for openai/whisper-large-v3. For openai/whisper-large-v3 models, the prompt can be used to provide additional context or instructions." }, "response_format": { "type": "string", "enum": [ "json", "text", "verbose_json" ], "default": "json", "description": "The format of the output. Options: json (default), text (plain text), verbose_json (JSON with additional metadata like word timestamps)." }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "default": 0, "description": "The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit." }, "timestamp_granularities": { "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] }, "description": "The timestamp granularities to populate for this transcription. response_format must be set to verbose_json to use timestamp granularities. Either or both of these options are supported: word, or segment. Note: There is no additional latency for segment timestamps, but generating word timestamps incurs additional latency." } }, "required": [ "model" ], "additionalProperties": false, "examples": [ { "model": "openai/whisper-large-v3", "language": "en", "response_format": "json" }, { "model": "openai/whisper-large-v3", "language": "es", "prompt": "This is a conversation about technology.", "temperature": 0.2, "response_format": "text" } ] }, "rvencAudioTranslationInferenceParams": { "type": "object", "description": "Structure of the JSON to encrypt and send as `encryptedInference` for audio translation. Output is always English, whatever the input language.", "properties": { "model": { "type": "string", "description": "ID of the model to use. Only openai/whisper-large-v3 is currently available for translations.", "enum": [ "openai/whisper-large-v3" ] }, "prompt": { "type": "string", "description": "An optional text to guide the model's style or continue a previous audio segment. The prompt should be in English to match the output language." }, "response_format": { "type": "string", "enum": [ "json", "text", "verbose_json" ], "default": "json", "description": "The format of the output. Options: json (default), text (plain text), verbose_json (JSON with additional metadata)." }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "default": 0, "description": "The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit." } }, "required": [ "model" ], "additionalProperties": false, "examples": [ { "model": "openai/whisper-large-v3", "response_format": "json" }, { "model": "openai/whisper-large-v3", "prompt": "This is a technical discussion.", "temperature": 0.3, "response_format": "text" }, { "model": "openai/whisper-large-v3", "response_format": "verbose_json" } ] }, "rvencTranscriptionDecryptedResponse": { "type": "object", "description": "Decrypted audio transcription result matching OpenAI's Transcription response. When `encryptedResponse` is decrypted, it will match this structure.", "properties": { "text": { "type": "string", "description": "The transcribed text of the audio.", "examples": [ "Hello world" ] }, "task": { "type": "string", "description": "The task performed, typically 'transcribe'. (Verbose JSON only)", "examples": [ "transcribe" ] }, "language": { "type": "string", "description": "The detected or specified language. (Verbose JSON only)", "examples": [ "english" ] }, "duration": { "type": "number", "description": "The duration of the audio in seconds. (Verbose JSON only)", "examples": [ 2.5 ] }, "segments": { "type": "array", "description": "Segments of the transcribed text with timestamps. (Verbose JSON only, if requested)", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "seek": { "type": "integer" }, "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "integer" } }, "temperature": { "type": "number" }, "avg_logprob": { "type": "number" }, "compression_ratio": { "type": "number" }, "no_speech_prob": { "type": "number" } } } }, "words": { "type": "array", "description": "Word-level timestamps. (Verbose JSON only, if requested)", "items": { "type": "object", "properties": { "word": { "type": "string" }, "start": { "type": "number" }, "end": { "type": "number" } } } } }, "required": [ "text" ], "additionalProperties": false, "examples": [ { "text": "The quick brown fox jumps over the lazy dog." }, { "task": "transcribe", "language": "english", "duration": 5.2, "text": "The quick brown fox jumps over the lazy dog.", "segments": [ { "id": 0, "seek": 0, "start": 0, "end": 5.2, "text": "The quick brown fox jumps over the lazy dog.", "tokens": [ 50364, 464, 2068, 7586, 21831, 11687, 625, 262, 16931, 3290, 13, 50624 ], "temperature": 0, "avg_logprob": -0.2, "compression_ratio": 1.2, "no_speech_prob": 0.1 } ] } ] }, "rvencTranslationDecryptedResponse": { "type": "object", "description": "Decrypted audio translation result matching OpenAI's Translation response. When `encryptedResponse` is decrypted, it will match this structure.", "properties": { "text": { "type": "string", "description": "The translated text (in English).", "examples": [ "Hello world" ] }, "task": { "type": "string", "description": "The task performed, typically 'translate'. (Verbose JSON only)", "examples": [ "translate" ] }, "language": { "type": "string", "description": "The detected language of the input audio. (Verbose JSON only)", "examples": [ "spanish" ] }, "duration": { "type": "number", "description": "The duration of the audio in seconds. (Verbose JSON only)", "examples": [ 3.1 ] }, "segments": { "type": "array", "description": "Segments of the translated text with timestamps. (Verbose JSON only, if requested)", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "seek": { "type": "integer" }, "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "integer" } }, "temperature": { "type": "number" }, "avg_logprob": { "type": "number" }, "compression_ratio": { "type": "number" }, "no_speech_prob": { "type": "number" } } } } }, "required": [ "text" ], "additionalProperties": false, "examples": [ { "text": "The quick brown fox jumps over the lazy dog." }, { "task": "translate", "language": "german", "duration": 4.5, "text": "I am a Berliner.", "segments": [ { "id": 0, "seek": 0, "start": 0, "end": 4.5, "text": "I am a Berliner.", "tokens": [ 50364, 314, 716, 257, 45115, 13, 50589 ], "temperature": 0, "avg_logprob": -0.15, "compression_ratio": 1.1, "no_speech_prob": 0.05 } ] } ] }, "createRvencAudioTranscriptionRequest": { "type": "object", "description": "Audio transcription request with an end-to-end encrypted payload and the key material needed to decrypt it.", "properties": { "model": { "type": "string", "description": "Model identifier to use for transcription" }, "encryptedInference": { "type": "string", "description": "Encrypted JSON string containing all audio transcription parameters. When decrypted, this string must match the structure shown in the expandable `_decryptedInference` property below (reference only - do not send this property)." }, "_decryptedInference": { "$ref": "#/components/schemas/rvencAudioTranscriptionInferenceParams", "description": "**Reference only - Do NOT send this property** - This shows the structure that `encryptedInference` should contain when decrypted. Encrypt a JSON object matching this structure and send it as the `encryptedInference` string.", "readOnly": true }, "cipherText": { "type": "string", "description": "Cipher text for shared secret generation (ECDH key exchange)" }, "nonce": { "type": "string", "description": "Nonce used for encrypting the inference payload" }, "encryptedFileName": { "type": "string", "description": "The encrypted audio file name. The file name is encrypted using XChaCha20-Poly1305 with the shared secret and fileNameNonce." }, "fileNameNonce": { "type": "string", "description": "Nonce used for encrypting the encrypted audio file name" }, "encryptedFile": { "type": "string", "description": "The encrypted audio file data. The audio content is encrypted using XChaCha20-Poly1305 with the shared secret and fileNonce." }, "fileNonce": { "type": "string", "description": "Nonce used for encrypting the encrypted audio file" } }, "required": [ "model", "encryptedInference", "cipherText", "nonce", "fileNameNonce", "encryptedFileName", "fileNonce", "encryptedFile" ], "additionalProperties": false, "examples": [ { "model": "whisper-large-v3", "encryptedInference": "encrypted_inference_payload_data", "cipherText": "cipher_text_for_key_exchange", "nonce": "nonce_value", "fileNameNonce": "file_name_nonce_value", "encryptedFileName": "encrypted_audio_file_name_data", "fileNonce": "file_nonce_value", "encryptedFile": "encrypted_audio_file_data" } ] }, "createRvencAudioTranslationRequest": { "type": "object", "description": "Audio translation request with an end-to-end encrypted payload and the key material needed to decrypt it.", "properties": { "model": { "type": "string", "description": "Model identifier to use for translation" }, "encryptedInference": { "type": "string", "description": "Encrypted JSON string containing all audio translation parameters. When decrypted, this string must match the structure shown in the expandable `_decryptedInference` property below (reference only - do not send this property)." }, "_decryptedInference": { "$ref": "#/components/schemas/rvencAudioTranslationInferenceParams", "description": "**Reference only - Do NOT send this property** - This shows the structure that `encryptedInference` should contain when decrypted. Encrypt a JSON object matching this structure and send it as the `encryptedInference` string.", "readOnly": true }, "cipherText": { "type": "string", "description": "Cipher text for shared secret generation (ECDH key exchange)" }, "nonce": { "type": "string", "description": "Nonce used for encrypting the inference payload" }, "encryptedFileName": { "type": "string", "description": "The encrypted audio file name. The file name is encrypted using XChaCha20-Poly1305 with the shared secret and fileNameNonce." }, "fileNameNonce": { "type": "string", "description": "Nonce used for encrypting the encrypted audio file name" }, "encryptedFile": { "type": "string", "description": "The encrypted audio file data. The audio content is encrypted using XChaCha20-Poly1305 with the shared secret and fileNonce." }, "fileNonce": { "type": "string", "description": "Nonce used for encrypting the encrypted audio file" } }, "required": [ "model", "encryptedInference", "cipherText", "nonce", "fileNameNonce", "encryptedFileName", "fileNonce", "encryptedFile" ], "additionalProperties": false, "examples": [ { "model": "whisper-large-v3", "encryptedInference": "encrypted_inference_payload_data", "cipherText": "cipher_text_for_key_exchange", "nonce": "nonce_value", "fileNameNonce": "file_name_nonce_value", "encryptedFileName": "encrypted_audio_file_name_data", "fileNonce": "file_nonce_value", "encryptedFile": "encrypted_audio_file_data" } ] }, "createRvencAudioTranscriptionResponse": { "type": "object", "description": "Encrypted audio transcription response. Contains the encrypted transcription result that must be decrypted using the shared secret derived from the request's cipherText.", "properties": { "encryptedResponse": { "type": "string", "description": "Encrypted JSON string containing the transcription result. Decrypt using XChaCha20-Poly1305 with the shared secret (derived from cipherText) and the response nonce. When decrypted, the content matches the structure shown in the `_decryptedResponse` property below (reference only)." }, "nonce": { "type": "string", "description": "Hex-encoded nonce used for decrypting the encryptedResponse payload." }, "_decryptedResponse": { "$ref": "#/components/schemas/rvencTranscriptionDecryptedResponse", "description": "**Reference only - This is NOT returned in the response.** This shows the structure that `encryptedResponse` contains when decrypted. The decrypted content matches OpenAI's Transcription response structure.", "readOnly": true } }, "required": [ "encryptedResponse", "nonce" ], "examples": [ { "encryptedResponse": "a1b2c3d4e5f67890abcdef1234567890abcdef123456789012345678901234567890abcdef...", "nonce": "f6e5d4c3b2a19876543210fedcba9876" } ] }, "createRvencAudioTranslationResponse": { "type": "object", "description": "Encrypted audio translation response. Contains the encrypted translation result (always translated to English) that must be decrypted using the shared secret derived from the request's cipherText.", "properties": { "encryptedResponse": { "type": "string", "description": "Encrypted JSON string containing the translation result. Decrypt using XChaCha20-Poly1305 with the shared secret (derived from cipherText) and the response nonce. When decrypted, the content matches the structure shown in the `_decryptedResponse` property below (reference only)." }, "nonce": { "type": "string", "description": "Hex-encoded nonce used for decrypting the encryptedResponse payload." }, "_decryptedResponse": { "$ref": "#/components/schemas/rvencTranslationDecryptedResponse", "description": "**Reference only - This is NOT returned in the response.** This shows the structure that `encryptedResponse` contains when decrypted. The decrypted content matches OpenAI's Translation response structure.", "readOnly": true } }, "required": [ "encryptedResponse", "nonce" ], "examples": [ { "encryptedResponse": "b2c3d4e5f67890abcdef1234567890abcdef12345678901234567890abcdef12345678...", "nonce": "e5d4c3b2a19876543210fedcba987654" } ] }, "rvencModelsList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/rvencModel" } } }, "required": [ "data" ] }, "openAiModel": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique public model identifier (slug)" }, "object": { "type": "string", "const": "model" }, "created": { "type": [ "integer", "null" ] }, "owned_by": { "type": [ "string", "null" ] }, "model": { "type": "string", "description": "Model slug to pass in the `model` field of OpenAI-compatible chat completion requests to select this model" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/modelMetadata" }, "input_modalities": { "type": "array", "items": { "type": "string" } }, "price_config": { "type": "object" }, "regions": { "type": "array", "description": "Region codes the model can be served from for standard (OpenAI-compatible) inference.", "items": { "type": "string" } }, "requires_auth": { "type": [ "integer", "null" ] }, "usage_mode": { "type": "string" }, "visible_in_dashboard": { "type": [ "integer", "null" ] }, "likes_count": { "type": [ "integer", "null" ] }, "dislikes_count": { "type": [ "integer", "null" ] }, "total_reviews": { "type": [ "integer", "null" ] }, "rating_percent": { "type": [ "number", "null" ] } }, "required": [ "id", "metadata", "object" ] }, "openAiModelsList": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/openAiModel" } } }, "required": [ "object", "data" ] }, "listToolsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/chatsTool" } } }, "required": [ "data" ], "examples": [ { "data": [ { "name": "generateImage", "normalizedName": "Generate Image", "shortName": "Image", "description": "Generate Image through Diffusion Model" }, { "name": "webSearchTool", "normalizedName": "Web Search", "shortName": "Web", "description": "Search the web for information." }, { "name": "imageDescribeAndCaption", "normalizedName": "Image Describe and Caption", "shortName": "Image", "description": "Ability to see images (interacts with Vision Language Models)" } ] } ] }, "executeToolRequest": { "type": "object", "description": "Request body for executing a tool with encrypted parameters. The structure varies based on the tool type: simple tools, file output tools, or file input tools.", "oneOf": [ { "title": "Simple Tool Request", "description": "Request for simple tools that don't involve file I/O: webSearchTool, getTime, webPageScraperTool", "type": "object", "properties": { "cipherText": { "type": "string", "description": "Cipher text from ML-KEM encapsulation for shared secret generation" }, "encryptedParams": { "type": "string", "description": "Encrypted JSON string containing the tool parameters" }, "nonce": { "type": "string", "description": "Nonce used for encrypting the parameters payload" } }, "required": [ "cipherText", "encryptedParams", "nonce" ], "additionalProperties": false, "examples": [ { "title": "Web Search Request", "value": { "cipherText": "a1b2c3d4e5f6...", "encryptedParams": "9f8e7d6c5b4a...", "nonce": "1a2b3c4d5e6f..." } } ] }, { "title": "File Output Tool Request", "description": "Request for tools that generate files: generateImage, audioGenerateFromText, createFileForUser. Requires additional DEK encryption materials for secure file output.", "type": "object", "properties": { "cipherText": { "type": "string", "description": "Cipher text from ML-KEM encapsulation for shared secret generation" }, "encryptedParams": { "type": "string", "description": "Encrypted JSON string containing the tool parameters" }, "nonce": { "type": "string", "description": "Nonce used for encrypting the parameters payload" }, "encryptedDEK": { "type": "string", "description": "Encrypted Data Encryption Key (DEK) for file output encryption" }, "dekNonce": { "type": "string", "description": "Nonce used for encrypting the DEK" }, "wrappedDEK": { "type": "string", "description": "Wrapped Data Encryption Key for file storage to enable later file decryption" }, "kid": { "type": "string", "description": "Key identifier (SHA3-256 hash of the public key used for encryption) for file metadata storage" } }, "required": [ "cipherText", "encryptedParams", "nonce", "encryptedDEK", "dekNonce", "wrappedDEK", "kid" ], "additionalProperties": false, "examples": [ { "title": "Generate Image Request", "value": { "cipherText": "a1b2c3d4e5f6...", "encryptedParams": "9f8e7d6c5b4a...", "nonce": "1a2b3c4d5e6f...", "encryptedDEK": "7g8h9i0j1k2l...", "dekNonce": "3m4n5o6p7q8r...", "wrappedDEK": "9s0t1u2v3w4x...", "kid": "sha3_256_hash_of_public_key" } } ] }, { "title": "File Input Tool Request", "description": "Request for tools that process existing files: imageDescribeAndCaption, imageDescribeAndCaptionFallback, videoDescribeAndCaption, getPDFContent, getTextDocumentContent, transcribeAudioToText, transcribeAudioWithDiarization, audioDiarization, getSpreadsheetContent, getPowerPointContent, getDataFileContent, getFileContentOCR. Requires fileId and DEK for file decryption.", "type": "object", "properties": { "cipherText": { "type": "string", "description": "Cipher text from ML-KEM encapsulation for shared secret generation" }, "nonce": { "type": "string", "description": "Nonce used for encrypting the parameters payload" }, "fileId": { "type": "string", "description": "File ID of the encrypted file to process" }, "encryptedDEK": { "type": "string", "description": "Encrypted Data Encryption Key (DEK)" }, "dekNonce": { "type": "string", "description": "Nonce used for encrypting the DEK" }, "encryptedFileDEK": { "type": "string", "description": "Encrypted Data Encryption Key (DEK) for file decryption" }, "fileDEKNonce": { "type": "string", "description": "Nonce used for encrypting the DEK" } }, "required": [ "cipherText", "nonce", "fileId", "encryptedDEK", "dekNonce", "encryptedFileDEK", "fileDEKNonce" ], "additionalProperties": false, "examples": [ { "title": "PDF Content Request", "value": { "cipherText": "a1b2c3d4e5f6...", "nonce": "1a2b3c4d5e6f...", "fileId": "file_encrypted_019ae533-a975-7cbb-9147-4d7583a335e3", "encryptedDEK": "7g8h9i0j1k2l...", "dekNonce": "3m4n5o6p7q8r...", "encryptedFileDEK": "7g8h9i0j1k2l...", "fileDEKNonce": "3m4n5o6p7q8r..." } } ] }, { "title": "RAG Tool Request", "description": "Request for tools that perform RAG operations: searchRag. Requires additional RAG DEK encryption materials for secure search.", "type": "object", "properties": { "cipherText": { "type": "string", "description": "Cipher text from ML-KEM encapsulation for shared secret generation" }, "encryptedParams": { "type": "string", "description": "Encrypted JSON string containing the tool parameters" }, "nonce": { "type": "string", "description": "Nonce used for encrypting the parameters payload" }, "encryptedDEK": { "type": "string", "description": "Encrypted Data Encryption Key (DEK) for file output encryption" }, "dekNonce": { "type": "string", "description": "Nonce used for encrypting the DEK" }, "encryptedFileDEKs": { "type": "array", "description": "Encrypted Data Encryption Keys (DEKs) for file decryption", "items": { "type": "object", "properties": { "encryptedDEK": { "type": "string", "description": "Encrypted Data Encryption Key (DEK)" }, "nonce": { "type": "string", "description": "Nonce used for encrypting the DEK" }, "fileId": { "type": "string", "description": "File ID of the encrypted file to process" } }, "required": [ "encryptedDEK", "nonce", "fileId" ], "additionalProperties": false } }, "encryptedRagDEK": { "type": "string", "description": "Encrypted RAG Data Encryption Key (DEK) for file output encryption" }, "ragDEKNonce": { "type": "string", "description": "Nonce used for encrypting the RAG DEK" }, "encryptedRagVersion": { "type": "string", "description": "Encrypted RAG Version" }, "ragVersionNonce": { "type": "string", "description": "Nonce used for encrypting the RAG Version" } }, "required": [ "cipherText", "encryptedParams", "nonce", "encryptedDEK", "dekNonce", "encryptedFileDEKs", "encryptedRagDEK", "ragDEKNonce", "encryptedRagVersion", "ragVersionNonce" ], "additionalProperties": false, "examples": [ { "title": "RAG Search Request", "value": { "cipherText": "a1b2c3d4e5f6...", "encryptedParams": "9f8e7d6c5b4a...", "nonce": "1a2b3c4d5e6f...", "encryptedDEK": "7g8h9i0j1k2l...", "dekNonce": "3m4n5o6p7q8r...", "encryptedFileDEKs": [ { "encryptedDEK": "7g8h9i0j1k2l...", "nonce": "3m4n5o6p7q8r...", "fileId": "file_encrypted_019ae533-a975-7cbb-9147-4d7583a335e3" } ], "encryptedRagDEK": "7g8h9i0j1k2l...", "encryptedRagVersion": "7g8h9i0j1k2l...", "ragDEKNonce": "3m4n5o6p7q8r...", "ragVersionNonce": "3m4n5o6p7q8r..." } } ] } ] }, "executeToolResponse": { "type": "object", "description": "Response from tool execution. Structure varies by tool type.", "oneOf": [ { "title": "File Output Response", "description": "Response for file-producing tools (generateImage, audioGenerateFromText, createFileForUser)", "type": "object", "properties": { "fileId": { "type": "string", "description": "Unique identifier for the created file" }, "fileName": { "type": "string", "description": "Encrypted file name (decrypt using DEK)" }, "fileSize": { "type": "integer", "description": "File size in bytes" }, "handle": { "type": "string", "description": "Encrypted file handle for local access" }, "mimeType": { "type": "string", "description": "Encrypted MIME type (decrypt using DEK)" }, "s3Path": { "type": "string", "description": "Storage path for the encrypted file" }, "success": { "type": "boolean" }, "message": { "type": "string", "description": "Human-readable message about the operation" } }, "required": [ "fileId", "fileName", "fileSize", "mimeType", "s3Path", "success" ], "additionalProperties": false, "examples": [ { "fileId": "file_encrypted_gen_019ae533-a975-7cbb-9147-4d7583a335e3", "fileName": "de0b1a99cc4fcb45c1f236b2bb328015375cbe4f...", "fileSize": 1057063, "handle": "46b6fb708c5deb249130605bb16cfb98...", "mimeType": "9b7369da092f69c6efbe24d6db6501ef...", "s3Path": "agentCreatedFiles/file_encrypted_gen_019ae533-a975-7cbb-9147-4d7583a335e3.enc", "success": true, "message": "Image generated successfully and made available for download" } ] }, { "title": "Encrypted Response", "description": "Encrypted response for all non-file tools. Decrypt encryptedResponse using DEK and nonce. The _decryptedResponse property shows reference structures for each tool type.", "type": "object", "properties": { "encryptedResponse": { "type": "string", "description": "Encrypted response data. Decrypt using DEK and nonce to get the actual tool response." }, "nonce": { "type": "string", "description": "Nonce used for encryption" }, "_decryptedResponse": { "description": "**Reference only** - This shows the possible structures that encryptedResponse should contain when decrypted, depending on the tool type.", "readOnly": true, "oneOf": [ { "title": "Get Time Decrypted", "type": "object", "properties": { "now": { "type": "string", "format": "date-time", "description": "Current timestamp in ISO 8601 format" }, "timezone": { "type": "string", "description": "Requested timezone" } }, "required": [ "now", "timezone" ], "additionalProperties": false }, { "title": "Web Search Decrypted", "type": "string", "description": "Markdown formatted search results with titles, URLs, and descriptions", "examples": [ "## 1. [Latest AI News - TechCrunch](https://techcrunch.com/ai)\n\nThe latest artificial intelligence news and updates...\n\n---\n\n## 2. [AI Breakthroughs - MIT](https://mit.edu/ai)\n\nResearch breakthroughs in machine learning...\n\n---" ] }, { "title": "Web Page Scraper Decrypted", "type": "string", "description": "Web page content converted to markdown", "examples": [ "# Page Title\n\nMain content of the web page converted to markdown format..." ] }, { "title": "Image/Video Describe Decrypted", "type": "string", "description": "Text description of the image or video content", "examples": [ "The image shows a sunset over a calm ocean. The sky is painted in shades of orange, pink, and purple. Palm trees are silhouetted against the colorful sky on the left side of the frame." ] }, { "title": "PDF Content Decrypted", "type": "object", "properties": { "chunks": { "type": "array", "items": { "type": "object", "properties": { "pageContent": { "type": "string" }, "metadata": { "type": "object" } } }, "description": "Array of text chunks extracted from the PDF" } }, "required": [ "chunks" ], "additionalProperties": false }, { "title": "Text Document Content Decrypted", "type": "object", "properties": { "content": { "type": "string", "description": "Full text content of the document" }, "chunks": { "type": "array", "items": { "type": "object", "properties": { "pageContent": { "type": "string" }, "metadata": { "type": "object" } } }, "description": "Chunked content for easier processing" }, "format": { "type": "string", "description": "File format (txt, md, docx, etc.)" }, "wordCount": { "type": "integer", "description": "Approximate word count" }, "error": { "type": "string" } }, "required": [ "content", "format" ], "additionalProperties": false }, { "title": "Transcribe Audio Decrypted", "type": "object", "properties": { "text": { "type": "string", "description": "Full transcribed text" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" } } }, "description": "Timed segments of the transcription" }, "language": { "type": "string", "description": "Detected or specified language" } }, "required": [ "text" ], "additionalProperties": false }, { "title": "Transcribe with Diarization Decrypted", "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "string" }, "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" } } }, "description": "Segments with speaker labels and timestamps" }, "speakers": { "type": "array", "items": { "type": "string" }, "description": "List of identified speakers" }, "totalDuration": { "type": "number", "description": "Total audio duration in seconds" }, "totalWords": { "type": "integer", "description": "Total word count" }, "detectedLanguage": { "type": "string", "description": "Detected language" } }, "required": [ "segments", "speakers" ], "additionalProperties": false }, { "title": "OCR Decrypted", "type": "string", "description": "Extracted text from OCR processing", "examples": [ "INVOICE\n\nDate: December 4, 2025\nInvoice #: INV-001\n\nItem Qty Price\nWidget A 10 $99.00\nWidget B 5 $149.00\n\nTotal: $1,735.00" ] }, { "title": "Spreadsheet Content Decrypted", "type": "object", "properties": { "format": { "type": "string", "enum": [ "csv", "xlsx" ], "description": "Spreadsheet format" }, "data": { "type": "array", "items": { "type": "array" }, "description": "2D array of cell values (for CSV)" }, "sheets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "data": { "type": "array" }, "preview": { "type": "string" } } }, "description": "Array of sheets (for XLSX)" }, "preview": { "type": "string", "description": "Human-readable table preview" }, "rowCount": { "type": "integer" }, "columnCount": { "type": "integer" }, "error": { "type": "string" } }, "required": [ "format", "rowCount", "columnCount" ], "additionalProperties": false }, { "title": "Data File Content Decrypted", "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "xml" ], "description": "Data file format" }, "content": { "type": "string", "description": "Pretty-printed file content" }, "summary": { "type": "object", "description": "Summary of the data structure", "properties": { "type": { "type": "string" }, "length": { "type": "integer" }, "keys": { "type": "array", "items": { "type": "string" } }, "keyCount": { "type": "integer" }, "rootTag": { "type": "string" }, "elementCount": { "type": "integer" } } }, "error": { "type": "string" } }, "required": [ "format", "content" ], "additionalProperties": false }, { "title": "PowerPoint Content Decrypted", "type": "object", "properties": { "slides": { "type": "array", "items": { "type": "object", "properties": { "slideNumber": { "type": "integer" }, "text": { "type": "string" }, "notes": { "type": "string" }, "hasImages": { "type": "boolean" }, "imageCount": { "type": "integer" }, "recommendedOcr": { "type": "boolean" }, "textLength": { "type": "integer" } } }, "description": "Array of slide content" }, "totalSlides": { "type": "integer", "description": "Total number of slides" }, "format": { "type": "string", "description": "PowerPoint format (pptx, ppt, etc.)" }, "formattedContent": { "type": "string", "description": "Human-readable formatted content of all slides" }, "ocrSummary": { "type": "object", "properties": { "slidesNeedingOcr": { "type": "integer" }, "slidesWithImages": { "type": "integer" }, "slidesWithMinimalText": { "type": "integer" } } }, "error": { "type": "string" } }, "required": [ "slides", "totalSlides", "format", "formattedContent" ], "additionalProperties": false }, { "title": "Audio Diarization Decrypted", "type": "object", "properties": { "speakers": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "string" }, "segments": { "type": "array" } } }, "description": "Audio separated by speakers" } }, "required": [ "speakers" ], "additionalProperties": false }, { "title": "RAG Search Decrypted", "type": "string", "description": "Search results from user's document store", "examples": [ "Relevant document chunks matching the search query..." ] } ] } }, "required": [ "encryptedResponse", "nonce" ], "additionalProperties": false, "examples": [ { "encryptedResponse": "encrypted_data_here...", "nonce": "nonce_value_here..." } ] } ] }, "getCvmAttestationResponse": { "type": "object", "description": "Unified CVM attestation report.", "properties": { "manifest": { "type": "object", "description": "Metadata of the CVM that produced the report", "properties": { "podvm_version": { "type": "string", "description": "PodVM image version the CVM booted from", "examples": [ "1.4.0" ] }, "workload_id": { "type": "string", "description": "Workload identifier taken from the CVM init-data", "examples": [ "example-workload" ] } }, "required": [ "podvm_version", "workload_id" ], "additionalProperties": false }, "cpu": { "type": "object", "description": "CPU attestation evidence. Vendor quote internals are defined by the attestation server.", "minProperties": 1, "maxProperties": 1, "additionalProperties": true }, "gpu": { "description": "GPU attestation evidence, if any.", "oneOf": [ { "type": "string", "enum": [ "Absent" ] }, { "type": "object", "properties": { "Nvidia": { "type": "string", "description": "NVIDIA detached EAT token (JWT) bound to the CPU report" } }, "required": [ "Nvidia" ], "additionalProperties": false } ] } }, "required": [ "manifest", "cpu", "gpu" ], "additionalProperties": false } }, "requestBodies": { "createDeveloperApiKeyRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDeveloperApiKeyRequest" } } } }, "updateDeveloperApiKeyRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateDeveloperApiKeyRequest" } } } }, "listDeveloperApiKeyRequestsRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listDeveloperApiKeyRequestsRequest" } } } }, "uploadFileEncryptedRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/uploadFileEncryptedRequest" } } } }, "indexFileEncryptedRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/indexFileEncryptedRequest" } } } }, "indexResultFileEncryptedRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/indexResultFileEncryptedRequest" } } } }, "deleteIndexFileEncryptedRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteIndexFileEncryptedRequest" } } } }, "createRvencChatCompletionRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createRvencChatCompletionRequest" } } } }, "createOpenAiChatCompletionRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createOpenAiChatCompletionRequest" } } } }, "createRvencAudioTranscriptionRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createRvencAudioTranscriptionRequest" } } } }, "createRvencAudioTranslationRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createRvencAudioTranslationRequest" } } } }, "executeToolRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/executeToolRequest" } } } } }, "responses": { "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400, 401, 403, 404, 405, 409, 429, 500, 502, 503 ], "description": "Status code of the response" }, "data": { "type": [ "object", "null" ], "description": "Response data containing the requested object" }, "error": { "type": [ "string", "null" ], "examples": [ "Some error message" ], "description": "Error message of the response, human readable" }, "message": { "type": "null" }, "env": { "type": "string", "enum": [ "development", "production" ], "description": "API environment" }, "log": { "type": [ "string", "object", "null" ], "examples": [ { "request_id": "req_1234567890" }, "Some pertinent log message" ], "description": "Useful informaiton, not always present, to debug the response" }, "validator": { "type": [ "object", "array", "null" ], "examples": [ { "email": "Invalid email address", "password": "Password is required" } ], "description": "Validator response object, each key is the field name and value is the error message" }, "support_id": { "type": [ "string", "null" ], "format": "uuid", "examples": [ "req_support_01923f4e-7b2a-7c3d-9e8f-0a1b2c3d4e5f" ], "description": "Support ID linked to the response, used to identify it when talking with our team." } }, "required": [ "status", "error", "message", "env", "log", "support_id" ], "additionalProperties": false } } } }, "401": { "description": "Access token is missing or invalid", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400, 401, 403, 404, 405, 409, 429, 500, 502, 503 ], "description": "Status code of the response" }, "data": { "type": [ "object", "null" ], "description": "Response data containing the requested object" }, "error": { "type": [ "string", "null" ], "examples": [ "Some error message" ], "description": "Error message of the response, human readable" }, "message": { "type": "null" }, "env": { "type": "string", "enum": [ "development", "production" ], "description": "API environment" }, "log": { "type": [ "string", "object", "null" ], "examples": [ { "request_id": "req_1234567890" }, "Some pertinent log message" ], "description": "Useful informaiton, not always present, to debug the response" }, "validator": { "type": [ "object", "array", "null" ], "examples": [ { "email": "Invalid email address", "password": "Password is required" } ], "description": "Validator response object, each key is the field name and value is the error message" }, "support_id": { "type": [ "string", "null" ], "format": "uuid", "examples": [ "req_support_01923f4e-7b2a-7c3d-9e8f-0a1b2c3d4e5f" ], "description": "Support ID linked to the response, used to identify it when talking with our team." } }, "required": [ "status", "error", "message", "env", "log", "support_id" ], "additionalProperties": false }, { "properties": { "status": { "type": "integer", "enum": [ 401 ] } } } ] } } } }, "403": { "description": "You do not have the required permissions to access this resource", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400, 401, 403, 404, 405, 409, 429, 500, 502, 503 ], "description": "Status code of the response" }, "data": { "type": [ "object", "null" ], "description": "Response data containing the requested object" }, "error": { "type": [ "string", "null" ], "examples": [ "Some error message" ], "description": "Error message of the response, human readable" }, "message": { "type": "null" }, "env": { "type": "string", "enum": [ "development", "production" ], "description": "API environment" }, "log": { "type": [ "string", "object", "null" ], "examples": [ { "request_id": "req_1234567890" }, "Some pertinent log message" ], "description": "Useful informaiton, not always present, to debug the response" }, "validator": { "type": [ "object", "array", "null" ], "examples": [ { "email": "Invalid email address", "password": "Password is required" } ], "description": "Validator response object, each key is the field name and value is the error message" }, "support_id": { "type": [ "string", "null" ], "format": "uuid", "examples": [ "req_support_01923f4e-7b2a-7c3d-9e8f-0a1b2c3d4e5f" ], "description": "Support ID linked to the response, used to identify it when talking with our team." } }, "required": [ "status", "error", "message", "env", "log", "support_id" ], "additionalProperties": false }, { "properties": { "status": { "type": "integer", "enum": [ 403 ] } } } ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400, 401, 403, 404, 405, 409, 429, 500, 502, 503 ], "description": "Status code of the response" }, "data": { "type": [ "object", "null" ], "description": "Response data containing the requested object" }, "error": { "type": [ "string", "null" ], "examples": [ "Some error message" ], "description": "Error message of the response, human readable" }, "message": { "type": "null" }, "env": { "type": "string", "enum": [ "development", "production" ], "description": "API environment" }, "log": { "type": [ "string", "object", "null" ], "examples": [ { "request_id": "req_1234567890" }, "Some pertinent log message" ], "description": "Useful informaiton, not always present, to debug the response" }, "validator": { "type": [ "object", "array", "null" ], "examples": [ { "email": "Invalid email address", "password": "Password is required" } ], "description": "Validator response object, each key is the field name and value is the error message" }, "support_id": { "type": [ "string", "null" ], "format": "uuid", "examples": [ "req_support_01923f4e-7b2a-7c3d-9e8f-0a1b2c3d4e5f" ], "description": "Support ID linked to the response, used to identify it when talking with our team." } }, "required": [ "status", "error", "message", "env", "log", "support_id" ], "additionalProperties": false }, { "properties": { "status": { "type": "integer", "enum": [ 404 ] } } } ] } } } }, "429": { "description": "Too many requests", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, when available.", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$", "minLength": 1, "maxLength": 19 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400, 401, 403, 404, 405, 409, 429, 500, 502, 503 ], "description": "Status code of the response" }, "data": { "type": [ "object", "null" ], "description": "Response data containing the requested object" }, "error": { "type": [ "string", "null" ], "examples": [ "Some error message" ], "description": "Error message of the response, human readable" }, "message": { "type": "null" }, "env": { "type": "string", "enum": [ "development", "production" ], "description": "API environment" }, "log": { "type": [ "string", "object", "null" ], "examples": [ { "request_id": "req_1234567890" }, "Some pertinent log message" ], "description": "Useful informaiton, not always present, to debug the response" }, "validator": { "type": [ "object", "array", "null" ], "examples": [ { "email": "Invalid email address", "password": "Password is required" } ], "description": "Validator response object, each key is the field name and value is the error message" }, "support_id": { "type": [ "string", "null" ], "format": "uuid", "examples": [ "req_support_01923f4e-7b2a-7c3d-9e8f-0a1b2c3d4e5f" ], "description": "Support ID linked to the response, used to identify it when talking with our team." } }, "required": [ "status", "error", "message", "env", "log", "support_id" ], "additionalProperties": false } } } }, "502": { "description": "Upstream service failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400, 401, 403, 404, 405, 409, 429, 500, 502, 503 ], "description": "Status code of the response" }, "data": { "type": [ "object", "null" ], "description": "Response data containing the requested object" }, "error": { "type": [ "string", "null" ], "examples": [ "Some error message" ], "description": "Error message of the response, human readable" }, "message": { "type": "null" }, "env": { "type": "string", "enum": [ "development", "production" ], "description": "API environment" }, "log": { "type": [ "string", "object", "null" ], "examples": [ { "request_id": "req_1234567890" }, "Some pertinent log message" ], "description": "Useful informaiton, not always present, to debug the response" }, "validator": { "type": [ "object", "array", "null" ], "examples": [ { "email": "Invalid email address", "password": "Password is required" } ], "description": "Validator response object, each key is the field name and value is the error message" }, "support_id": { "type": [ "string", "null" ], "format": "uuid", "examples": [ "req_support_01923f4e-7b2a-7c3d-9e8f-0a1b2c3d4e5f" ], "description": "Support ID linked to the response, used to identify it when talking with our team." } }, "required": [ "status", "error", "message", "env", "log", "support_id" ], "additionalProperties": false } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400, 401, 403, 404, 405, 409, 429, 500, 502, 503 ], "description": "Status code of the response" }, "data": { "type": [ "object", "null" ], "description": "Response data containing the requested object" }, "error": { "type": [ "string", "null" ], "examples": [ "Some error message" ], "description": "Error message of the response, human readable" }, "message": { "type": "null" }, "env": { "type": "string", "enum": [ "development", "production" ], "description": "API environment" }, "log": { "type": [ "string", "object", "null" ], "examples": [ { "request_id": "req_1234567890" }, "Some pertinent log message" ], "description": "Useful informaiton, not always present, to debug the response" }, "validator": { "type": [ "object", "array", "null" ], "examples": [ { "email": "Invalid email address", "password": "Password is required" } ], "description": "Validator response object, each key is the field name and value is the error message" }, "support_id": { "type": [ "string", "null" ], "format": "uuid", "examples": [ "req_support_01923f4e-7b2a-7c3d-9e8f-0a1b2c3d4e5f" ], "description": "Support ID linked to the response, used to identify it when talking with our team." } }, "required": [ "status", "error", "message", "env", "log", "support_id" ], "additionalProperties": false } } } }, "meDeveloperApiKeyResponse": { "description": "Successful API key self-report response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/meDeveloperApiKeyResponse" } ] } } } }, "viewDeveloperApiKeyResponse": { "description": "Successful API key view response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/viewDeveloperApiKeyResponse" } ] } } } }, "createDeveloperApiKeyResponse": { "description": "Successful API key creation response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/createDeveloperApiKeyResponse" } ] } } } }, "listDeveloperApiKeyResponse": { "description": "Successful API keys list response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/listDeveloperApiKeyResponse" } ] } } } }, "updateDeveloperApiKeyResponse": { "description": "Successful API key update response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/updateDeveloperApiKeyResponse" } ] } } } }, "deleteDeveloperApiKeyResponse": { "description": "Successful API key delete response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/deleteDeveloperApiKeyResponse" } ] } } } }, "apiKeyAnalyticsResponse": { "description": "Successful API key analytics response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/apiKeyAnalyticsResponse" } ] } } } }, "listApiKeyScopesResponse": { "description": "List of available API key scopes", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/listApiKeyScopesResponse" } ] } } } }, "listDeveloperApiKeyRequestsResponse": { "description": "Successful API key requests list response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/listDeveloperApiKeyRequestsResponse" } ] } } } }, "viewDeveloperApiKeyRequestResponse": { "description": "Successful API key request view response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/viewDeveloperApiKeyRequestResponse" } ] } } } }, "uploadFileEncryptedResponse": { "description": "Encrypted file uploaded successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/uploadFileEncryptedResponse" } ] } } } }, "listFilesEncryptedResponse": { "description": "List of encrypted files retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/listFilesEncryptedResponse" } ] } } } }, "viewFileEncryptedResponse": { "description": "Encrypted file retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/viewFileEncryptedResponse" } ] } } } }, "deleteFileEncryptedResponse": { "description": "Encrypted file deleted successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/deleteFileEncryptedResponse" } ] } } } }, "indexFileEncryptedResponse": { "description": "Files indexed successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/indexFileEncryptedResponse" } ] } } } }, "indexResultFileEncryptedResponse": { "description": "RAG status updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/indexResultFileEncryptedResponse" } ] } } } }, "deleteIndexFileEncryptedResponse": { "description": "File indexes deleted successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/deleteIndexFileEncryptedResponse" } ] } } } }, "rvencModelsListResponse": { "description": "Confidential (rvenc) models list retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/rvencModelsList" } ] } } } }, "openAiModelsListResponse": { "description": "OpenAI-compatible models list retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/openAiModelsList" } } } }, "createRvencChatCompletionResponse": { "description": "RVENC chat completion response. Returns JSON when stream is false or omitted (default), or a server-sent events stream when stream is true.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/createRvencChatCompletionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/rvencChatCompletionNonStreaming" } } } }, "createRvencAudioTranscriptionResponse": { "description": "Encrypted audio transcription response. The response contains the encrypted transcription result which must be decrypted using the shared secret derived from the request's cipherText, along with the response nonce.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/createRvencAudioTranscriptionResponse" } } } ] } } } }, "createRvencAudioTranslationResponse": { "description": "Encrypted audio translation response. The response contains the encrypted translation result (always to English) which must be decrypted using the shared secret derived from the request's cipherText, along with the response nonce.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/createRvencAudioTranslationResponse" } } } ] } } } }, "listToolsResponse": { "description": "Tools list retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "$ref": "#/components/schemas/listToolsResponse" } ] } } } }, "executeToolResponse": { "description": "Tool executed successfully with encrypted response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/executeToolResponse" } } } ] } } } } }, "parameters": { "X-Queue-Timeout": { "name": "X-Queue-Timeout", "in": "header", "required": false, "description": "Maximum seconds the request may wait in the inference queue when no capacity is free (decimals allowed). `0` never queues: a saturated model answers 429 immediately. Values above the server budget (10s) are capped; the header can only shorten the wait, never extend it. Invalid values are ignored. A request that cannot be admitted in time gets 429 with `Retry-After`.", "schema": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "examples": [ "0", "2.5" ] } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Send your access token as header Authorization: Bearer {accessToken}" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Your API key that starts with sk_live or sk_test. You can create yours at go.prem.io/api-keys." }, "EnclaveCallbackAuth": { "type": "apiKey", "in": "header", "name": "X-Enclave-Secret", "description": "The shared secret for callbacks from the Prem API Enclave." } } }, "tags": [ { "name": "dev-api", "description": "Developer API endpoints" }, { "name": "Inference", "description": "OpenAI-compatible inference endpoints" } ] }