{ "openapi": "3.0.0", "info": { "title": "Devs.ai API", "version": "1.0" }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Enter your bearer token in the format **Bearer {token}**. Legacy header X-Authorization is also supported for backwards compatibility." } }, "schemas": { "ListChatsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatSummary" } } } }, "ChatSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the chat session." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the chat session was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the chat session was last updated." }, "name": { "type": "string", "description": "Name of the chat session." }, "userId": { "type": "string", "description": "Identifier of the user associated with the chat session." }, "pinPosition": { "type": "integer", "format": "int32", "description": "The position of the chat in a pinned list or similar.", "nullable": true }, "ai": { "$ref": "#/components/schemas/ChatAI" } } }, "ChatDetails": { "allOf": [ { "$ref": "#/components/schemas/ChatSummary" }, { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } } } } ] }, "ChatMessage": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the chat message." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the chat message was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the chat message was last updated." }, "content": { "type": "string", "description": "The content of the message" }, "role": { "type": "string", "description": "The role of the message sender, either user or system" } } }, "ChatAI": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the AI." }, "name": { "type": "string", "description": "Name of the AI." }, "src": { "type": "string", "description": "URL for the AI's image." }, "description": { "type": "string", "description": "Description of the AI." }, "userId": { "type": "string", "description": "Identifier of the AI's owner." }, "userName": { "type": "string", "description": "The user name of the AI's owner." } } }, "Error": { "type": "object", "required": [ "message" ], "description": "Standard error body returned by all endpoints.", "properties": { "message": { "type": "string", "description": "Human-readable error message." }, "code": { "type": "string", "description": "Machine-readable error code, e.g. VALIDATION_ERROR, INVALID_JSON, BAD_REQUEST, FORBIDDEN, NOT_FOUND, CONFLICT, INTERNAL_SERVER_ERROR. Absent on authentication and authorization failures raised by middleware, which return only a message." }, "details": { "type": "array", "description": "Per-field validation failures. Present when code is VALIDATION_ERROR.", "items": { "$ref": "#/components/schemas/ValidationErrorDetail" } } } }, "CreateApiKeyRequestDto": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "description": "Name of the API key." }, "scopes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Scopes to grant to the API key." }, "orgId": { "type": "string", "description": "Optional organization ID to create the API key in. Defaults to the caller's organization. Tenant-scoped callers may use this to create keys for users in another organization within the same tenant." }, "userId": { "type": "string", "description": "Optional user ID to create the API key for. Defaults to the caller." } } }, "ApiKeyDto": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "lastUsedAt", "orgId", "userId", "name", "scopes", "source" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the API key." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the API key was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the API key was last updated." }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "The date and time when the API key was last used." }, "orgId": { "type": "string", "description": "Organization ID associated with the API key." }, "userId": { "type": "string", "description": "User ID associated with the API key." }, "userEmail": { "type": "string", "description": "Email of the user associated with the API key. Omitted on responses that do not join the user record, such as update and reset." }, "name": { "type": "string", "description": "Name of the API key." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted to the API key." }, "source": { "$ref": "#/components/schemas/ApiKeySource" } } }, "ApiKeyWithTokenDto": { "allOf": [ { "$ref": "#/components/schemas/ApiKeyDto" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "The plaintext API key token. Returned only when a key is created and when it is reset; it cannot be retrieved afterwards." } } } ] }, "ListDataSourcesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataSource" } } } }, "DataSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the data source." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the data source was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the data source was last updated." }, "lastIndexedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "The date and time when the data source was last indexed, if applicable." }, "orgId": { "type": "string", "description": "Organization ID that owns the data source." }, "ownerUserId": { "type": "string", "description": "User ID that created the data source." }, "name": { "type": "string", "description": "Name of the data source." }, "type": { "$ref": "#/components/schemas/DataSourceType" }, "refreshPeriod": { "$ref": "#/components/schemas/DataSourceRefreshPeriod" }, "indexStatus": { "$ref": "#/components/schemas/DataSourceIndexStatus" }, "indexPercentage": { "type": "string", "description": "Percentage of the indexing process completed, if applicable." }, "data": { "type": "object", "nullable": true, "description": "Provider-specific data source configuration." }, "cite": { "type": "boolean", "description": "Whether this data source should be cited in responses." }, "orgVisible": { "type": "boolean", "description": "Whether this data source is visible to the organization." } } }, "DataSourceType": { "type": "string", "description": "The type of the data source.", "enum": [ "API", "FILE_UPLOAD", "GOOGLE_DRIVE", "ONEDRIVE", "WEB_URL", "CONFLUENCE", "JIRA", "GITHUB" ] }, "DataSourceRefreshPeriod": { "type": "string", "description": "How frequently the data source should be refreshed.", "enum": [ "NEVER", "DAILY", "WEEKLY", "MONTHLY" ] }, "DataSourceIndexStatus": { "type": "string", "description": "The indexing status of the data source.", "enum": [ "INITIALIZED", "INDEXING", "REFRESHING", "PARTIALLY_COMPLETED", "COMPLETED", "FAILED", "DELETION_REQUESTED", "DELETED", "MISSING" ] }, "AIReference": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "src": { "type": "string" } } }, "UserSummary": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string", "nullable": true } } }, "AgentDataSource": { "allOf": [ { "$ref": "#/components/schemas/DataSource" }, { "type": "object", "properties": { "hasValidCredentials": { "type": "boolean", "description": "Whether the data source has valid credentials." } } } ] }, "ListAgentDataSourcesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDataSource" } } } }, "DataSourceWithAiDetails": { "allOf": [ { "$ref": "#/components/schemas/DataSource" }, { "type": "object", "properties": { "ais": { "type": "array", "items": { "$ref": "#/components/schemas/AIReference" } }, "ownerUser": { "$ref": "#/components/schemas/UserSummary", "nullable": true } } } ] }, "PaginatedDataSourceWithAiDetailsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataSourceWithAiDetails" } }, "total": { "type": "integer" } } }, "UpdateDataSourceRequest": { "type": "object", "properties": { "refreshPeriod": { "$ref": "#/components/schemas/DataSourceRefreshPeriod" }, "cite": { "type": "boolean", "nullable": true }, "ais": { "type": "array", "items": { "type": "string" } }, "orgVisible": { "type": "boolean", "nullable": true } } }, "UpdateKnowledgeRequest": { "type": "object", "properties": { "cite": { "type": "boolean" } }, "required": [ "cite" ] }, "DataSourceKnowledgeStats": { "type": "object", "properties": { "doneCount": { "type": "integer" }, "failedCount": { "type": "integer" }, "pendingCount": { "type": "integer" }, "indexingCount": { "type": "integer" }, "totalCount": { "type": "integer" } } }, "KnowledgeIndexStatus": { "type": "string", "enum": [ "INITIALIZED", "RETRIEVING_CONTENT", "CONTENT_RETRIEVED", "DOCUMENTS_CREATED", "INDEXING", "PARTIALLY_COMPLETED", "COMPLETED", "FAILED", "DELETED" ] }, "KnowledgeOriginalContent": { "type": "object", "properties": { "contentBlobUrl": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "isContentStoredExternally": { "type": "boolean" }, "contentUrl": { "type": "string" } } }, "Knowledge": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/DataSourceType" }, "uniqueId": { "type": "string", "nullable": true }, "parentUniqueId": { "type": "string", "nullable": true }, "indexStatus": { "$ref": "#/components/schemas/KnowledgeIndexStatus" }, "documentCount": { "type": "integer", "nullable": true }, "tokenCount": { "type": "integer", "nullable": true }, "originalContent": { "$ref": "#/components/schemas/KnowledgeOriginalContent", "nullable": true }, "documentsBlobUrl": { "type": "string", "nullable": true }, "indexPercentage": { "type": "string" }, "metadata": { "type": "object", "nullable": true }, "isBlobStorageDeleted": { "type": "boolean" }, "cite": { "type": "boolean" } } }, "GetKnowledgeResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Knowledge" } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": "string" } } } } }, "WebUrlFileType": { "type": "string", "enum": [ "TEXT", "CSV", "PDF", "MARKDOWN", "DOC", "XLS" ] }, "WebUrlDataSourceInput": { "type": "object", "properties": { "url": { "type": "string" }, "dataRefreshPeriod": { "$ref": "#/components/schemas/DataSourceRefreshPeriod" }, "includeFiles": { "type": "boolean" }, "includedFileTypes": { "type": "array", "items": { "$ref": "#/components/schemas/WebUrlFileType" } }, "includeUrlGlobs": { "type": "array", "items": { "type": "string" } }, "excludeUrlGlobs": { "type": "array", "items": { "type": "string" } }, "maxPages": { "type": "integer" }, "maxMemory": { "type": "integer" }, "timeout": { "type": "integer" } }, "required": [ "url", "dataRefreshPeriod", "includeFiles", "includedFileTypes" ] }, "GoogleDriveFile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "CreateGoogleDriveKnowledgeRequest": { "type": "object", "properties": { "oauthTokenId": { "type": "string" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleDriveFile" } }, "dataRefreshPeriod": { "$ref": "#/components/schemas/DataSourceRefreshPeriod" } }, "required": [ "files" ] }, "CreateOneDriveKnowledgeRequest": { "type": "object", "properties": { "oauthTokenId": { "type": "string" }, "fileId": { "type": "string" }, "filename": { "type": "string" }, "dataRefreshPeriod": { "$ref": "#/components/schemas/DataSourceRefreshPeriod" } }, "required": [ "oauthTokenId", "fileId", "filename" ] }, "CreateConfluenceKnowledgeRequest": { "type": "object", "properties": { "oauthTokenId": { "type": "string" }, "pageId": { "type": "string" }, "pageName": { "type": "string" }, "contentType": { "type": "string" }, "spaceId": { "type": "string" }, "dataRefreshPeriod": { "$ref": "#/components/schemas/DataSourceRefreshPeriod" }, "indexChildPages": { "type": "boolean" }, "indexDriveFiles": { "type": "boolean" }, "indexAttachments": { "type": "boolean" }, "selectedDriveAccount": { "type": "string" }, "archive": { "type": "boolean" }, "allSpaces": { "type": "boolean" } }, "required": [ "oauthTokenId", "pageName" ] }, "CreateJiraKnowledgeRequest": { "type": "object", "properties": { "oauthTokenId": { "type": "string" }, "projectName": { "type": "string" }, "projectKey": { "type": "string" }, "dataRefreshPeriod": { "$ref": "#/components/schemas/DataSourceRefreshPeriod" } }, "required": [ "oauthTokenId", "projectName", "projectKey" ] }, "CreateGithubKnowledgeRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "repos", "all" ] }, "gitHubAppInstallationId": { "type": "integer" }, "repos": { "type": "array", "items": { "type": "string" } }, "dataRefreshPeriod": { "$ref": "#/components/schemas/DataSourceRefreshPeriod" } }, "required": [ "mode", "gitHubAppInstallationId" ] }, "StreamingTextResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "The streaming text response from the AI." } } }, "ListAIsRequestScope": { "type": "string", "enum": [ "PRIVATE", "OWNED", "GROUP", "SHARED", "ORGANIZATION", "PUBLIC", "ALL" ] }, "AIDetail": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "introduction": { "type": "string", "nullable": true }, "description": { "type": "string" }, "instructions": { "type": "string" }, "src": { "type": "string" }, "orgId": { "type": "string" }, "userId": { "type": "string" }, "profile": { "$ref": "#/components/schemas/AIProfile" }, "userName": { "type": "string" }, "orgName": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/AIVisibility" }, "listInOrgCatalog": { "type": "boolean" }, "listInPublicCatalog": { "type": "boolean" }, "listInTenantCatalog": { "type": "boolean" }, "chatLogsVisible": { "type": "boolean" }, "generateCitations": { "type": "boolean" }, "intermediateStepsVisible": { "type": "boolean" }, "modelId": { "type": "string" }, "options": { "$ref": "#/components/schemas/AIModelOptions" }, "groups": { "type": "array", "items": { "type": "string" } }, "editors": { "type": "array", "items": { "$ref": "#/components/schemas/AIEditorUser" } }, "publicCategories": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCategoryType" } }, "orgCategoryIds": { "type": "array", "items": { "type": "string" } }, "messageCount": { "type": "integer" }, "rating": { "type": "number" }, "ratingCount": { "type": "integer" }, "isShared": { "type": "boolean" }, "hasUserChats": { "type": "boolean" }, "isApprovedByOrg": { "type": "boolean" }, "isPremiumModel": { "type": "boolean" }, "isDeleted": { "type": "boolean" } } }, "AIProfile": { "type": "object", "properties": { "headline": { "type": "string" }, "description": { "type": "string" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/AIProfileFeature" } }, "initialSuggestedActions": { "type": "array", "description": "Suggested prompts offered at the start of a new chat.", "items": { "$ref": "#/components/schemas/AIProfileSuggestedAction" } }, "showCharacter": { "type": "boolean" }, "showTraining": { "type": "boolean" }, "showPersonality": { "type": "boolean" }, "trainingDescription": { "type": "string" }, "conversations": { "type": "array", "items": { "type": "object" } }, "socialImage": { "type": "string" }, "idleVideo": { "type": "string" }, "idleVideoError": { "type": "string" }, "showSpeaker": { "type": "boolean" }, "showVideo": { "type": "boolean" }, "voice": { "type": "string" }, "voiceEngine": { "type": "string" }, "videoModel": { "type": "string" } } }, "AIProfileFeature": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" } } }, "AIEditorUser": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "email": { "type": "string" } } }, "PublicCategoryType": { "type": "string", "enum": [ "ACCOUNTING_FINANCE", "AI_MODELS", "ENGINEERING", "HUMAN_RESOURCES", "INFORMATION_TECHNOLOGY", "LEARNING_DEVELOPMENT", "MARKETING", "PRODUCTIVITY", "SALES", "ADVISOR", "FEATURED" ] }, "GroupAvailability": { "type": "string", "enum": [ "EVERYONE", "RESTRICTED" ], "description": "Availability status of the group." }, "GroupSummary": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "orgId": { "type": "string" }, "ownerUserId": { "type": "string" }, "name": { "type": "string" }, "availability": { "$ref": "#/components/schemas/GroupAvailability" } } }, "GroupDetail": { "allOf": [ { "$ref": "#/components/schemas/GroupSummary" }, { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/GroupUser" } } } } ] }, "GroupUser": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "userId": { "type": "string", "nullable": true }, "email": { "type": "string" } } }, "OrgUsage": { "type": "object", "properties": { "orgId": { "type": "string", "description": "Unique identifier for the organization." }, "dataTokensUsed": { "type": "number", "description": "Number of data tokens used by the organization." }, "dataUsageTokenLimit": { "type": "number", "nullable": true, "description": "The data token usage limit for the organization, if any." }, "apiTokensUsed": { "type": "number", "description": "Number of API tokens used by the organization." }, "apiUsageTokenLimit": { "type": "number", "nullable": true, "description": "The API token usage limit for the organization, if any." } } }, "OrgUsageByAI": { "type": "object", "properties": { "orgUsage": { "$ref": "#/components/schemas/OrgUsage" }, "aiUsages": { "type": "array", "items": { "$ref": "#/components/schemas/AIUsage" } } } }, "AIUsage": { "type": "object", "properties": { "aiId": { "type": "string", "description": "Unique identifier for the AI instance." }, "aiDataTokensUsed": { "type": "number", "nullable": true, "description": "Number of data tokens used by this AI instance." }, "aiApiTokensUsed": { "type": "number", "nullable": true, "description": "Number of API tokens used by this AI instance." } } }, "AIVisibility": { "type": "string", "description": "Visibility level controlling who can access the AI. PRIVATE: Only the owner can access. GROUP: Only specified groups can access. ORGANIZATION: Anyone in the organization can access. ANYONE_WITH_LINK: Anyone with the link can access.", "enum": [ "PRIVATE", "GROUP", "ORGANIZATION", "ANYONE_WITH_LINK" ] }, "AIModelOptions": { "type": "object", "description": "Configuration options for the AI model's behavior", "properties": { "temperature": { "type": "array", "description": "Controls randomness in the model's output", "minItems": 1, "maxItems": 1, "items": { "type": "number" } }, "topP": { "type": "array", "description": "Controls diversity via nucleus sampling", "minItems": 1, "maxItems": 1, "items": { "type": "number" } }, "topK": { "type": "array", "description": "Controls diversity by limiting to top K tokens", "minItems": 1, "maxItems": 1, "items": { "type": "number" } }, "maxTokens": { "type": "array", "description": "Maximum number of tokens in the model's response", "minItems": 1, "maxItems": 1, "items": { "type": "number" } }, "maxInputTokens": { "type": "array", "description": "Maximum number of input tokens allowed", "minItems": 1, "maxItems": 1, "items": { "type": "number" } }, "frequencyPenalty": { "type": "array", "description": "Penalizes frequent token usage", "minItems": 1, "maxItems": 1, "items": { "type": "number" } }, "presencePenalty": { "type": "array", "description": "Penalizes new token usage", "minItems": 1, "maxItems": 1, "items": { "type": "number" } }, "reasoningEffort": { "type": "string", "description": "Reasoning effort hint for models that support it. Stored as supplied and not validated by the API." }, "reasoning": { "type": "object", "description": "Reasoning configuration for models that support it. Stored as supplied and not validated by the API.", "properties": { "enabled": { "type": "boolean" }, "parameters": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } } } } }, "AICreateRequest": { "type": "object", "description": "Request object for creating an AI configuration.", "properties": { "src": { "type": "string" }, "name": { "type": "string" }, "introduction": { "type": "string", "nullable": true }, "description": { "type": "string" }, "instructions": { "type": "string" }, "seed": { "type": "string" }, "modelId": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/AIVisibility" }, "listInOrgCatalog": { "type": "boolean" }, "listInPublicCatalog": { "type": "boolean" }, "listInTenantCatalog": { "type": "boolean" }, "generateCitations": { "type": "boolean" }, "chatLogsVisible": { "type": "boolean" }, "intermediateStepsVisible": { "type": "boolean" }, "options": { "$ref": "#/components/schemas/AIModelOptions" }, "groups": { "type": "array", "items": { "type": "string" } }, "profile": { "$ref": "#/components/schemas/AIProfile" }, "editors": { "type": "array", "items": { "$ref": "#/components/schemas/AIEditorUser" } }, "publicCategories": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCategoryType" } }, "orgCategoryIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "src", "name", "description", "instructions" ] }, "AIUpdateRequest": { "type": "object", "description": "Request object for updating an agent. This is not a sparse patch: name, description and instructions must be supplied on every call, and omitted optional fields are written as absent rather than left at their current values. Read the agent first and resend the full object to change one field. Tools, user inputs and guardrails are not part of this body; they have their own sub-resources.", "required": [ "name", "description", "instructions" ], "properties": { "src": { "type": "string" }, "name": { "type": "string" }, "introduction": { "type": "string", "nullable": true }, "description": { "type": "string" }, "instructions": { "type": "string" }, "modelId": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/AIVisibility" }, "listInOrgCatalog": { "type": "boolean" }, "listInPublicCatalog": { "type": "boolean" }, "listInTenantCatalog": { "type": "boolean" }, "generateCitations": { "type": "boolean" }, "chatLogsVisible": { "type": "boolean" }, "intermediateStepsVisible": { "type": "boolean" }, "options": { "$ref": "#/components/schemas/AIModelOptions" }, "groups": { "type": "array", "items": { "type": "string" } }, "profile": { "$ref": "#/components/schemas/AIProfile" }, "editors": { "type": "array", "items": { "$ref": "#/components/schemas/AIEditorUser" } }, "publicCategories": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCategoryType" } }, "orgCategoryIds": { "type": "array", "items": { "type": "string" } } } }, "ChatEvent": { "type": "object", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/ChatEventType" } } }, "ErrorChatEvent": { "allOf": [ { "$ref": "#/components/schemas/ChatEvent" }, { "type": "object", "required": [ "error" ], "properties": { "type": { "type": "string", "enum": [ "error" ] }, "error": { "type": "string" } } } ] }, "ToolCallChatEvent": { "allOf": [ { "$ref": "#/components/schemas/ChatEvent" }, { "type": "object", "required": [ "messageId", "calls" ], "properties": { "type": { "type": "string", "enum": [ "tool.call" ] }, "messageId": { "type": "string" }, "calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" } } } } ] }, "ToolCall": { "type": "object", "required": [ "id", "toolId", "type", "arguments" ], "properties": { "id": { "type": "string" }, "toolId": { "type": "string" }, "type": { "type": "string" }, "arguments": { "oneOf": [ { "type": "string" }, { "type": "object" } ] } } }, "ToolMessageChatEvent": { "allOf": [ { "$ref": "#/components/schemas/ChatEvent" }, { "$ref": "#/components/schemas/ToolOutput" }, { "type": "object", "required": [ "messageId", "tokenCount", "modelId" ], "properties": { "type": { "type": "string", "enum": [ "tool.message" ] }, "messageId": { "type": "string" }, "tokenCount": { "type": "number" }, "modelId": { "type": "string", "description": "The model ID that processed this tool message." }, "metadata": { "type": "object" }, "internal": { "type": "boolean" } } } ] }, "ToolOutput": { "type": "object", "required": [ "toolCallId", "output" ], "additionalProperties": false, "properties": { "toolCallId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "success", "error" ], "default": "success" }, "output": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "MessageChatEvent": { "allOf": [ { "$ref": "#/components/schemas/ChatEvent" }, { "type": "object", "required": [ "messageId" ], "properties": { "messageId": { "type": "string" }, "role": { "type": "string" } } } ] }, "MessageCreatedChatEvent": { "allOf": [ { "$ref": "#/components/schemas/MessageChatEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message.created" ] }, "internal": { "type": "boolean" } } } ] }, "MessageCompleteChatEvent": { "allOf": [ { "$ref": "#/components/schemas/MessageChatEvent" }, { "type": "object", "required": [ "estimatedInputTokens" ], "properties": { "type": { "type": "string", "enum": [ "message.complete" ] }, "estimatedInputTokens": { "type": "number", "description": "Estimated number of input tokens used." }, "inputTokens": { "type": "number", "description": "Actual number of input tokens used (if available from the model)." }, "estimatedOutputTokens": { "type": "number", "description": "Estimated number of output tokens generated." }, "outputTokens": { "type": "number", "description": "Actual number of output tokens generated (if available from the model)." }, "modelId": { "type": "string", "description": "The model ID that generated the response." } } } ] }, "MessageDeltaChatEvent": { "allOf": [ { "$ref": "#/components/schemas/MessageChatEvent" }, { "type": "object", "required": [ "content" ], "properties": { "type": { "type": "string", "enum": [ "message.delta" ] }, "content": { "$ref": "#/components/schemas/TextMessageContent" } } } ] }, "MessageErrorChatEvent": { "allOf": [ { "$ref": "#/components/schemas/MessageChatEvent" }, { "type": "object", "required": [ "error", "code" ], "properties": { "type": { "type": "string", "enum": [ "message.error" ] }, "error": { "type": "string", "description": "Human-readable error message." }, "code": { "type": "string", "enum": [ "MODEL_REQUEST_RATE_LIMIT_EXCEEDED", "MODEL_MAXIMUM_CONTEXT_EXCEEDED", "MODEL_REQUEST_ERROR", "MODEL_UNKNOWN", "CONTENT_MODERATION_TRIGGERED", "TOKEN_RATE_LIMIT_EXCEEDED", "RECURSION_LIMIT_REACHED", "UNKNOWN" ], "description": "Machine-readable error code identifying the type of error." } } } ] }, "ChatEventType": { "type": "string", "enum": [ "message.created", "message.delta", "message.complete", "message.error", "tool.call", "tool.message", "error", "flow.trace.event", "history.compressed" ], "description": "The type of chat event in the SSE stream." }, "ChatCompletionRequest": { "type": "object", "required": [ "messages", "model" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionMessage" }, "minItems": 1, "description": "A list of messages comprising the conversation so far" }, "model": { "type": "string", "description": "ID of the Devs.ai AI or the LLM model to use for completion" }, "stream": { "type": "boolean", "description": "Whether to stream the response or not", "default": false }, "options": { "$ref": "#/components/schemas/ChatOptions", "description": "Optional chat options for flow overrides and tracing" }, "tools": { "type": "array", "description": "Optional list of tools to use. Supports OpenAI function tools and Devs.ai built-in tools. Custom function tool names must be unique. Names that conflict with internal tools enabled for this specific request are rejected with HTTP 400.", "items": { "oneOf": [ { "$ref": "#/components/schemas/OpenAIFunctionTool" }, { "$ref": "#/components/schemas/BuiltInTool" }, { "$ref": "#/components/schemas/ImageGenerationTool" }, { "$ref": "#/components/schemas/McpServerTool" } ] } }, "generateCitations": { "type": "boolean", "description": "Whether to generate citations in the response" }, "parallel_tool_calls": { "type": "boolean", "description": "Whether to allow parallel tool calls" }, "stream_options": { "type": "object", "properties": { "include_usage": { "type": "boolean", "description": "Whether to include usage information in the stream" } } }, "max_tokens": { "type": "integer", "description": "Maximum number of tokens to generate" } } }, "ChatCompletionMessage": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "developer", "tool" ], "description": "The role of the message author" }, "content": { "oneOf": [ { "type": "string", "description": "The text content of the message" }, { "type": "array", "description": "Array of content parts for multimodal messages", "items": { "oneOf": [ { "$ref": "#/components/schemas/TextContentPart" }, { "$ref": "#/components/schemas/ImageUrlContentPart" } ] } } ], "nullable": true, "description": "The content of the message. Can be a string or an array of content parts for multimodal input." }, "tool_calls": { "type": "array", "description": "Tool calls made by the assistant (only present in assistant messages)", "items": { "$ref": "#/components/schemas/OpenAIToolCall" } }, "tool_call_id": { "type": "string", "description": "The ID of the tool call this message is responding to (only present in tool messages)" } } }, "TextContentPart": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } } }, "ImageUrlContentPart": { "type": "object", "required": [ "type", "image_url" ], "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the image or a base64-encoded image" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ], "description": "The detail level of the image" } } } } }, "OpenAIToolCall": { "type": "object", "required": [ "id", "type", "function" ], "properties": { "id": { "type": "string", "description": "The ID of the tool call" }, "type": { "type": "string", "enum": [ "function" ], "description": "The type of tool call" }, "function": { "type": "object", "required": [ "name", "arguments" ], "properties": { "name": { "type": "string", "description": "The name of the function to call" }, "arguments": { "type": "string", "description": "The arguments to pass to the function as a JSON string" } } } } }, "OpenAIFunctionTool": { "type": "object", "required": [ "type", "function" ], "description": "OpenAI-compatible function tool definition", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the function. Must be unique and must not conflict with internal tools enabled for this specific request." }, "description": { "type": "string", "description": "A description of what the function does" }, "parameters": { "type": "object", "description": "The parameters the function accepts, described as a JSON Schema object" } } } } }, "BuiltInTool": { "type": "object", "required": [ "type" ], "description": "Devs.ai built-in tool", "properties": { "type": { "type": "string", "enum": [ "web_search", "python", "spreadsheet", "memory", "sandbox" ], "description": "The type of built-in tool to enable" } } }, "ImageGenerationTool": { "type": "object", "required": [ "type", "modelId" ], "description": "Image generation tool configuration", "properties": { "type": { "type": "string", "enum": [ "image_generation" ] }, "modelId": { "type": "string", "description": "The ID of the image generation model to use" }, "samples": { "type": "integer", "description": "Number of images to generate" }, "size": { "type": "string", "description": "Size of the generated image (e.g., '1024x1024')" }, "aspectRatio": { "type": "string", "description": "Aspect ratio of the generated image" }, "quality": { "type": "string", "description": "Quality of the generated image" }, "style": { "type": "string", "description": "Style of the generated image" } } }, "McpServerTool": { "type": "object", "required": [ "type", "toolId" ], "description": "MCP (Model Context Protocol) server tool", "properties": { "type": { "type": "string", "enum": [ "mcp_server" ] }, "toolId": { "type": "string", "description": "The ID of the MCP tool to use" } } }, "ChatCompletionResponse": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "The index of the choice in the array." }, "message": { "type": "object", "properties": { "role": { "type": "string", "description": "The role of the message author.", "enum": [ "assistant" ] }, "content": { "type": "string", "description": "The content of the message." } } }, "finish_reason": { "type": "string", "description": "The reason why the chat completion finished.", "enum": [ "stop" ] } } } }, "chatId": { "type": "string", "description": "The ID of the chat session." } } }, "FileDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the file." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the file was created." }, "source": { "$ref": "#/components/schemas/FileSource" }, "filename": { "type": "string", "description": "The name of the file." }, "size": { "type": "integer", "description": "The size of the file in bytes." }, "mimeType": { "type": "string", "description": "The MIME type of the file." }, "url": { "type": "string", "nullable": true, "description": "The URL where the file can be accessed." }, "metadata": { "type": "object", "nullable": true, "description": "Additional metadata associated with the file." }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "The date and time when the file was deleted, if applicable." }, "status": { "$ref": "#/components/schemas/FileStatus" } } }, "FileSource": { "type": "string", "description": "The source of the file.", "enum": [ "USER", "SYSTEM" ] }, "FileStatus": { "type": "string", "description": "The status of the file.", "enum": [ "UPLOADED", "UPLOADING", "DELETING", "DELETED" ] }, "FilesResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FileDto" } } } }, "CreateFileRequestDto": { "type": "object", "required": [ "filename", "size", "mimeType" ], "properties": { "filename": { "type": "string", "description": "The name of the file." }, "size": { "type": "integer", "description": "The size of the file in bytes." }, "mimeType": { "type": "string", "description": "The MIME type of the file." }, "metadata": { "type": "object", "nullable": true, "description": "Additional metadata associated with the file." } } }, "MessageContentType": { "type": "string", "enum": [ "text", "image", "audio", "video", "document" ] }, "FileMessageContentType": { "type": "string", "description": "Content types for file references only (excludes text)", "enum": [ "image", "audio", "video", "document" ] }, "TextMessageContent": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "The text content." }, "invisible": { "type": "boolean", "description": "Whether this content is invisible to the user." }, "metadata": { "type": "object", "description": "Additional metadata." } } }, "IdMessageContent": { "type": "object", "required": [ "type", "id" ], "description": "A file reference using the file ID.", "properties": { "type": { "$ref": "#/components/schemas/FileMessageContentType" }, "id": { "type": "string", "description": "The ID of the file to include in the message." }, "invisible": { "type": "boolean", "description": "Whether this content is invisible to the user." }, "metadata": { "type": "object", "description": "Additional metadata for the file." } } }, "UrlMessageContent": { "type": "object", "required": [ "type", "url", "mimeType" ], "description": "A file reference using a URL.", "properties": { "type": { "$ref": "#/components/schemas/FileMessageContentType" }, "url": { "type": "string", "description": "The URL of the file." }, "mimeType": { "type": "string", "description": "The MIME type of the file." }, "invisible": { "type": "boolean", "description": "Whether this content is invisible to the user." }, "metadata": { "type": "object", "description": "Additional metadata for the file." } } }, "ComplexMessageContent": { "type": "array", "description": "An array of message content items, which can include text and file references. This allows sending multimodal messages with images, documents, audio, and video along with text. First upload files using /api/v1/chats/{chatId}/files, then reference them by ID in your message.", "items": { "oneOf": [ { "$ref": "#/components/schemas/TextMessageContent" }, { "$ref": "#/components/schemas/IdMessageContent" }, { "$ref": "#/components/schemas/UrlMessageContent" } ] }, "example": [ { "type": "text", "text": "What's in this image?" }, { "type": "image", "id": "file_abc123", "metadata": { "detail": "high", "width": 1024, "height": 768 } } ] }, "SubmitToolOutputRequest": { "type": "object", "required": [ "systemMessageId", "outputs" ], "properties": { "systemMessageId": { "type": "string", "description": "The ID of the system message that requested the tool outputs (the message containing the tool calls)." }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/ToolOutput" }, "description": "Array of tool outputs, one for each tool call that needs a response." }, "options": { "$ref": "#/components/schemas/ChatOptions", "description": "Optional chat options for flow overrides." } } }, "PostToChatRequestTool": { "oneOf": [ { "$ref": "#/components/schemas/BuiltInToolRequest" }, { "$ref": "#/components/schemas/ImageGenerationToolRequest" }, { "$ref": "#/components/schemas/McpServerToolRequest" }, { "$ref": "#/components/schemas/OpenAIFunctionToolRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "web_search": "#/components/schemas/BuiltInToolRequest", "python": "#/components/schemas/BuiltInToolRequest", "spreadsheet": "#/components/schemas/BuiltInToolRequest", "memory": "#/components/schemas/BuiltInToolRequest", "sandbox": "#/components/schemas/BuiltInToolRequest", "image_generation": "#/components/schemas/ImageGenerationToolRequest", "mcp_server": "#/components/schemas/McpServerToolRequest", "function": "#/components/schemas/OpenAIFunctionToolRequest" } }, "description": "A tool to enable for the chat request. Discriminated by the `type` field." }, "BuiltInToolRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search", "python", "spreadsheet", "memory", "sandbox" ], "description": "The built-in tool type to enable." } }, "description": "Enables a built-in server-side tool by type." }, "ImageGenerationToolRequest": { "type": "object", "required": [ "type", "modelId" ], "properties": { "type": { "type": "string", "enum": [ "image_generation" ], "description": "Must be 'image_generation'." }, "modelId": { "type": "string", "description": "The image generation model to use (e.g. 'dall-e-3', 'stable-diffusion-xl')." }, "samples": { "type": "integer", "description": "Number of images to generate." }, "size": { "type": "string", "description": "Image size (e.g. '1024x1024', '1792x1024')." }, "aspectRatio": { "type": "string", "description": "Aspect ratio (e.g. '16:9', '1:1'). Alternative to size for models that support it." }, "quality": { "type": "string", "description": "Image quality (e.g. 'standard', 'hd')." }, "style": { "type": "string", "description": "Image style (e.g. 'vivid', 'natural')." } }, "description": "Enables the image generation tool with model-specific configuration." }, "McpServerToolRequest": { "type": "object", "required": [ "type", "toolId" ], "properties": { "type": { "type": "string", "enum": [ "mcp_server" ], "description": "Must be 'mcp_server'." }, "toolId": { "type": "string", "description": "The ID of the MCP server tool to enable. Must be a valid CUID referencing an existing MCP tool." } }, "description": "Enables a specific MCP (Model Context Protocol) server tool by its ID." }, "OpenAIFunctionToolRequest": { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "Must be 'function'." }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the function. Must be unique among all tools in the request and must not conflict with internal tools enabled for this specific request." }, "description": { "type": "string", "description": "A description of what the function does. Helps the AI decide when to call it." }, "parameters": { "type": "object", "additionalProperties": true, "description": "The function's parameters described as a JSON Schema object. The AI uses this schema to generate the correct arguments when calling the function." } } } }, "description": "Defines an OpenAI-compatible function tool. The AI may choose to call this function, but the server does not execute it. Instead, the tool call is returned to the client via a tool.call SSE event for client-side execution. Use the submit tool outputs endpoint to return the result." }, "ChatOptions": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "override": { "type": "object", "properties": { "force": { "type": "boolean" }, "id": { "type": "string" }, "version": { "type": "number" } } }, "tracing": { "type": "object", "properties": { "enabled": { "type": "boolean" } } } } } } }, "FlowOptions": { "type": "object", "properties": { "override": { "$ref": "#/components/schemas/FlowOverrideOptions" }, "tracing": { "$ref": "#/components/schemas/FlowTracingOptions" } } }, "FlowTracingOptions": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether flow tracing is enabled." } } }, "FlowOverrideOptions": { "type": "object", "required": [ "force", "id", "version" ], "properties": { "force": { "type": "boolean", "description": "If true, only the flow identified by the id field will be selected." }, "id": { "type": "string", "description": "The flow ID to use." }, "version": { "type": "integer", "description": "The version of the flow to use." } } }, "ToolType": { "type": "string", "enum": [ "API_FUNCTION", "SQL", "PYTHON", "USER_INPUT", "KNOWLEDGE_RETRIEVAL", "WEB_SEARCH", "MCP_SERVER", "IMAGE_GENERATION", "USER_CONTEXT", "SPREADSHEET", "BROWSER", "SANDBOX", "OPENAI_FUNCTION" ] }, "AuthenticationType": { "type": "string", "enum": [ "NONE", "API_KEY", "OAUTH" ] }, "ApiKeyAuthType": { "type": "string", "enum": [ "BASIC", "BEARER", "CUSTOM" ] }, "OAuthTokenExchangeMethod": { "type": "string", "enum": [ "POST", "AUTHORIZATION_HEADER" ] }, "CustomHeader": { "type": "object", "properties": { "header": { "type": "string" }, "value": { "type": "string" } }, "required": [ "header", "value" ] }, "ApiKeyAuthenticationData": { "type": "object", "properties": { "apiKey": { "type": "string" }, "apiKeyAuthType": { "$ref": "#/components/schemas/ApiKeyAuthType" }, "customHeader": { "type": "array", "items": { "$ref": "#/components/schemas/CustomHeader" } } } }, "OAuthAuthenticationData": { "type": "object", "properties": { "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "authorizationUrl": { "type": "string" }, "tokenUrl": { "type": "string" }, "scopes": { "type": "string" }, "tokenExchangeMethod": { "$ref": "#/components/schemas/OAuthTokenExchangeMethod" } }, "required": [ "clientId", "clientSecret", "tokenUrl", "scopes", "tokenExchangeMethod" ] }, "ApiCompressionConfiguration": { "type": "object", "properties": { "compressionModel": { "type": "string" }, "compressionThreshold": { "type": "integer" }, "compressionChunkSize": { "type": "integer" } } }, "Tool": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "orgId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/ToolType" }, "data": { "type": "object" }, "orgTemplateUuid": { "type": "string" }, "orgTemplateConfig": { "type": "object" }, "templateConfig": { "type": "object" } } }, "ToolListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } }, "SQLToolDatabaseType": { "type": "string", "enum": [ "MYSQL" ] }, "CreateApiToolRequest": { "type": "object", "properties": { "apiUrl": { "type": "string" }, "schema": { "type": "string" }, "authenticationType": { "$ref": "#/components/schemas/AuthenticationType" }, "authenticationData": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyAuthenticationData" }, { "$ref": "#/components/schemas/OAuthAuthenticationData" } ] }, "compressionEnabled": { "type": "boolean" }, "compressionConfiguration": { "$ref": "#/components/schemas/ApiCompressionConfiguration" } }, "required": [ "apiUrl", "schema", "authenticationType", "compressionEnabled" ] }, "UpdateApiToolRequest": { "allOf": [ { "$ref": "#/components/schemas/CreateApiToolRequest" } ] }, "CreateUserInputToolRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "USER_INPUT" ] }, "textInput": { "type": "boolean" }, "selectInput": { "type": "boolean" }, "multiSelectInput": { "type": "boolean" }, "confirmInput": { "type": "boolean" }, "addressInput": { "type": "boolean" } }, "required": [ "type", "textInput", "selectInput", "multiSelectInput", "confirmInput", "addressInput" ] }, "UpdateUserInputToolRequest": { "type": "object", "properties": { "textInput": { "type": "boolean" }, "selectInput": { "type": "boolean" }, "multiSelectInput": { "type": "boolean" }, "confirmInput": { "type": "boolean" }, "addressInput": { "type": "boolean" } }, "required": [ "textInput", "selectInput", "multiSelectInput", "confirmInput", "addressInput" ] }, "CreateKnowledgeRetrievalToolRequest": { "type": "object", "properties": { "model": { "type": "string" }, "maxRetrievalTokens": { "type": "integer" }, "maxRetrievalDocuments": { "type": "integer" }, "queryExpansion": { "type": "boolean" }, "alternateQueryCount": { "type": "integer" }, "hyde": { "type": "boolean" }, "rerank": { "type": "boolean" }, "grade": { "type": "boolean" }, "compress": { "type": "boolean" }, "minRelevanceScore": { "type": "number" } }, "required": [ "model", "maxRetrievalTokens", "maxRetrievalDocuments", "queryExpansion", "alternateQueryCount", "hyde", "rerank", "grade", "compress", "minRelevanceScore" ] }, "UpdateKnowledgeRetrievalToolRequest": { "allOf": [ { "$ref": "#/components/schemas/CreateKnowledgeRetrievalToolRequest" } ] }, "CreateWebSearchToolRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "WEB_SEARCH" ] }, "modelId": { "type": "string" } }, "required": [ "type" ] }, "UpdateWebSearchToolRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "WEB_SEARCH" ] }, "modelId": { "type": "string" } }, "required": [ "type" ] }, "CreateImageGenerationToolRequest": { "type": "object", "properties": { "modelId": { "type": "string" }, "samples": { "type": "integer" }, "size": { "type": "string" }, "aspectRatio": { "type": "string" }, "quality": { "type": "string" }, "style": { "type": "string" } }, "required": [ "modelId" ] }, "UpdateImageGenerationToolRequest": { "allOf": [ { "$ref": "#/components/schemas/CreateImageGenerationToolRequest" } ] }, "CreateSpreadsheetToolRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SPREADSHEET" ] }, "model": { "type": "string" } }, "required": [ "type", "model" ] }, "UpdateSpreadsheetToolRequest": { "type": "object", "properties": { "model": { "type": "string" } }, "required": [ "model" ] }, "MCPTool": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "string" } } }, "CreateMcpServerToolRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "MCP_SERVER" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "orgToolTemplateId": { "type": "string" }, "authenticationType": { "$ref": "#/components/schemas/AuthenticationType" }, "authenticationData": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyAuthenticationData" }, { "$ref": "#/components/schemas/OAuthAuthenticationData" } ] }, "allTools": { "type": "array", "items": { "$ref": "#/components/schemas/MCPTool" } }, "selectedTools": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "name" ] }, "UpdateMcpServerToolRequest": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "orgToolTemplateId": { "type": "string" }, "authenticationType": { "$ref": "#/components/schemas/AuthenticationType" }, "authenticationData": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyAuthenticationData" }, { "$ref": "#/components/schemas/OAuthAuthenticationData" } ] }, "allTools": { "type": "array", "items": { "$ref": "#/components/schemas/MCPTool" } }, "selectedTools": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ] }, "PreviewMcpServerToolRequest": { "type": "object", "properties": { "url": { "type": "string" }, "orgToolTemplateId": { "type": "string" }, "toolTemplateId": { "type": "string" }, "toolId": { "type": "string" }, "authenticationType": { "$ref": "#/components/schemas/AuthenticationType" }, "authenticationData": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyAuthenticationData" }, { "$ref": "#/components/schemas/OAuthAuthenticationData" } ] } } }, "PreviewMcpServerToolResponse": { "type": "object", "properties": { "availableTools": { "type": "array", "items": { "$ref": "#/components/schemas/MCPTool" } }, "authenticationRequired": { "type": "boolean" }, "oauthDiscovery": { "type": "object" }, "requiresToolSave": { "type": "boolean" } } }, "ToolOAuthStatus": { "type": "object", "properties": { "hasToken": { "type": "boolean" }, "scopes": { "type": "string" } } }, "AIUserInputType": { "type": "string", "enum": [ "SHORT_TEXT", "LONG_TEXT", "TEXT_CHOICE", "IMAGE_CHOICE", "DATE", "NUMBER", "PHONE_NUMBER", "FILE_UPLOAD", "DISPLAY", "ADDRESS" ] }, "AIUserInput": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "aiId": { "type": "string" }, "variableName": { "type": "string" }, "type": { "$ref": "#/components/schemas/AIUserInputType" }, "label": { "type": "string" }, "configuration": { "type": "object" }, "showOnChatCreate": { "type": "boolean" }, "orderIndex": { "type": "integer" } } }, "ListAIUserInputsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AIUserInput" } } } }, "CreateAIUserInputRequest": { "type": "object", "properties": { "variableName": { "type": "string" }, "type": { "$ref": "#/components/schemas/AIUserInputType" }, "label": { "type": "string" }, "configuration": { "type": "object" }, "showOnChatCreate": { "type": "boolean" }, "orderIndex": { "type": "integer" } }, "required": [ "variableName", "type", "label", "configuration" ] }, "UpdateAIUserInputRequest": { "allOf": [ { "$ref": "#/components/schemas/CreateAIUserInputRequest" } ] }, "AIUserInputOrderItem": { "type": "object", "properties": { "id": { "type": "string" }, "orderIndex": { "type": "integer" } }, "required": [ "id", "orderIndex" ] }, "UpdateAIUserInputsOrderRequest": { "type": "object", "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/AIUserInputOrderItem" } } }, "required": [ "inputs" ] }, "UpdateAIUserInputsOrderResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "EmbeddedClientConfig": { "type": "object", "properties": { "hostUrl": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "headerBackgroundColor": { "type": "string" }, "borderColor": { "type": "string" }, "shadowColor": { "type": "string" }, "iconColor": { "type": "string" }, "textColor": { "type": "string" }, "linkColor": { "type": "string" }, "aiMessageColor": { "type": "string" }, "humanMessageColor": { "type": "string" }, "buttonColor": { "type": "string" }, "buttonTextColor": { "type": "string" }, "borderRadius": { "type": "integer" }, "buttonImageUrl": { "type": "string" }, "buttonWidth": { "type": "integer" }, "buttonHeight": { "type": "integer" }, "buttonBackgroundColor": { "type": "string" }, "buttonBorderColor": { "type": "string" }, "buttonShadowColor": { "type": "string" }, "buttonBorderRadius": { "type": "integer" }, "buttonBorderWidth": { "type": "integer" }, "buttonPosition": { "type": "string" }, "buttonPositionX": { "type": "integer" }, "buttonPositionY": { "type": "integer" }, "backgroundColor": { "type": "string" }, "disableAutoFocus": { "type": "boolean" } } }, "EmbeddedClient": { "type": "object", "properties": { "id": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "userId": { "type": "string" }, "orgId": { "type": "string" }, "aiId": { "type": "string" }, "key": { "type": "string" }, "data": { "$ref": "#/components/schemas/EmbeddedClientConfig" } } }, "Secret": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "data": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateSecretRequest": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "data": { "type": "string" }, "aiId": { "type": "string" } }, "required": [ "name", "description" ] }, "UpdateSecretRequest": { "type": "object", "properties": { "description": { "type": "string" }, "data": { "type": "string" } } }, "OAuthTokenProvider": { "type": "string", "enum": [ "GOOGLE", "MSFT", "CONFLUENCE", "JIRA", "GITHUB" ] }, "OAuthTokenStatus": { "type": "string", "enum": [ "PENDING", "ACTIVE", "EXPIRED", "REVOKED" ] }, "UserOAuthToken": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "type": "string" }, "userId": { "type": "string" }, "provider": { "$ref": "#/components/schemas/OAuthTokenProvider" }, "externalId": { "type": "string" }, "label": { "type": "string" }, "data": { "type": "object" }, "metadata": { "type": "object" }, "status": { "$ref": "#/components/schemas/OAuthTokenStatus" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "issuedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "refreshExpiresAt": { "type": "string", "format": "date-time" } } }, "GitHubAppInstallation": { "type": "object", "properties": { "id": { "type": "integer" }, "installationId": { "type": "string" }, "targetId": { "type": "string" }, "targetType": { "type": "string" }, "targetLabel": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "GitHubAppInstallationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GitHubAppInstallation" } } } }, "ExternalGitHubRepository": { "type": "object", "properties": { "id": { "type": "integer" }, "node_id": { "type": "string" }, "name": { "type": "string" }, "private": { "type": "boolean" } } }, "PaginatedExternalGitHubRepositoryResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalGitHubRepository" } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": "string" } } } } }, "GithubFile": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "sha": { "type": "string" }, "size": { "type": "integer" }, "url": { "type": "string" }, "html_url": { "type": "string" }, "git_url": { "type": "string" }, "download_url": { "type": "string", "nullable": true }, "type": { "type": "string" }, "owner": { "type": "string" }, "repo": { "type": "string" }, "content": { "type": "string" } } }, "GitHubPreviewResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GithubFile" } } } }, "AIModel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "modelFamily": { "type": "string" }, "releaseDate": { "type": "string" }, "externalModelId": { "type": "string" }, "contextSize": { "type": "integer" }, "options": { "type": "object" }, "isVisible": { "type": "boolean" }, "creator": { "type": "string" }, "provider": { "type": "string" }, "isPrivate": { "type": "boolean" }, "usageTier": { "type": "string" }, "isDisabled": { "type": "boolean" }, "capabilities": { "type": "object" }, "benchmarks": { "type": "object" } } }, "AIModelListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AIModel" } } } }, "ShareAIRequest": { "type": "object", "properties": { "emails": { "type": "string" } }, "required": [ "emails" ] }, "AgentBundleSecretDescriptor": { "type": "object", "description": "Describes a secret stripped during export. Keys map to credential fields in the import request.", "properties": { "key": { "type": "string", "description": "Secret key in the format tool:::." }, "description": { "type": "string", "description": "Human-readable label for the credential field." }, "secretType": { "type": "string", "enum": [ "apiKey", "password", "clientId", "clientSecret", "header", "custom" ] } }, "required": [ "key", "description", "secretType" ] }, "AgentBundleAgentConfig": { "type": "object", "description": "Portable agent configuration included in an export bundle.", "properties": { "name": { "type": "string" }, "introduction": { "type": "string", "nullable": true }, "description": { "type": "string" }, "instructions": { "type": "string" }, "seed": { "type": "string", "description": "Legacy field from older exports. Merged into instructions on import." }, "src": { "type": "string" }, "modelId": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/AIVisibility" }, "listInOrgCatalog": { "type": "boolean" }, "listInPublicCatalog": { "type": "boolean" }, "listInTenantCatalog": { "type": "boolean" }, "chatLogsVisible": { "type": "boolean" }, "generateCitations": { "type": "boolean" }, "intermediateStepsVisible": { "type": "boolean" }, "options": { "$ref": "#/components/schemas/AIModelOptions", "nullable": true }, "profile": { "$ref": "#/components/schemas/AIProfile", "nullable": true } }, "required": [ "name", "introduction", "description", "instructions", "src", "modelId", "visibility", "listInOrgCatalog", "listInPublicCatalog", "listInTenantCatalog", "chatLogsVisible", "generateCitations", "intermediateStepsVisible", "options", "profile" ] }, "AgentBundleToolConfig": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/ToolType" }, "data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Tool configuration with secrets stripped." } }, "required": [ "name", "type", "data" ] }, "AgentBundleUserInputConfig": { "type": "object", "properties": { "variableName": { "type": "string" }, "type": { "$ref": "#/components/schemas/AIUserInputType" }, "label": { "type": "string" }, "configuration": { "type": "object", "additionalProperties": true }, "showOnChatCreate": { "type": "boolean" }, "orderIndex": { "type": "integer" } }, "required": [ "variableName", "type", "label", "configuration", "showOnChatCreate", "orderIndex" ] }, "AgentBundleFlowVersionConfig": { "type": "object", "properties": { "version": { "type": "integer" }, "active": { "type": "boolean" }, "description": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "version", "active", "description", "data" ] }, "AgentBundleFlowConfig": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBundleFlowVersionConfig" } } }, "required": [ "name", "enabled", "versions" ] }, "AgentBundleKnowledgeItemConfig": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "uniqueId": { "type": "string", "nullable": true }, "blobUrl": { "type": "string", "nullable": true }, "filename": { "type": "string", "nullable": true }, "mimeType": { "type": "string", "nullable": true } }, "required": [ "name", "type", "uniqueId", "blobUrl", "filename", "mimeType" ] }, "AgentBundleSkillConfig": { "type": "object", "properties": { "name": { "type": "string", "description": "Skill slug: lowercase alphanumeric characters, hyphens, and underscores." }, "description": { "type": "string" }, "content": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "name", "description", "content", "enabled" ] }, "AgentBundleDataSourceConfig": { "type": "object", "properties": { "originalId": { "type": "string", "description": "Original data source ID from the export environment, used for same-environment relink on import." }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/DataSourceType" }, "refreshPeriod": { "$ref": "#/components/schemas/DataSourceRefreshPeriod" }, "data": { "type": "object", "additionalProperties": true, "nullable": true }, "knowledgeItems": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBundleKnowledgeItemConfig" } } }, "required": [ "originalId", "name", "type", "refreshPeriod", "data", "knowledgeItems" ] }, "AgentBundle": { "type": "object", "description": "Portable agent definition for export and import. Secrets are stripped from tool data and listed in requiredSecrets.", "properties": { "version": { "type": "string", "enum": [ "1.0" ] }, "exportedAt": { "type": "string", "format": "date-time" }, "source": { "type": "object", "properties": { "apiBaseUrl": { "type": "string" }, "orgId": { "type": "string" } }, "required": [ "apiBaseUrl", "orgId" ] }, "agent": { "$ref": "#/components/schemas/AgentBundleAgentConfig" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBundleToolConfig" } }, "userInputs": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBundleUserInputConfig" } }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBundleFlowConfig" } }, "dataSources": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBundleDataSourceConfig" } }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBundleSkillConfig" } }, "requiredSecrets": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBundleSecretDescriptor" } } }, "required": [ "version", "exportedAt", "source", "agent", "tools", "userInputs", "flows", "dataSources", "skills", "requiredSecrets" ] }, "ImportAgentRequest": { "type": "object", "properties": { "bundle": { "$ref": "#/components/schemas/AgentBundle" }, "name": { "type": "string", "description": "Optional override for the imported agent name." }, "secrets": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Credential values keyed by requiredSecrets entries." } }, "required": [ "bundle" ] }, "ImportAgentResponse": { "type": "object", "properties": { "aiId": { "type": "string", "description": "Identifier of the newly created agent." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues encountered during import, such as model substitution or skipped skills." } }, "required": [ "aiId", "warnings" ] }, "DeleteAIDataSourcesRequest": { "type": "object", "properties": { "dataSourceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "dataSourceIds" ] }, "CreateAIDataSourceResponse": { "type": "object", "properties": { "aiId": { "type": "string" }, "dataSourceId": { "type": "string" } }, "required": [ "aiId", "dataSourceId" ] }, "TenantCategory": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer" }, "isActive": { "type": "boolean" }, "parentCategoryId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OrgToolTemplate": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "type": "string" }, "name": { "type": "string" }, "templateId": { "type": "string" }, "isEnabled": { "type": "boolean" }, "isEnabledInChat": { "type": "boolean" }, "orgConfiguration": { "type": "object" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "logoImageUrl": { "type": "string" }, "instructions": { "type": "string" } } } } }, "OrgToolTemplateSearchResponse": { "type": "object", "properties": { "orgToolTemplates": { "type": "array", "items": { "$ref": "#/components/schemas/OrgToolTemplate" } }, "total": { "type": "integer" } } }, "ToolAuthInfo": { "type": "object", "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "expiresIn": { "type": "integer" }, "issuedAt": { "type": "string", "format": "date-time" } } }, "OAuthInitiateResponse": { "type": "object", "properties": { "authUrl": { "type": "string" } }, "required": [ "authUrl" ] }, "IntegrationSearchRequest": { "type": "object", "properties": { "searchTerm": { "type": "string" }, "oauthTokenId": { "type": "string" } }, "required": [ "searchTerm", "oauthTokenId" ] }, "IntegrationItemRequest": { "type": "object", "properties": { "id": { "type": "string" }, "oauthTokenId": { "type": "string" } }, "required": [ "id", "oauthTokenId" ] }, "GitHubRepositorySearchRequest": { "type": "object", "properties": { "searchTerm": { "type": "string" }, "gitHubAppInstallationId": { "type": "string" }, "limit": { "type": "integer" }, "cursor": { "type": "string" } }, "required": [ "gitHubAppInstallationId" ] }, "GitHubPreviewRequest": { "type": "object", "properties": { "repo": { "type": "string" }, "gitHubAppInstallationId": { "type": "string" } }, "required": [ "repo", "gitHubAppInstallationId" ] }, "VercelBlobUploadResponse": { "type": "object", "properties": { "url": { "type": "string" }, "pathname": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "integer" } }, "additionalProperties": true }, "CreateResponseRequest": { "type": "object", "required": [ "input" ], "additionalProperties": true, "description": "Request body for `POST /api/v2/responses`. Mirrors OpenAI's Responses API `CreateResponse` shape with a small set of devs.ai extensions (each marked `**[devs.ai extension]**` below).", "properties": { "input": { "description": "User prompt — plain text or an array of input items (`message`, `function_call`, `function_call_output`). See the `InputItem` schema for the full grammar.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputItem" } } ] }, "model": { "type": "string", "description": "Model ID to use, like `gpt-4o` or `o3`. Required for stateless requests; optional when continuing a thread via `previous_response_id` / `conversation`." }, "previous_response_id": { "type": "string", "nullable": true, "description": "ID of a previous response to continue the conversation. Establishes multi-turn context." }, "conversation": { "description": "Conversation/thread ID (string) or object with `id` field. Items from this conversation are prepended to `input` and items from this response are appended to it.", "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } ] }, "instructions": { "type": "string", "nullable": true, "description": "System/developer instructions inserted as the first item in the model's context. When used with `previous_response_id`, instructions from the previous response are not carried over." }, "stream": { "type": "boolean", "default": true, "description": "If `true` (default), the response data is streamed to the client as Server-Sent Events. If `false`, the completed response is returned as JSON." }, "tools": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Tools the model may call while generating a response. See `ToolDefinition` for available tools (most built-ins are devs.ai extensions)." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Sampling temperature between 0 and 2. Higher values produce more random output." }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "description": "Nucleus sampling parameter. We generally recommend altering this OR `temperature`, not both." }, "max_output_tokens": { "type": "integer", "minimum": 1, "description": "Upper bound for the number of tokens that can be generated for a response, including reasoning tokens." }, "reasoning": { "type": "object", "description": "Reasoning configuration for reasoning-capable models (e.g. o-series).", "properties": { "effort": { "type": "string", "description": "Reasoning effort. OpenAI's standard enum is `[\"minimal\", \"low\", \"medium\", \"high\"]`. devs.ai also accepts the `**[devs.ai extension]**` values `none` and `xhigh`.", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ], "x-devs-ai-extension-values": [ "none", "xhigh" ] }, "summary": { "type": "string", "nullable": true, "enum": [ "auto", "concise", "detailed" ], "description": "Reasoning summary verbosity." }, "generate_summary": { "type": "string", "nullable": true, "enum": [ "auto", "concise", "detailed" ], "description": "Deprecated alias of `summary` (kept for backward compatibility with older OpenAI SDKs)." } } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Metadata key-value pairs for tagging." }, "parallel_tool_calls": { "type": "boolean", "description": "Whether to allow the model to run tool calls in parallel. Default `true`. Echoed back on the Response object." }, "tool_choice": { "description": "How the model should select which tool(s) to use. Accepts the OpenAI `tool_choice` shapes (e.g. `\"auto\"`, `\"none\"`, `\"required\"`, or a typed object referring to a specific tool)." }, "store": { "type": "boolean", "description": "Whether to store the generated response for later retrieval via the API. Default `true`." }, "truncation": { "description": "Truncation strategy for the model response. OpenAI accepts `\"auto\"` or `\"disabled\"`." }, "text": { "description": "Configuration options for a text response from the model. Can be plain text or structured JSON (e.g. `{ format: { type: \"json_schema\", ... } }`)." }, "service_tier": { "type": "string", "description": "Service tier to use for this request (e.g. `\"auto\"`, `\"default\"`, `\"flex\"`)." }, "user": { "type": "string", "description": "Stable identifier for the end-user. Used to boost cache hit rates and to help OpenAI detect abuse. Deprecated by OpenAI in favor of `safety_identifier` / `prompt_cache_key`." }, "include": { "type": "array", "items": { "type": "string" }, "description": "Specify additional output data to include in the model response (e.g. `file_search_call.results`, `message.input_image.image_url`, `message.output_text.logprobs`, `reasoning.encrypted_content`)." }, "background": { "type": "boolean", "description": "If `true`, the model runs in the background and the response can be polled / streamed via the dedicated endpoints." }, "options": { "allOf": [ { "$ref": "#/components/schemas/ChatOptions" }, { "description": "**[devs.ai extension]** Internal devs.ai chat options (provider-specific routing, sub-flow tracing, etc.). Not part of the OpenAI Responses API." } ], "x-devs-ai-extension": true }, "chat_mode": { "type": "string", "enum": [ "execute", "chat", "plan" ], "default": "execute", "description": "**[devs.ai extension]** Chat execution mode: `execute` runs tools, `chat` returns text only, `plan` returns the planned steps without running them.", "x-devs-ai-extension": true }, "user_secrets": { "type": "object", "additionalProperties": { "type": "string" }, "description": "**[devs.ai extension]** User-provided API keys / secrets that tools may reference at execution time. Keys are short-lived and never persisted server-side.", "x-devs-ai-extension": true }, "thread_mode": { "allOf": [ { "$ref": "#/components/schemas/ThreadMode" }, { "description": "**[devs.ai extension]** How to handle a new request when an existing thread is mid-run: `collect` (queue), `steer` (signal current run), `interrupt` (cancel + start), `force` (start fresh stateless run)." } ], "x-devs-ai-extension": true } } }, "CancelResponseRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string" }, "cancelPolicy": { "$ref": "#/components/schemas/CancelPolicy" } } }, "PauseResponseRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string" } } }, "ResumeResponseRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string" }, "toolOutputs": { "type": "array", "items": { "$ref": "#/components/schemas/ToolOutput" } } } }, "ResumeDeepResearchRequest": { "type": "object", "required": [ "subagentRunId" ], "additionalProperties": false, "properties": { "subagentRunId": { "type": "string", "minLength": 1 }, "approved": { "type": "boolean" }, "clarificationAnswer": { "type": "string" }, "goal": { "type": "string" }, "scope": { "type": "string" }, "deniedReason": { "type": "string" }, "reason": { "type": "string" } } }, "Response": { "type": "object", "required": [ "id", "object", "status", "output", "created_at" ], "description": "A model response. Mirrors OpenAI's Responses API `Response` shape with the devs.ai extensions noted below.", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "status": { "$ref": "#/components/schemas/ResponseStatus" }, "model": { "type": "string", "nullable": true }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/OutputItem" } }, "usage": { "$ref": "#/components/schemas/Usage" }, "error": { "$ref": "#/components/schemas/ResponseError" }, "created_at": { "type": "integer", "description": "Unix timestamp (seconds since epoch) when the response was created." }, "instructions": { "type": "string", "nullable": true, "description": "Echoed instructions from the request." }, "temperature": { "type": "number", "nullable": true }, "top_p": { "type": "number", "nullable": true }, "max_output_tokens": { "type": "integer", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "previous_response_id": { "type": "string", "nullable": true }, "parallel_tool_calls": { "type": "boolean", "description": "Whether the model was allowed to call tools in parallel for this response. Echoed from the request; defaults to `true` when not set on the request." }, "incomplete_details": { "type": "object", "nullable": true, "description": "Details about why the response is incomplete (only populated when `status: \"incomplete\"`).", "properties": { "reason": { "type": "string", "enum": [ "max_output_tokens", "content_filter", "paused" ], "description": "OpenAI's enum is `[\"max_output_tokens\", \"content_filter\"]`. The value `paused` is a **[devs.ai extension]** emitted when an in-flight run is paused via `POST /api/v2/responses/{responseId}/pause`.", "x-devs-ai-extension-values": [ "paused" ] } } }, "tool_choice": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "object", "additionalProperties": true, "nullable": true } ], "description": "Echoed tool choice strategy from the request." }, "tools": { "type": "array", "nullable": true, "items": {}, "description": "Echoed tools from the request." }, "text": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Echoed text format configuration from the request." }, "reasoning": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Echoed reasoning configuration from the request." }, "selection_metadata": { "type": "object", "description": "**[devs.ai extension]** Model routing / selection metadata captured during the run (chosen provider, fallback chain, latency hints, etc.).", "nullable": true, "additionalProperties": true, "x-devs-ai-extension": true } } }, "ControlResponse": { "type": "object", "required": [ "id", "object", "status" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response.cancel", "response.pause", "response.resume" ] }, "status": { "type": "string", "enum": [ "cancel_requested", "pause_requested", "resume_requested" ] }, "chatId": { "type": "string" } } }, "DeepResearchControlResponse": { "type": "object", "required": [ "id", "object", "status", "subagentRunId" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response.deep_research.resume" ] }, "status": { "type": "string", "enum": [ "resume_requested" ] }, "subagentRunId": { "type": "string" }, "reason": { "type": "string" } } }, "ResponseCreatedStreamEvent": { "type": "object", "required": [ "type", "response", "sequence_number" ], "description": "Payload for the synthetic `response.created` SSE event emitted at the start of a Responses API stream.", "properties": { "type": { "type": "string", "enum": [ "response.created" ] }, "response": { "$ref": "#/components/schemas/Response" }, "sequence_number": { "type": "integer", "minimum": 0 }, "stream_epoch": { "type": "string", "description": "**[devs.ai extension]** Redis stream epoch for reconnect handshakes. Also returned in the `x-stream-epoch` response header.", "x-devs-ai-extension": true } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "ResponseStatus": { "type": "string", "enum": [ "in_progress", "completed", "failed", "cancelled", "incomplete" ], "description": "Lifecycle status of the response. OpenAI's standard enum is `[\"in_progress\", \"completed\", \"failed\", \"incomplete\"]`. The value `cancelled` is a **[devs.ai extension]** returned when a run is cancelled via `POST /api/v2/responses/{responseId}/cancel`.", "x-devs-ai-extension-values": [ "cancelled" ] }, "ThreadMode": { "type": "string", "enum": [ "collect", "steer", "interrupt", "force" ], "default": "collect", "description": "**[devs.ai extension]** Controls how a new request is handled when an existing thread is mid-run. No OpenAI counterpart.", "x-devs-ai-extension": true }, "CancelPolicy": { "type": "string", "enum": [ "graceful", "immediate" ], "default": "graceful" }, "OutputItem": { "oneOf": [ { "$ref": "#/components/schemas/OutputMessage" }, { "$ref": "#/components/schemas/FunctionCallOutputItem" }, { "$ref": "#/components/schemas/ReasoningOutputItem" }, { "$ref": "#/components/schemas/WebSearchCallOutputItem" }, { "$ref": "#/components/schemas/ServerToolCallOutputItem" }, { "$ref": "#/components/schemas/ServerToolCallResultOutputItem" }, { "$ref": "#/components/schemas/McpCallOutputItem" } ], "discriminator": { "propertyName": "type", "mapping": { "message": "#/components/schemas/OutputMessage", "function_call": "#/components/schemas/FunctionCallOutputItem", "reasoning": "#/components/schemas/ReasoningOutputItem", "web_search_call": "#/components/schemas/WebSearchCallOutputItem", "server_tool_call": "#/components/schemas/ServerToolCallOutputItem", "server_tool_call_output": "#/components/schemas/ServerToolCallResultOutputItem", "mcp_call": "#/components/schemas/McpCallOutputItem" } } }, "OutputMessage": { "type": "object", "required": [ "id", "type", "role", "status", "content" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/OutputTextPart" } } } }, "OutputTextPart": { "type": "object", "required": [ "type", "text", "annotations" ], "description": "An `output_text` content part inside a streamed/persisted assistant `OutputMessage`. Mirrors OpenAI's `OutputTextContent` shape.", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/UrlCitationAnnotation" }, "description": "Currently devs.ai only emits `url_citation` annotations. OpenAI's `Annotation` union also includes `file_citation` and `file_path`, which devs.ai does not currently produce." } } }, "UrlCitationAnnotation": { "type": "object", "required": [ "type", "url", "start_index", "end_index" ], "properties": { "type": { "type": "string", "enum": [ "url_citation" ] }, "url": { "type": "string" }, "title": { "type": "string" }, "start_index": { "type": "integer" }, "end_index": { "type": "integer" } } }, "FunctionCallOutputItem": { "type": "object", "required": [ "id", "type", "name", "call_id", "arguments", "status" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function_call" ] }, "name": { "type": "string" }, "call_id": { "type": "string" }, "arguments": { "type": "string", "description": "JSON-encoded arguments" }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] } } }, "ReasoningOutputItem": { "type": "object", "required": [ "id", "type", "status", "summary" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "reasoning" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, "summary": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reasoning_text" ] }, "text": { "type": "string" } } } } } }, "WebSearchCallOutputItem": { "type": "object", "required": [ "id", "type", "status" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "web_search_call" ] }, "status": { "type": "string", "enum": [ "in_progress", "searching", "completed", "failed" ] } } }, "ServerToolCallOutputItem": { "type": "object", "description": "**[devs.ai extension]** Server-executed tool call output item. Emitted instead of OpenAI's `code_interpreter_call` / `image_generation_call` items for devs.ai's `python` and `image_generation` tools.", "x-devs-ai-extension": true, "required": [ "id", "type", "server_tool_call" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "server_tool_call" ] }, "server_tool_call": { "type": "object", "required": [ "call_id", "name", "arguments", "status" ], "properties": { "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON-encoded arguments" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ] } } } } }, "ServerToolCallResultOutputItem": { "type": "object", "description": "**[devs.ai extension]** Server-executed tool call result. Emitted in pair with `ServerToolCallOutputItem` instead of OpenAI's `code_interpreter_call_output` / `image_generation_call_output` items.", "x-devs-ai-extension": true, "required": [ "type", "call_id", "output" ], "properties": { "type": { "type": "string", "enum": [ "server_tool_call_output" ] }, "call_id": { "type": "string" }, "output": { "type": "string" } } }, "McpCallOutputItem": { "type": "object", "description": "MCP tool call output item (OpenAI standard)", "required": [ "id", "type", "server_label", "name", "arguments", "status" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "mcp_call" ] }, "server_label": { "type": "string", "description": "Human-readable label of the MCP server" }, "name": { "type": "string", "description": "Tool name" }, "arguments": { "type": "string", "description": "JSON-encoded arguments" }, "output": { "type": "string", "description": "Tool output on success" }, "error": { "type": "string", "description": "Error message on failure" }, "status": { "type": "string", "enum": [ "in_progress", "calling", "completed", "failed" ] } } }, "InputItem": { "description": "Input item for the Responses API (message, function_call, or function_call_output)", "oneOf": [ { "$ref": "#/components/schemas/MessageInputItem" }, { "$ref": "#/components/schemas/FunctionCallInputItem" }, { "$ref": "#/components/schemas/FunctionCallOutputInputItem" } ], "discriminator": { "propertyName": "type", "mapping": { "message": "#/components/schemas/MessageInputItem", "function_call": "#/components/schemas/FunctionCallInputItem", "function_call_output": "#/components/schemas/FunctionCallOutputInputItem" } } }, "MessageInputItem": { "description": "A `message` input item. Mirrors OpenAI's input grammar: items with `role: user|system|developer` are `InputMessage`-shaped (with `input_text`/`input_image`/`input_file` content), while items with `role: assistant` are `OutputMessage`-shaped (with `output_text`/`refusal` content, required `id`, required `status`). The two shapes do NOT share content parts.", "oneOf": [ { "$ref": "#/components/schemas/InputMessageInputItem" }, { "$ref": "#/components/schemas/OutputMessageInputItem" } ], "discriminator": { "propertyName": "role", "mapping": { "user": "#/components/schemas/InputMessageInputItem", "system": "#/components/schemas/InputMessageInputItem", "developer": "#/components/schemas/InputMessageInputItem", "assistant": "#/components/schemas/OutputMessageInputItem" } } }, "InputMessageInputItem": { "type": "object", "required": [ "role", "content" ], "description": "A user/system/developer message item. Mirrors OpenAI's `InputMessage` (request side). `id` is optional on the request side; the read-side `InputMessageResource` requires it.", "properties": { "type": { "type": "string", "enum": [ "message" ], "default": "message", "description": "**[devs.ai extension]** When omitted, defaults to `\"message\"` if `role` is present (devs.ai applies an `addDefaultMessageType` preprocess for client convenience). OpenAI's spec requires `type` to be sent explicitly.", "x-devs-ai-extension-behavior": "optional-on-request" }, "id": { "type": "string", "description": "Stable item identifier. Optional on the request side." }, "role": { "type": "string", "enum": [ "user", "system", "developer" ] }, "content": { "description": "Plain text shorthand (auto-wrapped as `input_text`) or an array of `InputContentPart` items (`input_text`, `input_image`, `input_file`).", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputContentPart" } } ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "description": "Item status. Optional for input messages." } } }, "OutputMessageInputItem": { "type": "object", "required": [ "id", "type", "role", "status", "content" ], "description": "An assistant message submitted as input (e.g. when reconstructing prior turns). Mirrors OpenAI's `OutputMessage`. `id`, `status`, `role: assistant`, and `type: message` are all required.", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/OutputContentPart" }, "description": "Array of `output_text` and/or `refusal` content parts." } } }, "InputContentPart": { "description": "Content part for an `InputMessageInputItem` (`role: user|system|developer`). Mirrors OpenAI's `InputContent` union: `input_text`, `input_image`, or `input_file` only.", "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "discriminator": { "propertyName": "type", "mapping": { "input_text": "#/components/schemas/InputTextContent", "input_image": "#/components/schemas/InputImageContent", "input_file": "#/components/schemas/InputFileContent" } } }, "OutputContentPart": { "description": "Content part for an `OutputMessageInputItem` (`role: assistant`). Mirrors OpenAI's `OutputMessageContent` union: `output_text` or `refusal` only.", "oneOf": [ { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/RefusalContent" } ], "discriminator": { "propertyName": "type", "mapping": { "output_text": "#/components/schemas/OutputTextContent", "refusal": "#/components/schemas/RefusalContent" } } }, "InputTextContent": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "input_text" ] }, "text": { "type": "string" }, "invisible": { "type": "boolean", "description": "**[devs.ai extension]** When `true`, this content part is sent to the model but hidden from end-user-facing transcripts.", "x-devs-ai-extension": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "**[devs.ai extension]** Free-form metadata attached to this content part. Not forwarded to the model.", "x-devs-ai-extension": true } } }, "InputImageContent": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_image" ] }, "image_url": { "type": "string" }, "file_id": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] }, "invisible": { "type": "boolean", "description": "**[devs.ai extension]** When `true`, this image is sent to the model but hidden from end-user-facing transcripts.", "x-devs-ai-extension": true } } }, "InputFileContent": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_file" ] }, "file_id": { "type": "string" }, "file_data": { "type": "string" }, "filename": { "type": "string" }, "invisible": { "type": "boolean", "description": "**[devs.ai extension]** When `true`, this file is sent to the model but hidden from end-user-facing transcripts.", "x-devs-ai-extension": true } } }, "OutputTextContent": { "type": "object", "required": [ "type", "text", "annotations" ], "description": "An `output_text` content part inside an assistant message. Mirrors OpenAI's `OutputTextContent`.", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/UrlCitationAnnotation" }, "description": "Currently devs.ai only emits `url_citation` annotations. OpenAI's `Annotation` union also includes `file_citation` and `file_path`, which devs.ai does not currently produce." }, "logprobs": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "**[devs.ai extension]** Log-probability information for tokens in this output. OpenAI's `OutputTextContent` does not include this field; populated by devs.ai when `include` requests `message.output_text.logprobs`.", "x-devs-ai-extension": true } } }, "RefusalContent": { "type": "object", "required": [ "type", "refusal" ], "description": "A `refusal` content part inside an assistant message. Mirrors OpenAI's `RefusalContent`.", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } } }, "FunctionCallInputItem": { "type": "object", "required": [ "type", "call_id", "name", "arguments" ], "description": "A prior `function_call` item submitted as input. Mirrors OpenAI's `FunctionCallItemParam`.", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string", "description": "Stable item identifier. Optional on the request side; preserved when echoed back." }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON-encoded arguments string." } } }, "FunctionCallOutputInputItem": { "type": "object", "required": [ "type", "call_id", "output" ], "description": "Result of a prior `function_call` submitted as input. Mirrors OpenAI's `FunctionCallOutputItemParam`, except for the `status` field — see below.", "properties": { "type": { "type": "string", "enum": [ "function_call_output" ] }, "call_id": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "error", "cancelled" ], "description": "**[devs.ai extension]** Status of the tool call result. devs.ai uses `[\"success\", \"error\", \"cancelled\"]`; OpenAI's `FunctionCallOutputItemParam.status` uses `[\"in_progress\", \"completed\", \"incomplete\"]`. The two enums are not compatible.", "x-devs-ai-extension": true } } }, "Usage": { "type": "object", "nullable": true, "description": "Token usage details for the response. Mirrors OpenAI's `ResponseUsage` shape, including the plural `input_tokens_details` / `output_tokens_details` field names.", "required": [ "input_tokens", "input_tokens_details", "output_tokens", "output_tokens_details", "total_tokens" ], "properties": { "input_tokens": { "type": "integer", "minimum": 0, "description": "The number of input tokens (prompt + tools + previous turns)." }, "input_tokens_details": { "type": "object", "required": [ "cached_tokens" ], "description": "Detailed breakdown of input tokens.", "properties": { "cached_tokens": { "type": "integer", "minimum": 0, "description": "The number of input tokens that were served from cache." } } }, "output_tokens": { "type": "integer", "minimum": 0, "description": "The number of output tokens (model response)." }, "output_tokens_details": { "type": "object", "required": [ "reasoning_tokens" ], "description": "Detailed breakdown of output tokens.", "properties": { "reasoning_tokens": { "type": "integer", "minimum": 0, "description": "The number of reasoning tokens (extended thinking) included in the output count." } } }, "total_tokens": { "type": "integer", "minimum": 0, "description": "The total number of tokens used (`input_tokens + output_tokens`)." } } }, "ResponseError": { "type": "object", "nullable": true, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "ContentPart": { "oneOf": [ { "$ref": "#/components/schemas/TextContentPart" }, { "$ref": "#/components/schemas/ImageContentPart" }, { "$ref": "#/components/schemas/AudioContentPart" }, { "$ref": "#/components/schemas/VideoContentPart" }, { "$ref": "#/components/schemas/DocumentContentPart" } ], "discriminator": { "propertyName": "type" } }, "ImageContentPart": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "url": { "type": "string", "description": "Image URL (provide url+mimeType, or id)" }, "mimeType": { "type": "string" }, "id": { "type": "string", "description": "File ID (resolved server-side to a URL)" }, "metadata": { "type": "object", "properties": { "detail": { "type": "string", "enum": [ "auto", "low", "high" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "filename": { "type": "string" } } } } }, "AudioContentPart": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "url": { "type": "string" }, "mimeType": { "type": "string" }, "id": { "type": "string" } } }, "VideoContentPart": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "url": { "type": "string" }, "mimeType": { "type": "string" }, "id": { "type": "string" } } }, "DocumentContentPart": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "url": { "type": "string" }, "mimeType": { "type": "string" }, "id": { "type": "string" }, "metadata": { "type": "object", "properties": { "filename": { "type": "string" } } } } }, "ToolDefinition": { "description": "A tool the model may invoke. The `function` and `web_search` variants mirror OpenAI's Responses API tools. All other variants are devs.ai-specific built-ins.", "oneOf": [ { "$ref": "#/components/schemas/FunctionToolDefinition" }, { "$ref": "#/components/schemas/WebSearchToolDefinition" }, { "$ref": "#/components/schemas/PythonToolDefinition" }, { "$ref": "#/components/schemas/ImageGenerationToolDefinition" }, { "$ref": "#/components/schemas/SpreadsheetToolDefinition" }, { "$ref": "#/components/schemas/MemoryToolDefinition" }, { "$ref": "#/components/schemas/SandboxToolDefinition" }, { "$ref": "#/components/schemas/McpServerToolDefinition" }, { "$ref": "#/components/schemas/DeepResearchToolDefinition" } ], "discriminator": { "propertyName": "type", "mapping": { "function": "#/components/schemas/FunctionToolDefinition", "web_search": "#/components/schemas/WebSearchToolDefinition", "python": "#/components/schemas/PythonToolDefinition", "image_generation": "#/components/schemas/ImageGenerationToolDefinition", "spreadsheet": "#/components/schemas/SpreadsheetToolDefinition", "memory": "#/components/schemas/MemoryToolDefinition", "sandbox": "#/components/schemas/SandboxToolDefinition", "mcp_server": "#/components/schemas/McpServerToolDefinition", "deep_research": "#/components/schemas/DeepResearchToolDefinition" } } }, "FunctionToolDefinition": { "type": "object", "required": [ "type", "name", "parameters" ], "description": "A user-defined function tool. Mirrors OpenAI's flat Responses-API `FunctionTool` shape: `{ type: \"function\", name, description?, parameters, strict? }`. Note the older Chat-Completions-style nested `{ type: \"function\", function: { ... } }` shape is NOT accepted on this endpoint.", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string", "description": "The name of the function to call." }, "description": { "type": "string", "description": "A description of the function. Used by the model to decide whether to call it." }, "parameters": { "type": "object", "additionalProperties": true, "description": "JSON Schema describing the parameters the function accepts." }, "strict": { "type": "boolean", "description": "Whether to enforce strict JSON-schema mode for the parameters." } } }, "WebSearchToolDefinition": { "type": "object", "required": [ "type" ], "description": "Web search tool. The output items (`web_search_call`) and streaming events (`response.web_search_call.in_progress|searching|completed`) emitted by devs.ai match OpenAI's standard shapes. NOTE: OpenAI's `web_search` / `web_search_preview` tool also accepts `user_location` and `search_context_size`; devs.ai currently ignores those input fields (they are silently dropped).", "properties": { "type": { "type": "string", "enum": [ "web_search" ] }, "includeXSearch": { "type": "boolean", "description": "**[devs.ai extension]** When `true`, also includes results from X (Twitter) search alongside web results.", "x-devs-ai-extension": true } } }, "PythonToolDefinition": { "type": "object", "required": [ "type" ], "description": "**[devs.ai extension]** Server-side Python execution tool. Conceptually similar to OpenAI's `code_interpreter` tool, but devs.ai emits `server_tool_call` / `server_tool_call_output` items and `response.server_tool_call.*` events instead of OpenAI's `code_interpreter_call` items and `response.code_interpreter_call.*` events.", "x-devs-ai-extension": true, "properties": { "type": { "type": "string", "enum": [ "python" ] } } }, "ImageGenerationToolDefinition": { "type": "object", "required": [ "type", "modelId" ], "description": "**[devs.ai extension]** Image generation tool. Shares the type name `image_generation` with OpenAI but the input shape (`modelId`, `samples`, `aspectRatio`, `quality`, `style`) and the emitted output shape (`server_tool_call` / `server_tool_call_output` items, `response.server_tool_call.*` events) differ from OpenAI's `ImageGenTool` / `image_generation_call` items.", "x-devs-ai-extension": true, "properties": { "type": { "type": "string", "enum": [ "image_generation" ] }, "modelId": { "type": "string" }, "samples": { "type": "number" }, "size": { "type": "string" }, "aspectRatio": { "type": "string" }, "quality": { "type": "string" }, "style": { "type": "string" } } }, "SpreadsheetToolDefinition": { "type": "object", "required": [ "type" ], "description": "**[devs.ai extension]** Spreadsheet manipulation tool. No OpenAI counterpart. Emits `server_tool_call` / `server_tool_call_output` items.", "x-devs-ai-extension": true, "properties": { "type": { "type": "string", "enum": [ "spreadsheet" ] } } }, "MemoryToolDefinition": { "type": "object", "required": [ "type" ], "description": "**[devs.ai extension]** Long-term memory tool. No OpenAI counterpart. Emits `server_tool_call` / `server_tool_call_output` items.", "x-devs-ai-extension": true, "properties": { "type": { "type": "string", "enum": [ "memory" ] } } }, "SandboxToolDefinition": { "type": "object", "required": [ "type" ], "description": "**[devs.ai extension]** General-purpose sandbox execution tool. No OpenAI counterpart. Emits `server_tool_call` / `server_tool_call_output` items.", "x-devs-ai-extension": true, "properties": { "type": { "type": "string", "enum": [ "sandbox" ] } } }, "McpServerToolDefinition": { "type": "object", "required": [ "type", "toolId" ], "description": "**[devs.ai extension]** Reference to a configured MCP server integration. Differs from OpenAI's `mcp` tool: devs.ai accepts `{ type: 'mcp_server', toolId }` referring to a configured MCP integration, instead of OpenAI's `server_label` / `server_url` / `connector_id` / `headers` / `allowed_tools` / `require_approval`. devs.ai DOES emit `mcp_call` output items and `response.mcp_call.in_progress|completed|failed` events that match OpenAI's standard shapes for executed tool calls, but does NOT currently emit OpenAI's `mcp_list_tools` discovery items, `mcp_approval_request` / `mcp_approval_response` items, `response.mcp_list_tools.*` events, or `response.mcp_call_arguments.*` events.", "x-devs-ai-extension": true, "properties": { "type": { "type": "string", "enum": [ "mcp_server" ] }, "toolId": { "type": "string", "description": "ID of the MCP server integration configured in devs.ai." } } }, "DeepResearchToolDefinition": { "type": "object", "required": [ "type" ], "description": "**[devs.ai extension]** Deep research tool that spawns a child workflow to perform multi-step research. No OpenAI counterpart.", "x-devs-ai-extension": true, "properties": { "type": { "type": "string", "enum": [ "deep_research" ] }, "timeBudgetMs": { "type": "integer", "minimum": 1 }, "maxChildren": { "type": "integer", "minimum": 1 }, "maxRefinementRounds": { "type": "integer", "minimum": 1 }, "visibility": { "type": "string", "enum": [ "visible", "background" ] }, "requireApproval": { "type": "boolean" }, "clarificationAnswer": { "type": "string" } } }, "OrgSubscriptionDto": { "type": "object", "required": [ "uuid", "orgId", "createdAt", "updatedAt", "type", "pricingPlan", "pricingPlanLabel", "maxUsers", "allowsMultipleUsers", "maxFreeUsers", "allowsFreeUsers", "userMembershipType", "status", "periodEndDate", "usageLimits", "externalSubscriptionId", "externalCustomerId", "processorType", "metadata", "cancelledAt", "periodStartDate", "balanceAllocationPerUser", "storageAllocationGb", "enforceBillingSinceCycleStart" ], "properties": { "uuid": { "type": "string", "description": "Public identifier for the organization subscription." }, "orgId": { "type": "string", "description": "Organization ID associated with the subscription." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was last updated." }, "type": { "$ref": "#/components/schemas/OrgSubscriptionTypeDto" }, "pricingPlan": { "$ref": "#/components/schemas/OrgSubscriptionPricingPlanDto" }, "pricingPlanLabel": { "type": "string", "description": "Human-readable pricing plan label." }, "maxUsers": { "type": "integer", "nullable": true, "description": "Maximum number of users allowed by the subscription." }, "allowsMultipleUsers": { "type": "boolean", "description": "Whether the subscription permits multiple users." }, "maxFreeUsers": { "type": "integer", "nullable": true, "description": "Maximum number of free users allowed by the subscription." }, "allowsFreeUsers": { "type": "boolean", "description": "Whether the subscription permits restricted/free users." }, "userMembershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto" }, "status": { "$ref": "#/components/schemas/OrgSubscriptionStatusDto" }, "periodEndDate": { "type": "string", "format": "date-time", "nullable": true, "description": "The current subscription period end date, when available." }, "usageLimits": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/UsageLimitsDto" } ] }, "externalSubscriptionId": { "type": "string", "nullable": true, "description": "External processor subscription identifier." }, "externalCustomerId": { "type": "string", "nullable": true, "description": "External processor customer identifier." }, "processorType": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SubscriptionProcessorTypeDto" } ] }, "metadata": { "$ref": "#/components/schemas/SubscriptionMetadataDto" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO-8601 cancel signal. Set on cancellation while status may remain ACTIVE until the subscription period closes." }, "periodStartDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Current subscription period start date, when available." }, "balanceAllocationPerUser": { "type": "string", "nullable": true, "description": "Dollar allocation per user as a decimal string (preserves precision)." }, "storageAllocationGb": { "type": "integer", "nullable": true, "description": "Storage allocation in gigabytes for the subscription plan." }, "enforceBillingSinceCycleStart": { "type": "string", "format": "date-time", "nullable": true, "description": "Cycle start when dollar-balance enforcement began, or null when deferred." } } }, "OrgSubscriptionTypeDto": { "type": "string", "enum": [ "FREE", "PAID" ] }, "OrgSubscriptionPricingPlanDto": { "type": "string", "enum": [ "FREE", "FREE_MULTI_USER", "PERSONAL", "BUSINESS", "ENTERPRISE" ] }, "OrgMembershipTypeDto": { "type": "string", "enum": [ "FULL", "RESTRICTED" ] }, "OrgSubscriptionStatusDto": { "type": "string", "enum": [ "ACTIVE", "CANCELLED", "SUSPENDED", "FREE_TRIAL" ] }, "SubscriptionProcessorTypeDto": { "type": "string", "enum": [ "STRIPE", "APPDIRECT", "APPLE", "TENANT" ] }, "TokenLimitsDto": { "type": "object", "required": [ "input", "output" ], "properties": { "input": { "type": "integer" }, "output": { "type": "integer" } } }, "UsageLimitsDto": { "type": "object", "required": [ "tokenLimits", "dataUsageLimitInGb", "mediaUsageTokenLimit" ], "properties": { "tokenLimits": { "type": "object", "required": [ "standard", "premium" ], "properties": { "standard": { "$ref": "#/components/schemas/TokenLimitsDto", "nullable": true }, "premium": { "$ref": "#/components/schemas/TokenLimitsDto", "nullable": true } } }, "dataUsageLimitInGb": { "type": "number" }, "mediaUsageTokenLimit": { "type": "integer" } } }, "SubscriptionMetadataDto": { "type": "object", "additionalProperties": true, "properties": { "trialEndDate": { "type": "string", "format": "date-time" }, "promo": { "type": "string" } } }, "TenantSubscriptionMetadataRequestDto": { "type": "object", "additionalProperties": false, "properties": { "trialEndDate": { "type": "string", "format": "date-time" }, "promo": { "type": "string" } }, "description": "Typed subscription metadata accepted on tenant subscription create/patch. Unknown keys are rejected." }, "SetTenantDefaultRateLimitRequestDto": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "SUBSCRIPTION_LIMITS", "UNLIMITED" ], "description": "Default rate limit mode for child organizations. SUBSCRIPTION_LIMITS applies subscription-based limits; UNLIMITED removes subscription caps." } } }, "TenantDefaultRateLimitResponseDto": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "SUBSCRIPTION_LIMITS", "UNLIMITED" ] } } }, "OrgRateLimitOverrideResponseDto": { "type": "object", "required": [ "orgId", "effectiveMode", "hasExplicitOverride" ], "properties": { "orgId": { "type": "string", "description": "Organization ID." }, "effectiveMode": { "type": "string", "enum": [ "BLOCKED", "UNLIMITED", "SUBSCRIPTION_LIMITS" ], "description": "Effective rate limit mode after tenant default and any per-org override." }, "hasExplicitOverride": { "type": "boolean", "description": "True when a BLOCKED or UNLIMITED override is set for this organization." } } }, "OrgRateLimitSimpleModeResponseDto": { "type": "object", "required": [ "orgId", "mode" ], "properties": { "orgId": { "type": "string" }, "mode": { "type": "string", "enum": [ "BLOCKED", "UNLIMITED", "NONE" ], "description": "Resulting override state: BLOCKED after block, UNLIMITED after unblock, NONE after clearing override." } } }, "OrgRateLimitOverrideItemDto": { "type": "object", "required": [ "orgId", "mode" ], "properties": { "orgId": { "type": "string" }, "mode": { "type": "string", "enum": [ "BLOCKED", "UNLIMITED" ] } } }, "ListTenantRateLimitOverridesResponseDto": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgRateLimitOverrideItemDto" } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": "string" } }, "description": "Present when additional pages can be fetched via the cursor query parameter." } } }, "CreateTenantOrganizationAdminDto": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Admin email address." }, "firstName": { "type": "string", "minLength": 1, "maxLength": 255 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 255 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Partner external user identifier." }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto", "description": "Admin seat type. Defaults to FULL." } }, "additionalProperties": false }, "CreateTenantOrganizationRequestDto": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Organization display name." }, "seedOrgName": { "type": "boolean", "default": true, "description": "When true (default), seeds the org brand name from name. When false, inherits tenant branding for the name." }, "admin": { "$ref": "#/components/schemas/CreateTenantOrganizationAdminDto" }, "externalId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Partner external organization identifier for reconciliation." } }, "additionalProperties": false }, "CreateTenantOrganizationResponseDto": { "type": "object", "required": [ "orgId", "adminUserId", "name", "tenantPublicId", "tenantName", "seededOrgName" ], "properties": { "orgId": { "type": "string" }, "adminUserId": { "type": "string", "description": "Resolved admin user ID (supplied admin or API caller)." }, "name": { "type": "string" }, "tenantPublicId": { "type": "string" }, "tenantName": { "type": "string" }, "seededOrgName": { "type": "boolean", "description": "False when seedOrgName was requested but the brand-name write failed (org still created)." } } }, "CreateTenantOrgSubscriptionRequestDto": { "type": "object", "required": [ "pricingPlan", "maxUsers" ], "properties": { "pricingPlan": { "type": "string", "enum": [ "FREE", "FREE_MULTI_USER", "PERSONAL", "BUSINESS" ], "description": "Pricing plan allowed on tenant subscription create/patch." }, "maxUsers": { "type": "integer", "minimum": 1, "description": "Paid seat cap." }, "externalSubscriptionId": { "type": "string", "nullable": true }, "externalCustomerId": { "type": "string", "nullable": true }, "allowsFreeUsers": { "type": "boolean", "description": "When true, permits RESTRICTED members up to maxFreeUsers." }, "maxFreeUsers": { "type": "integer", "minimum": 1, "nullable": true }, "metadata": { "$ref": "#/components/schemas/TenantSubscriptionMetadataRequestDto" } }, "additionalProperties": false, "description": "Creates a subscription via async workflow. processorType is set server-side to TENANT. Plan-derived fields (balanceAllocationPerUser, usageLimits, etc.) are not accepted on the wire." }, "PatchTenantOrgSubscriptionRequestDto": { "type": "object", "properties": { "pricingPlan": { "type": "string", "enum": [ "FREE", "FREE_MULTI_USER", "PERSONAL", "BUSINESS" ], "description": "Pricing plan allowed on tenant subscription create/patch." }, "maxUsers": { "type": "integer", "minimum": 1, "nullable": true }, "allowsFreeUsers": { "type": "boolean" }, "maxFreeUsers": { "type": "integer", "minimum": 1, "nullable": true }, "externalSubscriptionId": { "type": "string", "nullable": true }, "externalCustomerId": { "type": "string", "nullable": true }, "metadata": { "$ref": "#/components/schemas/TenantSubscriptionMetadataRequestDto" } }, "additionalProperties": false, "description": "Partial update. Status/lifecycle fields are not settable — use DELETE to cancel." }, "CancelTenantOrgSubscriptionRequestDto": { "type": "object", "properties": { "eventMetadata": { "type": "object", "additionalProperties": true, "description": "Optional provenance metadata for the cancel workflow." } }, "additionalProperties": false }, "BalanceTypeDto": { "type": "string", "enum": [ "CHAT", "CLI", "APP_BUILDER", "FREE_TIER" ] }, "BalanceColumnDto": { "type": "string", "enum": [ "INCLUDED", "EXTRA" ], "description": "Balance column to credit. Partners typically send EXTRA for purchased top-ups." }, "TenantAdjustBalanceRequestDto": { "type": "object", "required": [ "balanceType", "targetColumn", "amount", "reason" ], "properties": { "balanceType": { "$ref": "#/components/schemas/BalanceTypeDto" }, "targetColumn": { "$ref": "#/components/schemas/BalanceColumnDto" }, "amount": { "type": "string", "pattern": "^\\d{1,8}(\\.\\d{1,12})?$", "description": "Positive non-zero dollar amount as a decimal string (up to 8 integer and 12 fractional digits). Must be greater than zero; floats are not accepted." }, "reason": { "type": "string", "minLength": 10, "maxLength": 500, "description": "Audit reason (trimmed; must be at least 10 characters after trim)." } }, "additionalProperties": false }, "InitiatorTypeDto": { "type": "string", "enum": [ "SYSTEM", "USER", "ORG_ADMIN", "TENANT_ADMIN", "SUPERUSER" ] }, "LedgerEntryTypeDto": { "type": "string", "enum": [ "CONSUMPTION", "WEB_SEARCH_CONSUMPTION", "IMAGE_GENERATION_CONSUMPTION", "PROVISIONING", "TOP_UP", "RESET", "ADJUSTMENT", "FREE_TIER_CREDIT", "ADJUSTMENT_CREDIT_INCLUDED", "ADJUSTMENT_CREDIT_EXTRA", "ADJUSTMENT_DEBIT_INCLUDED", "ADJUSTMENT_DEBIT_EXTRA" ] }, "BalanceLedgerEntryDto": { "type": "object", "required": [ "id", "userId", "balanceType", "entryType", "amount", "initiatorType", "initiatedBy", "reason", "referenceType", "referenceId", "consumptionDetail", "createdAt" ], "properties": { "id": { "type": "integer" }, "userId": { "type": "string", "nullable": true }, "balanceType": { "$ref": "#/components/schemas/BalanceTypeDto" }, "entryType": { "$ref": "#/components/schemas/LedgerEntryTypeDto" }, "amount": { "type": "string", "description": "Signed decimal string." }, "initiatorType": { "$ref": "#/components/schemas/InitiatorTypeDto" }, "initiatedBy": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "referenceType": { "type": "string", "nullable": true }, "referenceId": { "type": "string", "nullable": true }, "consumptionDetail": { "type": "object", "nullable": true, "description": "Null for manual adjustments and top-ups." }, "createdAt": { "type": "string", "format": "date-time" } } }, "AdjustBalanceResponseDto": { "type": "object", "required": [ "ledgerEntry", "alreadyRecorded" ], "properties": { "ledgerEntry": { "$ref": "#/components/schemas/BalanceLedgerEntryDto" }, "alreadyRecorded": { "type": "boolean", "description": "True when an idempotent replay returned the previously recorded ledger row." } } }, "OrgBalanceDto": { "type": "object", "required": [ "balanceType", "includedBalance", "extraBalance" ], "properties": { "balanceType": { "$ref": "#/components/schemas/BalanceTypeDto" }, "includedBalance": { "type": "string", "description": "Per-cycle included balance (decimal string)." }, "extraBalance": { "type": "string", "description": "Top-up / extra balance (decimal string)." } } }, "BillingPaginationDto": { "type": "object", "required": [ "nextCursor", "limit" ], "properties": { "nextCursor": { "type": "string", "nullable": true }, "limit": { "type": "integer" } } }, "BalanceLedgerPageDto": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceLedgerEntryDto" } }, "pagination": { "$ref": "#/components/schemas/BillingPaginationDto" } } }, "InvoiceDto": { "type": "object", "required": [ "id", "number", "description", "status", "currency", "amountPaid", "amountDue", "hostedInvoiceUrl", "invoicePdfUrl", "periodStart", "periodEnd", "createdAt", "paidAt" ], "properties": { "id": { "type": "string" }, "number": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "status": { "type": "string" }, "currency": { "type": "string" }, "amountPaid": { "type": "string" }, "amountDue": { "type": "string" }, "hostedInvoiceUrl": { "type": "string", "nullable": true }, "invoicePdfUrl": { "type": "string", "nullable": true }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "paidAt": { "type": "string", "format": "date-time", "nullable": true } } }, "InvoicePageDto": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDto" } }, "pagination": { "$ref": "#/components/schemas/BillingPaginationDto" } } }, "AllocationLimitDto": { "oneOf": [ { "type": "string", "enum": [ "unlimited" ] }, { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, { "type": "null" } ], "description": "Dollar cap, explicit unlimited, or null (inherit from next layer)." }, "OrgAllocationDto": { "type": "object", "required": [ "balanceType", "monthlyLimit", "dailyLimit" ], "properties": { "balanceType": { "$ref": "#/components/schemas/BalanceTypeDto" }, "monthlyLimit": { "$ref": "#/components/schemas/AllocationLimitDto" }, "dailyLimit": { "$ref": "#/components/schemas/AllocationLimitDto" } } }, "TenantOrganizationMemberDto": { "type": "object", "required": [ "userId", "email", "firstName", "lastName", "role", "status", "membershipType", "createdAt", "externalUserId" ], "properties": { "userId": { "type": "string" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "ADMIN", "MEMBER" ] }, "status": { "type": "string", "enum": [ "member" ] }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto" }, "createdAt": { "type": "string", "format": "date-time" }, "externalUserId": { "type": "string", "nullable": true } } }, "CreateTenantOrganizationInvitationRequestDto": { "type": "object", "required": [ "emailAddress", "role" ], "properties": { "emailAddress": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "ADMIN", "MEMBER" ] }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto", "description": "Defaults to FULL." } }, "additionalProperties": false }, "TenantOrganizationInvitationSuccessDto": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "enum": [ true ] } } }, "TenantOrganizationInvitationDto": { "type": "object", "required": [ "id", "emailAddress", "role", "status", "membershipType", "createdAt" ], "properties": { "id": { "type": "string" }, "emailAddress": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked" ] }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto" }, "createdAt": { "type": "string", "format": "date-time", "nullable": true } } }, "TenantOrganizationInvitationsPageDto": { "type": "object", "required": [ "invitations", "totalCount" ], "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/TenantOrganizationInvitationDto" } }, "totalCount": { "type": "integer" } } }, "CreateTenantOrganizationMemberRequestDto": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "ADMIN", "MEMBER" ] }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto", "description": "Defaults to FULL." }, "firstName": { "type": "string", "minLength": 1, "maxLength": 255 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 255 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Partner external user identifier." } }, "additionalProperties": false }, "UpdateTenantOrganizationMemberRequestDto": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "ADMIN", "MEMBER" ] }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto" } }, "additionalProperties": false, "description": "At least one of role or membershipType must be provided." }, "TenantOrganizationMembersPageDto": { "type": "object", "required": [ "members", "totalCount" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/TenantOrganizationMemberDto" } }, "totalCount": { "type": "integer" } } }, "TenantMemberUpdateSuccessDto": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "enum": [ true ] } } }, "ValidationErrorDetail": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string", "description": "Dot-separated path to the offending field." }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "INVALID_TYPE", "TOO_SMALL", "TOO_BIG", "INVALID_FORMAT", "INVALID_VALUE", "UNRECOGNIZED_KEYS", "INVALID_UNION" ] } } }, "ApiKeySource": { "type": "string", "description": "Where the key was minted. PLATFORM: created via API or the web UI. CLI: created by the CLI login flow.", "enum": [ "PLATFORM", "CLI" ] }, "AIProfileSuggestedAction": { "type": "object", "required": [ "label", "message" ], "properties": { "label": { "type": "string", "description": "Text shown on the suggestion chip." }, "message": { "type": "string", "description": "Message sent when the chip is used." }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "SecuredAction": { "type": "string", "enum": [ "read", "write" ] }, "SecuredResourceAccessLevel": { "type": "string", "description": "Breadth of a permission. self: only the caller's own records. organization: everything in one organization. tenant: every organization under a tenant. instance: the whole deployment. tenant and instance are reserved for superusers and are silently dropped from role bodies.", "enum": [ "instance", "tenant", "organization", "self" ] }, "SecuredResourceType": { "type": "string", "description": "Resource a permission applies to. Instance-only resources (system, tenants, tenant-webhooks, instance-roles, billing-free-tier-config, billing-markup-configs) cannot be granted through this API.", "enum": [ "ai", "routines", "apps", "api-keys", "chats", "data-sources", "groups", "feature-flags", "org-client-credentials", "organizations", "org-settings", "org-subscriptions", "org-usage", "analytics", "org-logs", "org-files", "tools", "tool-templates", "users", "flows", "skills", "user-context", "user-settings", "files", "system", "oauth-tokens", "integrations-github", "app-branding", "app-integrations", "app-deploy-approvals", "app-marketplace-connect-requests", "instance-roles", "roles", "projects", "provider-status", "tenants", "tenant-webhooks", "default-user-permissions", "tool-API_FUNCTION", "tool-SQL", "tool-PYTHON", "tool-USER_INPUT", "tool-KNOWLEDGE_RETRIEVAL", "tool-WEB_SEARCH", "tool-IMAGE_GENERATION", "tool-MCP_SERVER", "tool-USER_CONTEXT", "tool-SPREADSHEET", "tool-BROWSER", "tool-SANDBOX", "tool-OPENAI_FUNCTION", "billing-balances", "billing-allocations", "billing-invoices", "billing-free-tier-config", "billing-markup-configs", "billing-topups", "org-units" ] }, "Permission": { "type": "object", "required": [ "resourceType", "action", "accessLevel" ], "description": "A single grant, read as \"this action on this resource at this breadth\". On create and update, entries that cannot be granted are discarded rather than rejected: any entry with accessLevel instance or tenant, any instance-only resource, any unrecognised resource type, and any organization-only resource requested at self level. At least one entry must survive filtering or the request fails validation, so a body of only invalid entries returns 400.", "properties": { "resourceType": { "$ref": "#/components/schemas/SecuredResourceType" }, "action": { "$ref": "#/components/schemas/SecuredAction" }, "accessLevel": { "$ref": "#/components/schemas/SecuredResourceAccessLevel" } } }, "CustomRoleDto": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "createdBy", "orgId", "name", "description", "permissions", "isSystem", "isDeleted", "deletedAt" ], "properties": { "id": { "type": "string", "description": "Public role identifier, used in role paths." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "description": "User ID that created the role." }, "orgId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } }, "isSystem": { "type": "boolean", "description": "True for built-in roles. Admin cannot be modified or deleted, User can be modified but not deleted, and any other system role is read-only." }, "isDeleted": { "type": "boolean", "description": "Roles are soft-deleted." }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "ListRolesResponseDto": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Built-in and custom roles for the organization. Not paginated.", "items": { "$ref": "#/components/schemas/CustomRoleDto" } } } }, "CreateRoleRequestDto": { "type": "object", "required": [ "name", "permissions" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Must be unique within the organization." }, "description": { "type": "string", "maxLength": 250 }, "permissions": { "type": "array", "minItems": 1, "description": "At least one grantable permission is required.", "items": { "$ref": "#/components/schemas/Permission" } } } }, "UpdateRoleRequestDto": { "type": "object", "description": "At least one of name, description or permissions must be provided. Supplying permissions replaces the role's grants outright.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "type": "string", "maxLength": 250 }, "permissions": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Permission" } } } }, "UpdateApiKeyRequestDto": { "type": "object", "required": [ "name", "scopes" ], "description": "Both fields are required; this replaces the key's name and scope list. Scopes the caller does not itself hold are dropped, and a request that grants no permitted scope is rejected with 403.", "properties": { "name": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } } }, "RevokeOrgApiKeyResponseDto": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "enum": [ true ] } } }, "OrgTheme": { "type": "string", "enum": [ "DEFAULT", "SCHOOL" ] }, "OrgPromptSurfaceConfig": { "type": "object", "required": [ "enabled", "prompt" ], "properties": { "enabled": { "type": "boolean" }, "prompt": { "type": "string", "maxLength": 4000, "description": "Control characters are rejected." } } }, "OrgPromptConfig": { "type": "object", "required": [ "agent", "agentless" ], "description": "System prompt injected by surface. agent covers custom agents; agentless covers direct model chat.", "properties": { "agent": { "$ref": "#/components/schemas/OrgPromptSurfaceConfig" }, "agentless": { "$ref": "#/components/schemas/OrgPromptSurfaceConfig" } } }, "ModelFeatureConfig": { "type": "object", "description": "Per-surface enablement for one model. An absent surface means enabled; only an explicit false disables.", "properties": { "chat": { "type": "boolean" }, "appBuilder": { "type": "boolean" }, "agents": { "type": "boolean" }, "routines": { "type": "boolean" } }, "additionalProperties": { "type": "boolean" } }, "ModelAudienceExclusionConfig": { "type": "object", "properties": { "excludedGroupIds": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 128 } }, "excludedUserIds": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 128 } } } }, "ModelAudienceInclusionConfig": { "type": "object", "properties": { "includedGroupIds": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 128 } }, "includedUserIds": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 128 } } } }, "OrgModelSettings": { "type": "object", "required": [ "restrictAvailableModels" ], "properties": { "restrictAvailableModels": { "type": "boolean", "description": "When true, only models in the allowlist may be used." }, "defaultModel": { "type": "string" }, "defaultImageModel": { "type": "string" }, "models": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted model IDs." }, "featureModels": { "type": "object", "description": "Keyed by model ID.", "additionalProperties": { "$ref": "#/components/schemas/ModelFeatureConfig" } }, "modelAudienceExclusions": { "type": "object", "description": "Keyed by model ID; at most 200 models.", "additionalProperties": { "$ref": "#/components/schemas/ModelAudienceExclusionConfig" } }, "modelAudienceInclusions": { "type": "object", "description": "Keyed by model ID; at most 200 models.", "additionalProperties": { "$ref": "#/components/schemas/ModelAudienceInclusionConfig" } }, "visibilityOverrides": { "type": "array", "items": { "type": "string" }, "description": "Applied only for callers with INSTANCE write on org-settings; ignored otherwise." } } }, "ThemeAwareBrandColor": { "description": "A hex colour, or per-theme hex colours. At least one of light or dark is required when the object form is used.", "oneOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }, { "type": "object", "properties": { "light": { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }, "dark": { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" } }, "additionalProperties": false } ] }, "SocialLinkConfig": { "type": "object", "properties": { "visible": { "type": "boolean", "description": "Defaults to true." }, "url": { "type": "string", "description": "Overrides the default target. HTTP or HTTPS for links; a plain address for email." } }, "additionalProperties": false }, "DesignLibraryConfig": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "enum": [ "tailwind", "shadcn", "mantine", "mui", "custom" ] }, "customName": { "type": "string" }, "customInstructions": { "type": "string" }, "csbTemplateId": { "type": "string" }, "componentList": { "type": "array", "items": { "type": "string" } }, "importPath": { "type": "string" } }, "additionalProperties": false }, "BrandStyles": { "type": "object", "description": "White-label appearance. Child organizations may be blocked from overriding branding by tenant policy, which returns 403.", "properties": { "font": { "type": "object", "properties": { "sans": { "type": "string", "enum": [ "Inter", "DM Sans", "Open Sans", "Roboto", "Lato", "Montserrat", "Poppins", "Raleway", "Source Sans Pro", "Nunito" ] }, "serif": { "type": "string", "enum": [ "Roboto Serif", "DM Serif Display", "Noto Serif", "Merriweather", "Lora", "Playfair Display", "Crimson Pro", "Libre Baskerville" ] } }, "additionalProperties": false }, "colors": { "type": "object", "properties": { "primary": { "$ref": "#/components/schemas/ThemeAwareBrandColor" }, "secondary": { "$ref": "#/components/schemas/ThemeAwareBrandColor" }, "primaryButtonFont": { "$ref": "#/components/schemas/ThemeAwareBrandColor" }, "secondaryButtonFont": { "$ref": "#/components/schemas/ThemeAwareBrandColor" }, "loginScreenBackground": { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }, "loginScreenText": { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" } }, "additionalProperties": false }, "authCopy": { "type": "object", "properties": { "loginTitle": { "type": "string", "minLength": 1, "maxLength": 120 }, "loginSubtitle": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false, "description": "Single-line text only." }, "socialLinks": { "type": "object", "properties": { "linkedIn": { "$ref": "#/components/schemas/SocialLinkConfig" }, "twitter": { "$ref": "#/components/schemas/SocialLinkConfig" }, "email": { "$ref": "#/components/schemas/SocialLinkConfig" } }, "additionalProperties": false }, "designLibrary": { "$ref": "#/components/schemas/DesignLibraryConfig" }, "presentationTemplate": { "type": "object", "description": "App design style metadata used for generated presentations.", "additionalProperties": true } }, "additionalProperties": false }, "ImageGenerationToolPolicy": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "allow", "deny" ] } }, "additionalProperties": false }, "ToolPolicies": { "type": "object", "required": [ "imageGeneration" ], "properties": { "imageGeneration": { "$ref": "#/components/schemas/ImageGenerationToolPolicy" } }, "additionalProperties": false }, "ChildOrgInfo": { "type": "object", "required": [ "orgId", "name" ], "properties": { "orgId": { "type": "string" }, "name": { "type": "string" } } }, "SanitizationAction": { "type": "string", "enum": [ "ALLOW", "REDACT", "BLOCK" ] }, "SensitiveEntityType": { "type": "string", "description": "Detectable sensitive data type. UNKNOWN is an internal sentinel and is rejected in policy rules.", "enum": [ "EMAIL_ADDRESS", "PHONE_NUMBER", "PERSON", "LOCATION", "DATE_TIME", "URL", "CREDIT_CARD", "CRYPTO", "IBAN_CODE", "IP_ADDRESS", "NRP", "MEDICAL_LICENSE", "US_BANK_NUMBER", "US_DRIVER_LICENSE", "US_ITIN", "US_PASSPORT", "US_SSN", "NPI", "UK_NHS", "UK_NINO", "SG_NRIC_FIN", "AU_ABN", "AU_ACN", "AU_TFN", "AU_MEDICARE", "IN_PAN", "IN_AADHAAR", "IN_VEHICLE_REGISTRATION", "IN_VOTER", "IN_PASSPORT", "API_KEY", "ACCESS_TOKEN", "PASSWORD", "PRIVATE_KEY", "UNKNOWN" ] }, "SanitizationPolicyRule": { "type": "object", "required": [ "entityType", "minConfidence", "action" ], "properties": { "entityType": { "$ref": "#/components/schemas/SensitiveEntityType" }, "minConfidence": { "type": "number", "minimum": 0, "maximum": 1 }, "action": { "$ref": "#/components/schemas/SanitizationAction" } } }, "SanitizationPolicy": { "type": "object", "required": [ "enabled", "defaultAction", "minScore", "rules", "allowList" ], "description": "Sensitive-data policy applied to prompts and responses. Manage it through the dedicated /api/v1/org-settings/sanitization routes; a value sent on the org-settings upsert is ignored.", "properties": { "enabled": { "type": "boolean" }, "defaultAction": { "$ref": "#/components/schemas/SanitizationAction" }, "minScore": { "type": "number", "minimum": 0, "maximum": 1, "description": "Findings scoring below this are treated as ALLOW." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/SanitizationPolicyRule" }, "description": "Each entity type may appear at most once." }, "allowList": { "type": "array", "items": { "type": "string" } } } }, "DeployApprovalConfig": { "type": "object", "required": [ "mode", "frequency" ], "properties": { "mode": { "type": "string", "enum": [ "none", "production_only", "all" ] }, "frequency": { "type": "string", "enum": [ "every_time", "once" ] }, "requestFormUrl": { "type": "string", "maxLength": 2048, "description": "Must be HTTPS." } }, "additionalProperties": false }, "StaticAppDefinition": { "type": "object", "required": [ "allowApiRoutes", "allowServerSideCode", "allowDatabase", "allowLinkedAgents", "allowExternalNetworkCalls", "allowAuthOrPayments" ], "description": "What still counts as a static app, and so may bypass risk assessment.", "properties": { "allowApiRoutes": { "type": "boolean" }, "allowServerSideCode": { "type": "boolean" }, "allowDatabase": { "type": "boolean" }, "allowLinkedAgents": { "type": "boolean" }, "allowExternalNetworkCalls": { "type": "boolean" }, "allowAuthOrPayments": { "type": "boolean" }, "maxFileCount": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "additionalProperties": false }, "DeployRiskAssessmentConfig": { "type": "object", "required": [ "enabled", "staticBypassEnabled", "applyToTargets", "agentBypassMode", "staticDefinition" ], "properties": { "enabled": { "type": "boolean" }, "staticBypassEnabled": { "type": "boolean" }, "applyToTargets": { "type": "string", "enum": [ "preview", "production", "all" ] }, "agentBypassMode": { "type": "string", "enum": [ "explain_only", "within_guardrails" ] }, "overrideAgentId": { "type": "string", "minLength": 1, "maxLength": 128 }, "staticDefinition": { "$ref": "#/components/schemas/StaticAppDefinition" } }, "additionalProperties": false }, "IntegrationRestriction": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "allowedIdentifiers": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Empty means no restriction. Defaults to empty." }, "deployApproval": { "$ref": "#/components/schemas/DeployApprovalConfig" } }, "additionalProperties": false }, "SupabaseIntegrationRestriction": { "type": "object", "description": "Supabase adds region, plan and per-user project quotas. An empty or absent list means that lever is not configured.", "properties": { "enabled": { "type": "boolean" }, "allowedIdentifiers": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "allowedRegions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "allowedPlans": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "maxProjectsPerUser": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "AppDuplicatePolicy": { "type": "object", "required": [ "allowPublicCrossOrg" ], "properties": { "allowPublicCrossOrg": { "type": "boolean" } }, "additionalProperties": false }, "MarketplaceConnectPolicy": { "type": "object", "required": [ "landingRequirement" ], "properties": { "landingRequirement": { "type": "string", "enum": [ "deploy", "share_link" ] } }, "additionalProperties": false }, "IntegrationPolicies": { "type": "object", "description": "Guardrails on third-party integrations and app deployment.", "properties": { "github": { "$ref": "#/components/schemas/IntegrationRestriction" }, "netlify": { "$ref": "#/components/schemas/IntegrationRestriction" }, "vercel": { "$ref": "#/components/schemas/IntegrationRestriction" }, "supabase": { "$ref": "#/components/schemas/SupabaseIntegrationRestriction" }, "deployRiskAssessment": { "$ref": "#/components/schemas/DeployRiskAssessmentConfig" }, "appDuplicate": { "$ref": "#/components/schemas/AppDuplicatePolicy" }, "marketplaceConnect": { "$ref": "#/components/schemas/MarketplaceConnectPolicy" } }, "additionalProperties": false }, "ContextBudgetPercentages": { "type": "object", "description": "Share of the model context window reserved for history. Absent means no organization override, so product defaults apply: 50 for chat, 80 for App Builder.", "properties": { "chat": { "type": "integer", "minimum": 30, "maximum": 80, "nullable": true }, "appBuilder": { "type": "integer", "minimum": 30, "maximum": 80, "nullable": true } }, "additionalProperties": false }, "OrgSettingsDto": { "type": "object", "required": [ "orgId" ], "description": "Organization settings. Fields are returned according to the caller's read permissions, so the response can be a subset: full org-settings read returns everything, while a caller holding only app-branding, app-integrations or app-deploy-approvals receives just that slice alongside orgId.", "properties": { "orgId": { "type": "string" }, "theme": { "$ref": "#/components/schemas/OrgTheme" }, "publicCatalog": { "type": "boolean", "description": "Whether the organization lists agents in the public Network Catalog." }, "approvedFilter": { "type": "boolean", "description": "Whether catalog browsing is limited to organization-approved agents." }, "userInvites": { "type": "boolean", "description": "Whether members may invite other users." }, "aiSharing": { "type": "boolean", "description": "Whether members may share agents." }, "aiRating": { "type": "boolean", "description": "Whether agents may be rated." }, "apiAccess": { "type": "boolean", "description": "Whether API keys may be minted for this organization. Creating a key requires this to be true." }, "linkPermissions": { "type": "boolean", "description": "Whether link-based agent sharing is allowed." }, "orgPermissions": { "type": "boolean", "description": "Whether organization-wide agent visibility is allowed." }, "groupCreation": { "type": "boolean", "description": "Whether members may create groups." }, "memory": { "type": "boolean", "description": "Whether conversational memory is enabled." }, "incognito": { "type": "boolean", "description": "Whether incognito chats are enabled." }, "suggestedActions": { "type": "boolean", "description": "Whether suggested actions are shown." }, "enterpriseSearch": { "type": "boolean", "description": "Whether enterprise search is enabled." }, "selfHostedCliAgents": { "type": "boolean", "description": "Whether self-hosted CLI agents are permitted." }, "requireTwoFactorAuth": { "type": "boolean", "description": "Whether members must enrol in two-factor authentication." }, "appExternalSharing": { "type": "boolean", "description": "Whether apps may be shared outside the organization." }, "defaultAgentVisibility": { "$ref": "#/components/schemas/AIVisibility" }, "modelSettings": { "$ref": "#/components/schemas/OrgModelSettings" }, "logoDark": { "type": "string", "nullable": true, "description": "HTTPS URL of the dark-theme logo." }, "logoLight": { "type": "string", "nullable": true, "description": "HTTPS URL of the light-theme logo." }, "orgName": { "type": "string", "nullable": true }, "brandStyles": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BrandStyles" } ] }, "appBrandingPrompt": { "type": "string", "nullable": true }, "docsSiteUrl": { "type": "string", "nullable": true, "maxLength": 2048, "description": "Must be HTTPS." }, "showDevsAiBranding": { "type": "boolean", "description": "Whether Devs.ai branding is shown." }, "showDocumentationLink": { "type": "boolean", "description": "Whether the documentation link is shown." }, "showUpgradeLink": { "type": "boolean", "description": "Whether the upgrade link is shown." }, "showUserInviteLink": { "type": "boolean", "description": "Whether the invite link is shown." }, "showUserMobileAppLink": { "type": "boolean", "description": "Whether the mobile app link is shown." }, "showMobileAppAnnouncementBanner": { "type": "boolean", "description": "Whether the mobile app banner is shown." }, "showIntegrationsLinks": { "type": "boolean", "description": "Whether integration links are shown." }, "showAvatarImageGeneration": { "type": "boolean", "description": "Whether avatar image generation is offered." }, "toolPolicies": { "$ref": "#/components/schemas/ToolPolicies" }, "integrationPolicies": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/IntegrationPolicies" } ] }, "timezone": { "type": "string", "maxLength": 64, "description": "IANA timezone, for example America/New_York." }, "locale": { "type": "string", "enum": [ "en", "fr", "" ], "description": "Default locale. Empty means the platform default." }, "contextBudgetPercentages": { "$ref": "#/components/schemas/ContextBudgetPercentages" }, "networkCatalogTenantEnabled": { "type": "boolean", "description": "Read-only. False when the tenant has disabled the Network Catalog for all of its organizations. Absent means enabled." }, "defaultListInOrgCatalog": { "type": "boolean", "description": "Read-only. Effective default for the organization-catalog toggle on new agents, resolved from the tenant default." }, "orgPrompt": { "type": "string", "nullable": true, "description": "Read-only mirror of orgPromptConfig.agent.prompt, kept for older clients." }, "orgPromptConfig": { "$ref": "#/components/schemas/OrgPromptConfig" }, "sanitizationPolicy": { "$ref": "#/components/schemas/SanitizationPolicy" }, "tenantOwnerOrgId": { "type": "string", "nullable": true, "description": "Read-only." }, "tenantId": { "type": "integer", "nullable": true, "description": "Read-only." }, "tenantName": { "type": "string", "nullable": true, "description": "Read-only." }, "isTenantOwner": { "type": "boolean", "description": "Read-only." }, "childOrganizations": { "type": "array", "description": "Read-only. Populated for tenant owner organizations.", "items": { "$ref": "#/components/schemas/ChildOrgInfo" } } } }, "UpsertOrgSettingsRequestDto": { "type": "object", "required": [ "orgId", "theme", "publicCatalog", "approvedFilter", "userInvites", "aiSharing", "aiRating", "apiAccess", "linkPermissions", "orgPermissions", "groupCreation", "memory", "incognito", "suggestedActions", "enterpriseSearch", "selfHostedCliAgents", "requireTwoFactorAuth", "defaultAgentVisibility", "modelSettings", "logoDark", "logoLight", "orgName", "brandStyles" ], "description": "Despite the POST verb this is a whole-object upsert, not a per-field patch. Every field in the required list must be present on each call, so the normal flow is to GET the settings, change what you need and send the result back. Omitted optional fields are merged from the current values rather than cleared. Fields the caller may not write are silently kept at their existing values instead of causing an error, so a 200 does not by itself prove a field changed. Unknown properties are rejected.", "properties": { "orgId": { "type": "string" }, "theme": { "$ref": "#/components/schemas/OrgTheme" }, "publicCatalog": { "type": "boolean", "description": "Whether the organization lists agents in the public Network Catalog." }, "approvedFilter": { "type": "boolean", "description": "Whether catalog browsing is limited to organization-approved agents." }, "userInvites": { "type": "boolean", "description": "Whether members may invite other users." }, "aiSharing": { "type": "boolean", "description": "Whether members may share agents." }, "aiRating": { "type": "boolean", "description": "Whether agents may be rated." }, "apiAccess": { "type": "boolean", "description": "Whether API keys may be minted for this organization. Creating a key requires this to be true." }, "linkPermissions": { "type": "boolean", "description": "Whether link-based agent sharing is allowed." }, "orgPermissions": { "type": "boolean", "description": "Whether organization-wide agent visibility is allowed." }, "groupCreation": { "type": "boolean", "description": "Whether members may create groups." }, "memory": { "type": "boolean", "description": "Whether conversational memory is enabled." }, "incognito": { "type": "boolean", "description": "Whether incognito chats are enabled." }, "suggestedActions": { "type": "boolean", "description": "Whether suggested actions are shown." }, "enterpriseSearch": { "type": "boolean", "description": "Whether enterprise search is enabled." }, "selfHostedCliAgents": { "type": "boolean", "description": "Whether self-hosted CLI agents are permitted." }, "requireTwoFactorAuth": { "type": "boolean", "description": "Whether members must enrol in two-factor authentication." }, "appExternalSharing": { "type": "boolean", "description": "Whether apps may be shared outside the organization." }, "defaultAgentVisibility": { "$ref": "#/components/schemas/AIVisibility" }, "modelSettings": { "$ref": "#/components/schemas/OrgModelSettings" }, "logoDark": { "type": "string", "nullable": true, "description": "HTTPS URL of the dark-theme logo." }, "logoLight": { "type": "string", "nullable": true, "description": "HTTPS URL of the light-theme logo." }, "orgName": { "type": "string", "nullable": true }, "brandStyles": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BrandStyles" } ] }, "appBrandingPrompt": { "type": "string", "nullable": true }, "docsSiteUrl": { "type": "string", "nullable": true, "maxLength": 2048, "description": "Must be HTTPS." }, "showDevsAiBranding": { "type": "boolean", "description": "Whether Devs.ai branding is shown." }, "showDocumentationLink": { "type": "boolean", "description": "Whether the documentation link is shown." }, "showUpgradeLink": { "type": "boolean", "description": "Whether the upgrade link is shown." }, "showUserInviteLink": { "type": "boolean", "description": "Whether the invite link is shown." }, "showUserMobileAppLink": { "type": "boolean", "description": "Whether the mobile app link is shown." }, "showMobileAppAnnouncementBanner": { "type": "boolean", "description": "Whether the mobile app banner is shown." }, "showIntegrationsLinks": { "type": "boolean", "description": "Whether integration links are shown." }, "showAvatarImageGeneration": { "type": "boolean", "description": "Whether avatar image generation is offered." }, "toolPolicies": { "$ref": "#/components/schemas/ToolPolicies" }, "integrationPolicies": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/IntegrationPolicies" } ] }, "timezone": { "type": "string", "maxLength": 64, "description": "IANA timezone, for example America/New_York." }, "locale": { "type": "string", "enum": [ "en", "fr", "" ], "description": "Default locale. Empty means the platform default." }, "contextBudgetPercentages": { "$ref": "#/components/schemas/ContextBudgetPercentages" }, "orgPromptConfig": { "$ref": "#/components/schemas/OrgPromptConfig" }, "orgPrompt": { "type": "string", "nullable": true, "maxLength": 4000, "description": "Deprecated. Use orgPromptConfig. Sending a non-empty value together with orgPromptConfig is rejected." }, "showChatImageGeneration": { "type": "boolean", "description": "Deprecated. Normalized into toolPolicies.imageGeneration." }, "tenantOwnerOrgId": { "type": "string", "nullable": true, "description": "Accepted for round-tripping but not persisted." }, "tenantId": { "type": "integer", "nullable": true, "description": "Accepted for round-tripping but not persisted." }, "tenantName": { "type": "string", "nullable": true, "description": "Accepted for round-tripping but not persisted." }, "isTenantOwner": { "type": "boolean", "description": "Accepted for round-tripping but not persisted." }, "childOrganizations": { "type": "array", "items": { "$ref": "#/components/schemas/ChildOrgInfo" }, "description": "Accepted for round-tripping but not persisted." }, "sanitizationPolicy": { "allOf": [ { "$ref": "#/components/schemas/SanitizationPolicy" } ], "description": "Accepted for round-tripping but not persisted here; use the dedicated sanitization routes." } }, "additionalProperties": false }, "OrgMemberRoleSummaryDto": { "type": "object", "required": [ "id", "name", "description", "isSystem" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "isSystem": { "type": "boolean" } } }, "OrgMemberDto": { "type": "object", "required": [ "userId", "email", "firstName", "lastName", "membershipType", "isClerkAdmin", "joinedAt", "lastLoginAt", "lastActiveAt", "externalUserId", "imageUrl", "roles" ], "properties": { "userId": { "type": "string" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto" }, "isClerkAdmin": { "type": "boolean", "description": "Always false for callers without roles read permission." }, "joinedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastLoginAt": { "type": "string", "format": "date-time", "nullable": true }, "lastActiveAt": { "type": "string", "format": "date-time", "nullable": true }, "externalUserId": { "type": "string", "nullable": true }, "imageUrl": { "type": "string", "nullable": true }, "roles": { "type": "array", "description": "Empty for callers without roles read permission.", "items": { "$ref": "#/components/schemas/OrgMemberRoleSummaryDto" } } } }, "SeatUsageDto": { "type": "object", "required": [ "processorType", "allowsFreeUsers", "isFreeMultiUserPlan", "paidSeatsUsed", "paidSeatsMax", "paidSeatsPending", "freeSeatsUsed", "freeSeatsMax", "freeSeatsPending", "pendingCountsApproximate" ], "properties": { "processorType": { "type": "string", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SubscriptionProcessorTypeDto" } ] }, "allowsFreeUsers": { "type": "boolean" }, "isFreeMultiUserPlan": { "type": "boolean" }, "paidSeatsUsed": { "type": "integer" }, "paidSeatsMax": { "type": "integer", "nullable": true, "description": "Null means unlimited." }, "paidSeatsPending": { "type": "integer" }, "freeSeatsUsed": { "type": "integer" }, "freeSeatsMax": { "type": "integer", "nullable": true, "description": "Null means unlimited." }, "freeSeatsPending": { "type": "integer" }, "pendingCountsApproximate": { "type": "boolean" } } }, "PendingOrgInvitationDto": { "type": "object", "required": [ "id", "emailAddress", "membershipType", "createdAt" ], "properties": { "id": { "type": "string" }, "emailAddress": { "type": "string", "format": "email" }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto" }, "customRoleIds": { "type": "array", "items": { "type": "string" } }, "invitedByEmail": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true } } }, "OrgMembersPageDto": { "type": "object", "required": [ "members", "totalCount", "roles", "invitations", "seatUsage" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMemberDto" } }, "totalCount": { "type": "integer", "description": "Total members matching the filters, across all pages." }, "pagination": { "type": "object", "required": [ "nextCursor" ], "description": "Present only when another page exists. Pass nextCursor back as the cursor query parameter.", "properties": { "nextCursor": { "type": "string" } } }, "roles": { "type": "array", "description": "Roles available in the organization. Empty for callers without roles read permission.", "items": { "$ref": "#/components/schemas/OrgMemberRoleSummaryDto" } }, "invitations": { "type": "array", "description": "Always empty on this endpoint; pending invitations are not populated here.", "items": { "$ref": "#/components/schemas/PendingOrgInvitationDto" } }, "seatUsage": { "$ref": "#/components/schemas/SeatUsageDto" } } }, "CreateOrgMemberInvitationsRequestDto": { "type": "object", "required": [ "emails", "membershipType" ], "properties": { "emails": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "email" }, "description": "Lowercased and de-duplicated before sending." }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto" }, "customRoleIds": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1 }, "description": "Defaults to empty. Assigning an admin role requires roles write permission on the target organization." }, "orgId": { "type": "string", "description": "Target organization. Defaults to the caller's organization." } }, "additionalProperties": false }, "CreateOrgMemberInvitationsResponseDto": { "type": "object", "required": [ "success", "invitedCount" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "invitedCount": { "type": "integer", "description": "Invitations actually sent. Addresses that are already members or already invited are skipped, so this can be 0 on a successful call." } } }, "TenantOrganizationDto": { "type": "object", "required": [ "orgId", "name", "imageUrl" ], "description": "Identity-provider view of a child organization. This is name and logo only, not the organization's settings; use /api/v1/org-settings for those.", "properties": { "orgId": { "type": "string" }, "name": { "type": "string", "nullable": true, "description": "Null only if the identity provider record cannot be re-read immediately after an update." }, "imageUrl": { "type": "string", "nullable": true, "description": "Logo URL, or null when no logo is set." } } } }, "parameters": { "responseId": { "name": "responseId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, "XIdempotencyKey": { "name": "X-Idempotency-Key", "in": "header", "required": true, "description": "Client-supplied idempotency key (1–128 characters). Required for subscription lifecycle mutations and balance top-ups. Replaying the same key returns the same success outcome.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "x-streaming-events": { "description": "## SSE Streaming Events\n\nWhen `stream=true`, the response is an SSE stream. Each event follows the format:\n\n```\nevent: \ndata: \n\n```\n\nEvery payload includes a monotonically increasing **`sequence_number`** field — devs.ai populates this on every event (devs.ai extension over OpenAI's spec, which only requires it on a subset of events). Use it for resumption via `GET /api/v2/responses/{responseId}/stream?lastSequence=...`.\n\nLegend:\n- ✅ OpenAI-aligned: same event name and payload shape as OpenAI's Responses API.\n- 🟡 OpenAI-aligned, partial coverage: event name matches OpenAI but devs.ai does not emit every variant OpenAI defines.\n- **[devs.ai extension]**: event has no equivalent in OpenAI's Responses API.\n\n### Lifecycle (✅ OpenAI-aligned)\n\n| Event | When | Key payload fields |\n|-------|------|--------------------|\n| `response.created` | Stream starts | `response` (full Response snapshot, `status: in_progress`) |\n| `response.in_progress` | Processing started / re-emitted on each new output item | `response` |\n| `response.completed` | Terminal: success | `response` (with `output` and `usage`) |\n| `response.failed` | Terminal: error | `response` (with `error`) |\n\n### Output Items + Content Parts (✅ OpenAI-aligned)\n\n| Event | When | Key payload fields |\n|-------|------|--------------------|\n| `response.output_item.added` | New output item (`message`, `function_call`, `reasoning`, `web_search_call`, `mcp_call`, `server_tool_call`, `server_tool_call_output`) | `item`, `output_index`, optional **[devs.ai extension]** `status_hints: string[]` |\n| `response.output_item.done` | Output item finalized | `item`, `output_index` |\n| `response.content_part.added` | New content part inside a message | `part`, `content_index`, `item_id`, `output_index` |\n| `response.content_part.done` | Content part finalized | `part`, `content_index`, `item_id`, `output_index` |\n\n### Text (✅ OpenAI-aligned)\n\n| Event | When | Key payload fields |\n|-------|------|--------------------|\n| `response.output_text.delta` | Incremental text token | `delta`, `content_index`, `item_id`, `output_index` |\n| `response.output_text.done` | Full text finalized | `text`, `content_index`, `item_id`, `output_index` |\n| `response.output_text.annotation.added` | New annotation (currently only `url_citation`) attached to the streaming text | `annotation`, `annotation_index`, `content_index`, `item_id`, `output_index` |\n\n### Function Calling (✅ OpenAI-aligned)\n\n| Event | When | Key payload fields |\n|-------|------|--------------------|\n| `response.function_call_arguments.delta` | Incremental client function arguments | `delta`, `item_id`, `output_index` |\n| `response.function_call_arguments.done` | Client function arguments finalized | `arguments`, `name`, `item_id`, `output_index` |\n\n### Reasoning (✅ OpenAI-aligned)\n\n| Event | When | Key payload fields |\n|-------|------|--------------------|\n| `response.reasoning_text.delta` | Reasoning token (models with extended thinking) | `delta`, `item_id`, `output_index` |\n| `response.reasoning_text.done` | Reasoning finalized | `text`, `item_id`, `output_index` |\n\n### Web Search (✅ OpenAI-aligned)\n\n| Event | When | Key payload fields |\n|-------|------|--------------------|\n| `response.web_search_call.in_progress` | Web search call created | `item_id`, `output_index` |\n| `response.web_search_call.searching` | Search executing | `item_id`, `output_index` |\n| `response.web_search_call.completed` | Search finished | `item_id`, `output_index` |\n\n### MCP (🟡 OpenAI-aligned, partial)\n\n| Event | When | Key payload fields |\n|-------|------|--------------------|\n| `response.mcp_call.in_progress` | MCP tool call started | `item_id`, `output_index` |\n| `response.mcp_call.completed` | MCP tool call succeeded | `item_id`, `output_index` |\n| `response.mcp_call.failed` | MCP tool call failed | `item_id`, `output_index`, `error` |\n\n> OpenAI also defines `response.mcp_call_arguments.delta` / `.done` and `response.mcp_list_tools.in_progress` / `.completed` / `.failed`. devs.ai does not emit these today (see the `mcp_server` tool definition for the full list of MCP features that are not yet implemented).\n\n### Server Tools — **[devs.ai extension]**\n\nEmitted INSTEAD OF OpenAI's `code_interpreter_call.*` and `image_generation_call.*` events for devs.ai's `python` and `image_generation` built-in tools, and for any other tool that runs server-side.\n\n| Event | When | Key payload fields |\n|-------|------|--------------------|\n| `response.server_tool_call.in_progress` | Server tool call created | `item_id`, `output_index` |\n| `response.server_tool_call.completed` | Server tool call succeeded | `item_id`, `output_index` |\n| `response.server_tool_call.failed` | Server tool call failed | `item_id`, `output_index`, `error` |\n| `response.server_tool_call_arguments.delta` | Incremental server tool arguments | `delta`, `item_id`, `output_index` |\n| `response.server_tool_call_arguments.done` | Server tool arguments finalized | `arguments`, `name`, `item_id`, `output_index` |\n\n### Subagents — **[devs.ai extension]**\n\nEmitted by the `deep_research` tool (and any other tool that spawns a child workflow).\n\n| Event | When | Key payload fields |\n|-------|------|--------------------|\n| `response.subagent.started` | Child workflow started | `subagent_run_id`, `visibility` |\n| `response.subagent.progress` | Child workflow progress (`visibility: visible` only) | `subagent_run_id`, `visibility`, `progress` |\n| `response.subagent.completed` | Child workflow finished | `subagent_run_id`, `visibility`, `status`, optional `error` |\n\n### Terminal Sentinel — **[devs.ai extension]**\n\n```\nevent: done\ndata: [DONE]\n```\n\nEvery stream ends with this sentinel after the terminal lifecycle event (`response.completed` or `response.failed`). OpenAI's Responses streaming format does not include a terminal sentinel.\n\n### Example: Simple Text Response\n\n```\nevent: response.created\ndata: {\"type\":\"response.created\",\"response\":{\"id\":\"resp_1\",\"object\":\"response\",\"status\":\"in_progress\",\"output\":[],\"usage\":null,\"parallel_tool_calls\":true},\"sequence_number\":0}\n\nevent: response.in_progress\ndata: {\"type\":\"response.in_progress\",\"response\":{\"id\":\"resp_1\",\"object\":\"response\",\"status\":\"in_progress\",\"output\":[],\"parallel_tool_calls\":true},\"sequence_number\":1}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"item\":{\"id\":\"msg_1\",\"type\":\"message\",\"role\":\"assistant\",\"status\":\"in_progress\",\"content\":[{\"type\":\"output_text\",\"text\":\"\",\"annotations\":[]}]},\"output_index\":0,\"sequence_number\":2}\n\nevent: response.content_part.added\ndata: {\"type\":\"response.content_part.added\",\"part\":{\"type\":\"output_text\",\"text\":\"\",\"annotations\":[]},\"content_index\":0,\"item_id\":\"msg_1\",\"output_index\":0,\"sequence_number\":3}\n\nevent: response.output_text.delta\ndata: {\"type\":\"response.output_text.delta\",\"delta\":\"Hello\",\"content_index\":0,\"item_id\":\"msg_1\",\"output_index\":0,\"sequence_number\":4}\n\nevent: response.output_text.delta\ndata: {\"type\":\"response.output_text.delta\",\"delta\":\" world\",\"content_index\":0,\"item_id\":\"msg_1\",\"output_index\":0,\"sequence_number\":5}\n\nevent: response.output_text.done\ndata: {\"type\":\"response.output_text.done\",\"text\":\"Hello world\",\"content_index\":0,\"item_id\":\"msg_1\",\"output_index\":0,\"sequence_number\":6}\n\nevent: response.content_part.done\ndata: {\"type\":\"response.content_part.done\",\"part\":{\"type\":\"output_text\",\"text\":\"Hello world\",\"annotations\":[]},\"content_index\":0,\"item_id\":\"msg_1\",\"output_index\":0,\"sequence_number\":7}\n\nevent: response.output_item.done\ndata: {\"type\":\"response.output_item.done\",\"item\":{\"id\":\"msg_1\",\"type\":\"message\",\"role\":\"assistant\",\"status\":\"completed\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello world\",\"annotations\":[]}]},\"output_index\":0,\"sequence_number\":8}\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp_1\",\"object\":\"response\",\"status\":\"completed\",\"output\":[...],\"parallel_tool_calls\":true,\"usage\":{\"input_tokens\":10,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens\":2,\"output_tokens_details\":{\"reasoning_tokens\":0},\"total_tokens\":12}},\"sequence_number\":9}\n\nevent: done\ndata: [DONE]\n```\n" } }, "security": [], "paths": { "/api/v1/api-keys": { "post": { "tags": [ "API Keys" ], "summary": "Create an API key", "description": "Creates a new API key for the caller or a specified user and organization (based on access level).", "operationId": "createApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequestDto" } } } }, "responses": { "201": { "description": "API key successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyWithTokenDto" } } } }, "400": { "description": "Bad request - invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - missing or invalid authentication." }, "403": { "description": "Forbidden - user lacks permission to create API keys or scopes." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai": { "post": { "tags": [ "AI Management" ], "summary": "Create New AI", "description": "Creates a new AI specified by the given identifier.", "operationId": "createAI", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AICreateRequest" } } } }, "responses": { "200": { "description": "Details of the specified AI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIDetail" } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "AI not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/import": { "post": { "tags": [ "AI Management" ], "summary": "Import Agent", "description": "Creates a new agent from a portable AgentBundle. Tool secrets can be supplied via the secrets map. Skills are imported only when the caller has SKILLS WRITE permission; otherwise they are skipped with a warning. If the bundle model is unavailable, the first available model is substituted and a warning is returned.", "operationId": "importAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportAgentRequest" } } } }, "responses": { "201": { "description": "Agent successfully imported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportAgentResponse" } } } }, "400": { "description": "Invalid request body or model ID." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}": { "get": { "tags": [ "AI Management" ], "summary": "Get AI Details", "description": "Retrieves details of the AI specified by the given identifier.", "operationId": "getAIDetails", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI whose details are to be retrieved.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the specified AI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIDetail" } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "AI not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "AI Management" ], "summary": "Update AI", "description": "Updates an agent. Not a sparse patch: name, description and instructions are required on every call, and omitting other fields does not preserve them. Changing modelId revalidates the model against the agents surface. Listing an agent in the Network Catalog requires instance-level write; listing it in the Tenant Catalog requires tenant owner organization admin. Requires AI WRITE, and the caller must own the agent, hold organization, tenant or instance write over it, or have been granted edit access.", "operationId": "updateAI", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the agent.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIUpdateRequest" } } } }, "responses": { "200": { "description": "The updated agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIDetail" } } } }, "400": { "description": "Bad request — missing name, description or instructions, an invalid modelId, or a model disabled for agents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — the caller cannot edit this agent, or cannot grant the requested catalog listing or visibility.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "AI Management" ], "summary": "Delete AI", "description": "Soft-deletes an agent and removes its data source links, permissions, tools and group links. Requires AI WRITE with the same ownership or edit-access rules as update.", "operationId": "deleteAI", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the agent.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Agent deleted. Empty body." }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — the caller cannot delete this agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/export": { "get": { "tags": [ "AI Management" ], "summary": "Export Agent", "description": "Exports an agent and its configuration as a portable AgentBundle JSON document. Secrets are stripped from tool configurations and listed in requiredSecrets. Skills are included only when the caller has SKILLS READ permission. Organization-scoped callers can export agents in their org; instance-level callers can export across orgs.", "operationId": "exportAgent", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the agent to export.", "schema": { "type": "string" } }, { "name": "includeDataSources", "in": "query", "required": false, "description": "Whether to include data sources in the export. Defaults to true.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" } }, { "name": "dataSourceIds", "in": "query", "required": false, "description": "Comma-separated list of specific data source IDs to include. When provided, only the listed data sources are exported.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent bundle exported successfully.", "headers": { "Content-Disposition": { "description": "Attachment filename derived from the agent name.", "schema": { "type": "string", "example": "attachment; filename=\"my-agent.json\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBundle" } } } }, "400": { "description": "AI ID is required." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Agent not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/approve": { "put": { "tags": [ "AI Management" ], "summary": "Approve an AI", "description": "Marks an AI as approved by the organization.", "operationId": "approveAI", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI to be approved.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "AI successfully approved." }, "401": { "description": "Missing authorization context. User must be authenticated." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "AI not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/chats": { "get": { "tags": [ "Chat Sessions" ], "summary": "Get all chats for the AI", "description": "Retrieves a list of all chat sessions associated with the given AI identifier.", "operationId": "getAIChats", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI whose chats are to be retrieved.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of chat sessions associated with the AI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChatsResponse" } } } }, "404": { "description": "AI not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Chat Sessions" ], "summary": "Create a new chat session for the AI", "description": "Creates a new chat session associated with the given AI identifier and returns the created chat session data.", "operationId": "createAIChat", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI with which the chat session is to be associated.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Chat session successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSummary" } } } }, "404": { "description": "Not found, when the specified AI ID does not exist or is not visible to the current user." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources": { "get": { "tags": [ "Data Sources" ], "summary": "List data sources for the AI", "description": "Retrieves a list of data sources associated with the given AI identifier.", "operationId": "listAIDataSources", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI whose data sources are to be retrieved.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of data sources associated with the AI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDataSourcesResponse" } } } }, "404": { "description": "AI not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Data Sources" ], "summary": "Add an existing data source to the specified AI", "description": "Associates an existing data source with the specified AI.", "operationId": "addDataSourceToAI", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The unique identifier for the AI to which the data source is to be added.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dataSourceId": { "type": "string", "description": "The unique identifier of the existing data source to be added." } }, "required": [ "dataSourceId" ] } } } }, "responses": { "201": { "description": "Data source successfully added to the AI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAIDataSourceResponse" } } } }, "400": { "description": "Bad request, malformed request syntax or invalid request message framing." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Not Found, either of the specified AI or data source are not found." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Data Sources" ], "summary": "Delete all data sources from the AI", "description": "Requests deletion of all data sources associated with the specified AI.", "operationId": "deleteAllAIDataSources", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI whose data sources are to be deleted.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Delete request accepted." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "AI not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/api": { "post": { "tags": [ "Data Sources" ], "summary": "Create a new API data source for the specified AI", "description": "Adds a new API data source with a specified name and JSON payload for the given AI.", "operationId": "createApiDataSource", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The unique identifier for the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the data source." }, "data": { "type": "object", "description": "The JSON payload to be used as the data source's knowledge." } }, "required": [ "name", "data" ] } } } }, "responses": { "201": { "description": "Data source successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSource" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AI not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/file": { "post": { "tags": [ "Data Sources" ], "summary": "Adds a file upload data source for the specified AI. Max file size: 4.5Mb.", "parameters": [ { "in": "path", "name": "aiId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the AI." } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "File uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSource" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AI not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/file-blob": { "post": { "tags": [ "Data Sources" ], "summary": "Initialize a file-blob upload for the AI", "description": "Generates a signed upload token for Vercel Blob and creates the data source after upload.", "operationId": "createFileBlobDataSource", "parameters": [ { "in": "path", "name": "aiId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the AI." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Upload token created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VercelBlobUploadResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/web-urls": { "post": { "tags": [ "Data Sources" ], "summary": "Create a web URL data source for the AI", "description": "Creates a web URL knowledge source and associates it with the AI.", "operationId": "createWebUrlDataSource", "parameters": [ { "in": "path", "name": "aiId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the AI." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebUrlDataSourceInput" } } } }, "responses": { "201": { "description": "Data source created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSource" } } } }, "403": { "description": "Forbidden - web URL data source requires a paid plan." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/google-drive": { "post": { "tags": [ "Data Sources" ], "summary": "Create Google Drive data sources for the AI", "description": "Creates Google Drive knowledge sources and associates them with the AI.", "operationId": "createGoogleDriveDataSources", "parameters": [ { "in": "path", "name": "aiId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the AI." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGoogleDriveKnowledgeRequest" } } } }, "responses": { "201": { "description": "Data sources created." }, "400": { "description": "Bad request" }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/onedrive": { "post": { "tags": [ "Data Sources" ], "summary": "Create a OneDrive data source for the AI", "description": "Creates a OneDrive knowledge source and associates it with the AI.", "operationId": "createOneDriveDataSource", "parameters": [ { "in": "path", "name": "aiId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the AI." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOneDriveKnowledgeRequest" } } } }, "responses": { "201": { "description": "Data source created." }, "400": { "description": "Bad request" }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/confluence": { "post": { "tags": [ "Data Sources" ], "summary": "Create a Confluence data source for the AI", "description": "Creates a Confluence knowledge source and associates it with the AI.", "operationId": "createConfluenceDataSource", "parameters": [ { "in": "path", "name": "aiId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the AI." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConfluenceKnowledgeRequest" } } } }, "responses": { "201": { "description": "Data source created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSource" } } } }, "403": { "description": "Forbidden - Confluence data source requires a paid plan." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/jira": { "post": { "tags": [ "Data Sources" ], "summary": "Create a Jira data source for the AI", "description": "Creates a Jira knowledge source and associates it with the AI.", "operationId": "createJiraDataSource", "parameters": [ { "in": "path", "name": "aiId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the AI." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJiraKnowledgeRequest" } } } }, "responses": { "201": { "description": "Data source created." }, "403": { "description": "Forbidden - Jira data source requires a paid plan." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/github": { "post": { "tags": [ "Data Sources" ], "summary": "Create a GitHub data source for the AI", "description": "Creates a GitHub knowledge source and associates it with the AI.", "operationId": "createGithubDataSource", "parameters": [ { "in": "path", "name": "aiId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the AI." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGithubKnowledgeRequest" } } } }, "responses": { "201": { "description": "Data source created." }, "403": { "description": "Forbidden - GitHub data source requires a paid plan." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/{dataSourceId}": { "delete": { "tags": [ "Data Sources" ], "summary": "Remove a data source from the AI", "description": "Removes the specified data source from the AI.", "operationId": "removeAIDataSource", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } }, { "name": "dataSourceId", "in": "path", "required": true, "description": "The identifier of the data source to remove.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Data source removed." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "AI or data source not found." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/data-sources/delete": { "post": { "tags": [ "Data Sources" ], "summary": "Delete multiple data sources from the AI", "description": "Bulk delete data sources by ID for the specified AI.", "operationId": "deleteAIDataSources", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAIDataSourcesRequest" } } } }, "responses": { "204": { "description": "Delete request accepted." }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden, the user is not authorized to perform this action." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/revoke": { "put": { "tags": [ "AI Management" ], "summary": "Revoke AI approval", "description": "Revokes the organization approval for an AI.", "operationId": "revokeAIApproval", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI whose approval is to be revoked.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "AI approval successfully revoked." }, "401": { "description": "Missing authorization context. User must be authenticated." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "AI not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools": { "get": { "tags": [ "Tools" ], "summary": "List tools for the AI", "description": "Retrieves all tools associated with the specified AI.", "operationId": "listAITools", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tools for the AI.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "AI not found with the given identifier." } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tools" ], "summary": "Create a tool for the AI", "description": "Creates a new tool and associates it with the specified AI.", "operationId": "createAITool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateApiToolRequest" }, { "$ref": "#/components/schemas/CreateUserInputToolRequest" }, { "$ref": "#/components/schemas/CreateKnowledgeRetrievalToolRequest" }, { "$ref": "#/components/schemas/CreateWebSearchToolRequest" }, { "$ref": "#/components/schemas/CreateImageGenerationToolRequest" }, { "$ref": "#/components/schemas/CreateSpreadsheetToolRequest" }, { "$ref": "#/components/schemas/CreateMcpServerToolRequest" }, { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ToolType" } }, "required": [ "type" ] } ] } } } }, "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden, the user is not authorized to perform this action." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/{toolId}": { "get": { "tags": [ "Tools" ], "summary": "Get a tool for the AI", "description": "Retrieves details for a specific tool associated with the AI.", "operationId": "getAITool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } }, { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tool details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "AI or tool not found." } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Tools" ], "summary": "Update a tool for the AI", "description": "Updates supported tool types (e.g., spreadsheet, web search).", "operationId": "updateAITool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } }, { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateSpreadsheetToolRequest" }, { "$ref": "#/components/schemas/UpdateWebSearchToolRequest" } ] } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden, the user is not authorized to perform this action." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Tools" ], "summary": "Delete a tool", "description": "Deletes the specified tool from the AI.", "operationId": "deleteAITool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } }, { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Tool deleted." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/api-function": { "get": { "tags": [ "Tools" ], "summary": "List API function tools for the AI", "description": "Retrieves API function tools associated with the AI.", "operationId": "listApiFunctionTools", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of API function tools.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolListResponse" } } } }, "404": { "description": "AI not found." } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tools" ], "summary": "Create an API function tool", "description": "Creates an API function tool and associates it with the AI.", "operationId": "createApiFunctionTool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiToolRequest" } } } }, "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/{toolId}/api-function": { "put": { "tags": [ "Tools" ], "summary": "Update an API function tool", "description": "Updates an API function tool associated with the AI.", "operationId": "updateApiFunctionTool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } }, { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiToolRequest" } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/python": { "get": { "tags": [ "Tools" ], "summary": "List Python tools for the AI", "description": "Retrieves Python tools associated with the AI.", "operationId": "listPythonTools", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of Python tools.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tools" ], "summary": "Create a Python tool", "description": "Creates a Python tool and associates it with the AI.", "operationId": "createPythonTool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/user-input": { "get": { "tags": [ "Tools" ], "summary": "List user input tools for the AI", "description": "Retrieves user input tools associated with the AI.", "operationId": "listUserInputTools", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of user input tools.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tools" ], "summary": "Create a user input tool", "description": "Creates a user input tool and associates it with the AI.", "operationId": "createUserInputTool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserInputToolRequest" } } } }, "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/knowledge-retrieval": { "get": { "tags": [ "Tools" ], "summary": "List knowledge retrieval tools for the AI", "description": "Retrieves knowledge retrieval tools associated with the AI.", "operationId": "listKnowledgeRetrievalTools", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of knowledge retrieval tools.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tools" ], "summary": "Create a knowledge retrieval tool", "description": "Creates a knowledge retrieval tool and associates it with the AI.", "operationId": "createKnowledgeRetrievalTool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeRetrievalToolRequest" } } } }, "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/image-generation": { "get": { "tags": [ "Tools" ], "summary": "List image generation tools for the AI", "description": "Retrieves image generation tools associated with the AI.", "operationId": "listImageGenerationTools", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of image generation tools.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tools" ], "summary": "Create an image generation tool", "description": "Creates an image generation tool and associates it with the AI.", "operationId": "createImageGenerationTool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImageGenerationToolRequest" } } } }, "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/mcp": { "get": { "tags": [ "Tools" ], "summary": "List MCP server tools for the AI", "description": "Retrieves MCP server tools associated with the AI.", "operationId": "listMcpServerTools", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of MCP server tools.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tools" ], "summary": "Create an MCP server tool", "description": "Creates an MCP server tool and associates it with the AI.", "operationId": "createMcpServerTool", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMcpServerToolRequest" } } } }, "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/auth": { "get": { "tags": [ "Tools" ], "summary": "List tool OAuth status for the AI", "description": "Lists OAuth token status information for tools associated with the AI.", "operationId": "listAIToolAuthStatus", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tool OAuth status list.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToolAuthInfo" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/tools/auth/reset": { "put": { "tags": [ "Tools" ], "summary": "Reset tool OAuth tokens for the AI", "description": "Deletes tool OAuth tokens for the AI.", "operationId": "resetAIToolAuth", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth tokens deleted.", "content": { "application/json": { "schema": { "type": "string" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/user-inputs": { "get": { "tags": [ "AI User Inputs" ], "summary": "List AI user inputs", "description": "Retrieves configured user inputs for the AI.", "operationId": "listAIUserInputs", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of user inputs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAIUserInputsResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "AI User Inputs" ], "summary": "Create an AI user input", "description": "Creates a user input field for the AI.", "operationId": "createAIUserInput", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAIUserInputRequest" } } } }, "responses": { "201": { "description": "User input created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIUserInput" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/user-inputs/{userInputId}": { "put": { "tags": [ "AI User Inputs" ], "summary": "Update an AI user input", "description": "Updates a configured user input for the AI.", "operationId": "updateAIUserInput", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } }, { "name": "userInputId", "in": "path", "required": true, "description": "The identifier of the user input.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAIUserInputRequest" } } } }, "responses": { "200": { "description": "User input updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIUserInput" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "AI User Inputs" ], "summary": "Delete an AI user input", "description": "Deletes a configured user input from the AI.", "operationId": "deleteAIUserInput", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } }, { "name": "userInputId", "in": "path", "required": true, "description": "The identifier of the user input.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "User input deleted." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/user-inputs/order": { "put": { "tags": [ "AI User Inputs" ], "summary": "Reorder AI user inputs", "description": "Updates the order of configured user inputs for the AI.", "operationId": "updateAIUserInputsOrder", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAIUserInputsOrderRequest" } } } }, "responses": { "200": { "description": "Order updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAIUserInputsOrderResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/embed": { "get": { "tags": [ "AI Embed" ], "summary": "Get embedded client configuration", "description": "Retrieves the embedded client configuration for the AI.", "operationId": "getEmbeddedClient", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Embedded client configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedClient" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "AI Embed" ], "summary": "Update embedded client configuration", "description": "Updates the embedded client configuration for the AI.", "operationId": "updateEmbeddedClient", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedClientConfig" } } } }, "responses": { "200": { "description": "Embedded client updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedClient" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/embed/generate": { "put": { "tags": [ "AI Embed" ], "summary": "Generate an embedded client key", "description": "Generates a new embedded client key for the AI.", "operationId": "generateEmbeddedClientKey", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Embedded client created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedClient" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/generate-profile": { "put": { "tags": [ "AI Management" ], "summary": "Generate AI profile", "description": "Generates an AI profile based on existing AI data.", "operationId": "generateAIProfile", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "AI profile generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIProfile" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai/{aiId}/share": { "put": { "tags": [ "AI Management" ], "summary": "Share an AI", "description": "Shares the AI with the provided emails.", "operationId": "shareAI", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareAIRequest" } } } }, "responses": { "200": { "description": "AI shared." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/chats/{chatId}": { "get": { "tags": [ "Chat Sessions" ], "summary": "Get a chat session", "description": "Retrieves the chat session with the specified ID.", "operationId": "getChat", "parameters": [ { "name": "chatId", "in": "path", "required": true, "description": "The unique identifier of the chat session to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chat session successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatDetails" } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Not found, when the specified chat ID does not exist." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Chat Sessions" ], "summary": "Message a chat session", "description": "Send a message to a chat session with an AI.", "operationId": "postChatSession", "parameters": [ { "name": "chatId", "in": "path", "required": true, "description": "The unique identifier of the chat session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "description": "The date and time of the chat from the perspective of the user. This may be different from the server time for the AI. Defaults to server time if not provided." }, "prompt": { "oneOf": [ { "type": "string", "description": "A simple text message to send to the AI." }, { "$ref": "#/components/schemas/ComplexMessageContent", "description": "A complex message with text and file references. Upload files first using the /api/v1/chats/{chatId}/files endpoint, then reference them by ID." } ], "description": "Message to send to the AI. Can be a string for simple text messages, or a ComplexMessageContent array that includes text and file references (images, documents, audio, video)." }, "modelId": { "type": "string", "description": "Optional model ID to override the AI's default model for this request." }, "options": { "$ref": "#/components/schemas/ChatOptions", "description": "Optional chat options such as flow overrides and tracing." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/PostToChatRequestTool" }, "description": "Array of tools to enable for this chat request. Each tool can be a built-in tool type (e.g. web_search, python), an image generation tool with model configuration, an MCP server tool reference, or an OpenAI-compatible function tool definition." }, "userSecrets": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional key-value map of user-provided secrets that may be required by tools (e.g. API keys for authenticated tool calls)." } }, "required": [ "prompt" ] }, "examples": { "simpleText": { "summary": "Simple text message", "value": { "date": "2024-01-15T10:30:00Z", "prompt": "Hello, how are you?", "tools": [] } }, "withWebSearch": { "summary": "Message with web search tool enabled", "value": { "date": "2024-01-15T10:30:00Z", "prompt": "What are the latest AI news?", "tools": [ { "type": "web_search" } ] } }, "withImage": { "summary": "Message with an image file", "description": "First upload the image using POST /api/v1/chats/{chatId}/files, then use the returned file ID in the prompt.", "value": { "date": "2024-01-15T10:30:00Z", "prompt": [ { "type": "text", "text": "What's in this image?" }, { "type": "image", "id": "file_abc123", "metadata": { "detail": "high", "width": 1024, "height": 768 } } ], "tools": [] } }, "withDocument": { "summary": "Message with a document file", "description": "Upload a PDF or other document, then reference it in your message.", "value": { "date": "2024-01-15T10:30:00Z", "prompt": [ { "type": "text", "text": "Summarize this document" }, { "type": "document", "id": "file_xyz789", "metadata": { "filename": "report.pdf" } } ], "tools": [] } }, "withFunctionTool": { "summary": "Message with an OpenAI-compatible function tool", "description": "Define a function tool that the AI can call. The tool call is returned to the client for execution; the server does not execute it.", "value": { "date": "2024-01-15T10:30:00Z", "prompt": "What is the weather in London?", "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get the current weather for a location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City name" } }, "required": [ "location" ] } } } ] } }, "withModelOverride": { "summary": "Message with model override", "value": { "date": "2024-01-15T10:30:00Z", "prompt": "Explain quantum computing", "modelId": "gpt-4o", "tools": [] } }, "withMultipleTools": { "summary": "Message with multiple tools enabled", "value": { "date": "2024-01-15T10:30:00Z", "prompt": "Search the web and generate an image of a sunset", "tools": [ { "type": "web_search" }, { "type": "image_generation", "modelId": "dall-e-3", "size": "1024x1024", "quality": "standard" } ] } } } } } }, "responses": { "200": { "description": "SSE stream of chat events", "content": { "text/event-stream": { "schema": { "type": "object", "description": "Server-sent events", "properties": { "message.created": { "$ref": "#/components/schemas/MessageCreatedChatEvent", "description": "Emitted when a new message is created" }, "message.delta": { "$ref": "#/components/schemas/MessageDeltaChatEvent", "description": "Emitted for incremental message updates" }, "tool.call": { "$ref": "#/components/schemas/ToolCallChatEvent", "description": "Emitted when a tool is called" }, "message.complete": { "$ref": "#/components/schemas/MessageCompleteChatEvent", "description": "Emitted when a message is completed" }, "message.error": { "$ref": "#/components/schemas/MessageErrorChatEvent", "description": "Emitted when a message error occurs" }, "tool.message": { "$ref": "#/components/schemas/ToolMessageChatEvent", "description": "Emitted for tool execution messages" }, "error": { "$ref": "#/components/schemas/ErrorChatEvent", "description": "Emitted on stream errors" }, "history.compressed": { "type": "object", "description": "Emitted when chat history is compressed to reduce context size. Contains the compression summary message.", "properties": { "type": { "type": "string", "enum": [ "history.compressed" ] }, "message": { "$ref": "#/components/schemas/ChatMessage" } } }, "closed": { "type": "object", "description": "Emitted when the stream is closed" } } } } } }, "400": { "description": "Bad request, when the request body does not contain the required fields or contains invalid data." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Not found, when the specified chat ID does not exist." }, "429": { "description": "Rate limit exceeded. The user has sent too many messages." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Chat Sessions" ], "summary": "Delete a chat session", "description": "Deletes the chat session with the specified ID.", "operationId": "deleteChat", "parameters": [ { "name": "chatId", "in": "path", "required": true, "description": "The unique identifier of the chat session to delete.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Chat session successfully deleted, no content to return." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Not Found, the specified chat ID does not exist." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/chats/{chatId}/duplicate": { "put": { "tags": [ "Chat Sessions" ], "summary": "Duplicate a chat session", "description": "Creates a duplicate of the chat session with the specified ID.", "operationId": "duplicateChat", "parameters": [ { "name": "chatId", "in": "path", "required": true, "description": "The unique identifier of the chat session to duplicate.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chat session successfully duplicated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatDetails" } } } }, "400": { "description": "Bad request, when the request contains invalid data." }, "404": { "description": "Not found, when the specified chat ID does not exist." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/chats/{chatId}/reset": { "put": { "tags": [ "Chat Sessions" ], "summary": "Reset a chat session", "description": "Resets the chat session with the specified ID, clearing its current state or content.", "operationId": "resetChat", "parameters": [ { "name": "chatId", "in": "path", "required": true, "description": "The unique identifier of the chat session to reset.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chat session successfully reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatDetails" } } } }, "404": { "description": "Not found, when the specified chat ID does not exist." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/chats/{chatId}/tool-output": { "post": { "tags": [ "Chat Sessions" ], "summary": "Submit tool outputs (e.g., input field responses)", "description": "When the AI requests user input through tool calls (e.g., asking the user to fill in form fields), use this endpoint to submit the user's responses. The AI will receive these outputs and continue the conversation. Listen for 'tool.call' events in the chat stream to know when input is needed.", "operationId": "submitToolOutput", "parameters": [ { "name": "chatId", "in": "path", "required": true, "description": "The unique identifier of the chat session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitToolOutputRequest" }, "examples": { "singleInput": { "summary": "Submit a single input field response", "description": "Example of submitting a user's name when the AI requests it.", "value": { "systemMessageId": "msg_abc123", "outputs": [ { "toolCallId": "call_xyz789", "status": "success", "output": "John Doe" } ] } }, "multipleInputs": { "summary": "Submit multiple input field responses", "description": "Example of submitting multiple form fields at once.", "value": { "systemMessageId": "msg_abc123", "outputs": [ { "toolCallId": "call_name", "status": "success", "output": "John Doe" }, { "toolCallId": "call_email", "status": "success", "output": "john@example.com" }, { "toolCallId": "call_age", "status": "success", "output": "30" } ] } } } } } }, "responses": { "200": { "description": "SSE stream of chat events. The AI will process the submitted inputs and continue the conversation.", "content": { "text/event-stream": { "schema": { "type": "object", "description": "Server-sent events stream (same format as POST /api/v1/chats/{chatId})" } } } }, "400": { "description": "Bad request - Missing required fields, invalid tool call IDs, or outputs don't match requested tool calls." }, "403": { "description": "Forbidden, the user is not authorized to access this chat." }, "404": { "description": "Chat not found with the given identifier." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/chats/{chatId}/files": { "post": { "tags": [ "Files" ], "summary": "Upload a file to a chat session", "description": "Uploads a file that can be referenced in messages sent to this chat. Max file size: 5MB. After uploading, use the returned file ID to reference it in the prompt field using ComplexMessageContent.", "operationId": "uploadChatFile", "parameters": [ { "name": "chatId", "in": "path", "required": true, "description": "The unique identifier of the chat session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload." }, "source": { "type": "string", "enum": [ "USER", "SYSTEM" ], "deprecated": true, "description": "Deprecated and ignored. Uploads through this endpoint are always recorded as USER, so they count against the per-chat attachment limit and are covered by attachment sanitization. SYSTEM files are created by server-side flows (generated images, tool outputs), never by this endpoint. Still accepted for backward compatibility." } } } } } }, "responses": { "201": { "description": "File successfully uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDto" } } } }, "400": { "description": "Bad request - No file found or invalid file data." }, "403": { "description": "Forbidden, the user is not authorized to upload files to this chat." }, "404": { "description": "Chat not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "tags": [ "Files" ], "summary": "List files in a chat session", "description": "Retrieves a list of all files associated with the specified chat session.", "operationId": "listChatFiles", "parameters": [ { "name": "chatId", "in": "path", "required": true, "description": "The unique identifier of the chat session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of files in the chat session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesResponseDto" } } } }, "400": { "description": "Bad request - Chat ID required." }, "403": { "description": "Forbidden, the user is not authorized to access this chat." }, "404": { "description": "Chat not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/data-sources": { "get": { "tags": [ "Data Sources" ], "summary": "List all data sources", "description": "Retrieves a list of data sources associated which the user has access to.", "operationId": "listDataSources", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Search term for data sources.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by data source type.", "schema": { "$ref": "#/components/schemas/DataSourceType" } }, { "name": "orderBy", "in": "query", "required": false, "description": "Order by field and direction. Prefix field name with '+' for ascending or '-' for descending order. Allowed fields: createdAt, lastIndexedAt, usageCount.", "schema": { "type": "string", "pattern": "^[+-](createdAt|lastIndexedAt|usageCount)$" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for paginated results.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A list of all data sources which the user has access to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDataSourceWithAiDetailsResponse" } } } }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/data-sources/{dataSourceId}": { "patch": { "tags": [ "Data Sources" ], "summary": "Update a Data Source", "description": "Updates properties for the specified data source.", "operationId": "updateDataSource", "parameters": [ { "name": "dataSourceId", "in": "path", "required": true, "description": "The unique identifier of the data source to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDataSourceRequest" } } } }, "responses": { "200": { "description": "Data source updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSource" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Not Found, the specified data source ID does not exist." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Data Sources" ], "summary": "Delete a Data Source", "description": "Deletes a specific data source associated with the given AI identifier.", "operationId": "deleteDataSource", "parameters": [ { "name": "dataSourceId", "in": "path", "required": true, "description": "The unique identifier of the data source to be deleted.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Data source successfully deleted, no content to return." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Not Found, the specified data source ID does not exist." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/data-sources/{dataSourceId}/refresh": { "put": { "tags": [ "Data Sources" ], "summary": "Refresh a Data Source", "description": "This endpoint refreshes the specified data source.", "operationId": "refreshDataSource", "parameters": [ { "name": "dataSourceId", "in": "path", "required": true, "description": "The unique identifier of the data source to be refreshed.", "schema": { "type": "string" } }, { "in": "query", "name": "forceRefresh", "description": "Indicates if the data source should be refreshed even if the content has not been updated", "schema": { "type": "boolean" } } ], "responses": { "202": { "description": "Request has been accepted for processing." }, "401": { "description": "Missing authorization context. User must be authenticated." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Data source not found with the specified ID." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/data-sources/{dataSourceId}/stats": { "get": { "tags": [ "Data Sources" ], "summary": "Get data source stats", "description": "Retrieves indexing statistics for the specified data source.", "operationId": "getDataSourceStats", "parameters": [ { "name": "dataSourceId", "in": "path", "required": true, "description": "The unique identifier of the data source.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Data source stats.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceKnowledgeStats" } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Data source not found." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/data-sources/{dataSourceId}/knowledge": { "get": { "tags": [ "Data Sources" ], "summary": "List knowledge items for a data source", "description": "Retrieves paginated knowledge items for the specified data source.", "operationId": "listDataSourceKnowledge", "parameters": [ { "name": "dataSourceId", "in": "path", "required": true, "description": "The unique identifier of the data source.", "schema": { "type": "string" } }, { "name": "first", "in": "query", "required": false, "description": "Number of items to return.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor for pagination.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated knowledge results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetKnowledgeResponse" } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Data source not found." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/data-sources/{dataSourceId}/knowledge/{knowledgeId}": { "patch": { "tags": [ "Data Sources" ], "summary": "Update a knowledge item", "description": "Updates a knowledge item for the specified data source.", "operationId": "updateKnowledgeItem", "parameters": [ { "name": "dataSourceId", "in": "path", "required": true, "description": "The unique identifier of the data source.", "schema": { "type": "string" } }, { "name": "knowledgeId", "in": "path", "required": true, "description": "The identifier of the knowledge item.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeRequest" } } } }, "responses": { "200": { "description": "Knowledge item updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Knowledge" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Data source or knowledge item not found." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}": { "get": { "tags": [ "Tools" ], "summary": "Get a tool", "description": "Retrieves a tool by ID.", "operationId": "getTool", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tool details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Tool not found." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Tools" ], "summary": "Delete a tool", "description": "Deletes the specified tool.", "operationId": "deleteTool", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Tool deleted." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}/user-input": { "put": { "tags": [ "Tools" ], "summary": "Update a user input tool", "description": "Updates the user input tool configuration.", "operationId": "updateUserInputTool", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserInputToolRequest" } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}/knowledge-retrieval": { "put": { "tags": [ "Tools" ], "summary": "Update a knowledge retrieval tool", "description": "Updates the knowledge retrieval tool configuration.", "operationId": "updateKnowledgeRetrievalTool", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeRetrievalToolRequest" } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}/image-generation": { "put": { "tags": [ "Tools" ], "summary": "Update an image generation tool", "description": "Updates the image generation tool configuration.", "operationId": "updateImageGenerationTool", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateImageGenerationToolRequest" } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}/mcp": { "put": { "tags": [ "Tools" ], "summary": "Update an MCP server tool", "description": "Updates the MCP server tool configuration.", "operationId": "updateMcpServerTool", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMcpServerToolRequest" } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}/api-function": { "put": { "tags": [ "Tools" ], "summary": "Update an API function tool", "description": "Updates the API function tool configuration.", "operationId": "updateApiFunctionToolGlobal", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiToolRequest" } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}/api-function/callback": { "get": { "tags": [ "Tools" ], "summary": "API function tool OAuth callback", "description": "Handles OAuth callbacks for API function tools.", "operationId": "apiFunctionToolCallback", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": true, "description": "Authorization code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Callback handled.", "content": { "application/json": { "schema": { "type": "string" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}/oauth-status": { "get": { "tags": [ "Tools" ], "summary": "Get tool OAuth status", "description": "Checks whether a tool has an active OAuth token.", "operationId": "getToolOAuthStatus", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth status for the tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolOAuthStatus" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}/oauth-token": { "delete": { "tags": [ "Tools" ], "summary": "Delete a tool OAuth token", "description": "Revokes the OAuth token for the specified tool.", "operationId": "deleteToolOAuthToken", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Token deleted." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/{toolId}/oauth-initiate": { "post": { "tags": [ "Tools" ], "summary": "Initiate tool OAuth flow", "description": "Generates an authorization URL for tool OAuth.", "operationId": "initiateToolOAuth", "parameters": [ { "name": "toolId", "in": "path", "required": true, "description": "The identifier of the tool.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authorization URL generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthInitiateResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tools/mcp/preview": { "post": { "tags": [ "Tools" ], "summary": "Preview MCP server tools", "description": "Previews available tools from an MCP server or template.", "operationId": "previewMcpServerTools", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewMcpServerToolRequest" } } } }, "responses": { "200": { "description": "Preview results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewMcpServerToolResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/secrets": { "get": { "tags": [ "Secrets" ], "summary": "List secrets", "description": "Lists secrets for the organization or a specific AI.", "operationId": "listSecrets", "parameters": [ { "name": "aiId", "in": "query", "required": false, "description": "Filter secrets by AI ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of secrets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Secret" } } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Secrets" ], "summary": "Create a secret", "description": "Creates a secret for the organization or a specific AI.", "operationId": "createSecret", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretRequest" } } } }, "responses": { "201": { "description": "Secret created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Secret" } } } }, "403": { "description": "Forbidden, the user is not authorized to perform this action." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/secrets/{secretId}": { "put": { "tags": [ "Secrets" ], "summary": "Update a secret", "description": "Updates an existing secret.", "operationId": "updateSecret", "parameters": [ { "name": "secretId", "in": "path", "required": true, "description": "The identifier of the secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSecretRequest" } } } }, "responses": { "200": { "description": "Secret updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Secret" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Secrets" ], "summary": "Delete a secret", "description": "Deletes the specified secret.", "operationId": "deleteSecret", "parameters": [ { "name": "secretId", "in": "path", "required": true, "description": "The identifier of the secret.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Secret deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/ai-models": { "get": { "tags": [ "AI Models" ], "summary": "List AI models", "description": "Retrieves available AI models.", "operationId": "listAIModels", "responses": { "200": { "description": "List of AI models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIModelListResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/categories": { "get": { "tags": [ "Categories" ], "summary": "List tenant categories", "description": "Retrieves available tenant categories for AI assignment.", "operationId": "listTenantCategories", "parameters": [ { "name": "orgId", "in": "query", "required": false, "description": "Optional org ID for superusers.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tenant categories.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantCategory" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/org-subscriptions/{publicId}": { "get": { "tags": [ "Subscriptions" ], "summary": "Get an organization subscription by public ID", "description": "Retrieves an organization subscription by its public subscription identifier. Callers must have organization, tenant, or instance-level read permission on organization subscriptions. When that requirement is met, the subscription is returned only if it exists and the caller is permitted to read that specific subscription; otherwise the API responds with 404 so clients cannot infer whether a given public ID exists.", "operationId": "getOrgSubscriptionByPublicId", "parameters": [ { "name": "publicId", "in": "path", "required": true, "description": "Public subscription identifier.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Organization subscription details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSubscriptionDto" } } } }, "400": { "description": "Invalid public subscription identifier." }, "403": { "description": "Forbidden. The caller does not have organization, tenant, or instance-level permission to read organization subscriptions, so this endpoint cannot be used." }, "404": { "description": "No subscription is returned. This status is used for an unknown public ID, no matching subscription, or when the caller is not allowed to read the requested subscription (same response shape in the latter case to avoid revealing whether the subscription exists)." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/org-tool-templates": { "get": { "tags": [ "Tool Templates" ], "summary": "List organization tool templates", "description": "Retrieves tool templates available for the organization.", "operationId": "listOrgToolTemplates", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of templates to return.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Tool templates list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgToolTemplateSearchResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/org-tool-templates/{id}": { "get": { "tags": [ "Tool Templates" ], "summary": "Get an organization tool template", "description": "Retrieves details for a specific organization tool template.", "operationId": "getOrgToolTemplate", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The template identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tool template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgToolTemplate" } } } }, "404": { "description": "Template not found." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/google-drive/accounts": { "get": { "tags": [ "Integrations" ], "summary": "List Google Drive accounts", "description": "Retrieves Google Drive OAuth accounts for the current user.", "operationId": "listGoogleDriveAccounts", "responses": { "200": { "description": "List of Google Drive accounts.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserOAuthToken" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/onedrive/accounts": { "get": { "tags": [ "Integrations" ], "summary": "List OneDrive accounts", "description": "Retrieves OneDrive OAuth accounts for the current user.", "operationId": "listOneDriveAccounts", "responses": { "200": { "description": "List of OneDrive accounts.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserOAuthToken" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/onedrive/accounts/{id}": { "delete": { "tags": [ "Integrations" ], "summary": "Disconnect a OneDrive account", "description": "Deletes the specified OneDrive OAuth token.", "operationId": "deleteOneDriveAccount", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The OAuth token ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account disconnected.", "content": { "application/json": { "schema": { "type": "string" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/onedrive/search": { "post": { "tags": [ "Integrations" ], "summary": "Search OneDrive content", "description": "Searches OneDrive files and folders.", "operationId": "searchOneDrive", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSearchRequest" } } } }, "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/onedrive/children": { "post": { "tags": [ "Integrations" ], "summary": "List OneDrive folder children", "description": "Retrieves child items for a OneDrive folder.", "operationId": "listOneDriveChildren", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationItemRequest" } } } }, "responses": { "200": { "description": "Children list.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/onedrive/sharepoint": { "post": { "tags": [ "Integrations" ], "summary": "List SharePoint children", "description": "Retrieves child items for a SharePoint site.", "operationId": "listSharePointChildren", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationItemRequest" } } } }, "responses": { "200": { "description": "SharePoint children list.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/confluence/accounts": { "get": { "tags": [ "Integrations" ], "summary": "List Confluence accounts", "description": "Retrieves Confluence OAuth accounts for the current user.", "operationId": "listConfluenceAccounts", "responses": { "200": { "description": "List of Confluence accounts.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserOAuthToken" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/confluence/search": { "post": { "tags": [ "Integrations" ], "summary": "Search Confluence content", "description": "Searches Confluence content for selection.", "operationId": "searchConfluence", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSearchRequest" } } } }, "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/jira/accounts": { "get": { "tags": [ "Integrations" ], "summary": "List Jira accounts", "description": "Retrieves Jira OAuth accounts for the current user.", "operationId": "listJiraAccounts", "responses": { "200": { "description": "List of Jira accounts.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserOAuthToken" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/jira/search": { "post": { "tags": [ "Integrations" ], "summary": "Search Jira projects", "description": "Searches Jira projects for selection.", "operationId": "searchJira", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSearchRequest" } } } }, "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/github/accounts": { "get": { "tags": [ "Integrations" ], "summary": "List GitHub accounts", "description": "Retrieves GitHub OAuth accounts for the current user.", "operationId": "listGitHubAccounts", "responses": { "200": { "description": "List of GitHub accounts.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserOAuthToken" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/me/integrations/github/installs": { "get": { "tags": [ "Integrations" ], "summary": "List GitHub app installations", "description": "Retrieves GitHub app installations for the current user.", "operationId": "listGitHubAppInstallations", "responses": { "200": { "description": "GitHub app installations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubAppInstallationsResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/github/search": { "post": { "tags": [ "Integrations" ], "summary": "Search GitHub repositories", "description": "Searches GitHub repositories accessible to an installation.", "operationId": "searchGitHubRepositories", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubRepositorySearchRequest" } } } }, "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedExternalGitHubRepositoryResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/github/preview": { "post": { "tags": [ "Integrations" ], "summary": "Preview GitHub repository", "description": "Previews repository content for selection.", "operationId": "previewGitHubRepository", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubPreviewRequest" } } } }, "responses": { "200": { "description": "Preview results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubPreviewResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/groups": { "post": { "tags": [ "Groups" ], "summary": "Create a new group", "description": "Creates a new group with the specified details.", "operationId": "createGroup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the group." }, "availability": { "$ref": "#/components/schemas/GroupAvailability" }, "memberEmails": { "type": "string", "description": "A comma-separated list of emails of users who should be added to the group." } }, "required": [ "name", "availability", "memberEmails" ] } } } }, "responses": { "200": { "description": "Group successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupDetail" } } } }, "401": { "description": "Missing authorization context. User must be authenticated." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/groups/{groupId}": { "put": { "tags": [ "Groups" ], "summary": "Update a group", "description": "Updates the details of a specific group and manages its member list.", "operationId": "updateGroup", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The unique identifier of the group to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the group." }, "availability": { "$ref": "#/components/schemas/GroupAvailability" }, "memberEmailsToAdd": { "type": "string", "description": "A comma-separated list of emails of users to be added to the group." }, "memberEmailsToRemove": { "type": "array", "items": { "type": "string" }, "description": "A comma-separated list of emails of users to be removed from the group." } } } } } }, "responses": { "200": { "description": "Group details updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupDetail" } } } }, "400": { "description": "Bad request, when the input data is invalid." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Not found, when the specified group ID does not exist." }, "500": { "description": "Internal Server Error." } } }, "delete": { "tags": [ "Groups" ], "summary": "Delete a group", "description": "Deletes the group with the specified identifier.", "operationId": "deleteGroup", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The unique identifier of the group to delete.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Group successfully deleted, no content to return." }, "400": { "description": "Bad request, when the request is malformed." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Not found, when the specified group ID does not exist." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/groups/{groupId}/leave": { "put": { "tags": [ "Groups" ], "summary": "Leave a group", "description": "Allows the current user to leave the group specified by the groupId.", "operationId": "leaveGroup", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The unique identifier of the group to leave.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Successfully left the group, no content to return." }, "400": { "description": "Bad request, when the request is malformed." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "404": { "description": "Not found, when the specified group ID does not exist." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/me/ai": { "get": { "tags": [ "AI Management" ], "summary": "List AIs", "parameters": [ { "in": "query", "name": "scope", "schema": { "$ref": "#/components/schemas/ListAIsRequestScope" }, "description": "The scope to filter results by" }, { "in": "query", "name": "groupId", "schema": { "type": "string" }, "description": "The id of a group to filter results by" }, { "in": "query", "name": "categoryId", "schema": { "type": "string" }, "description": "The id of a category to filter results by" }, { "in": "query", "name": "approvedByOrg", "schema": { "type": "boolean" }, "description": "Filter results by whether the AI has been approved by the organization." }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search term" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AIDetail" } } } } } } } } } }, "/api/v1/me/chats": { "get": { "tags": [ "Chat Sessions" ], "summary": "Get all chats for the User", "description": "Retrieves a list of all chat sessions associated with the current user", "operationId": "getChats", "responses": { "200": { "description": "A list of chat sessions associated with the AI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChatsResponse" } } } }, "404": { "description": "AI not found with the given identifier." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/me/groups": { "get": { "tags": [ "Groups" ], "summary": "Get groups of the current user", "description": "Retrieves a list of groups associated with the current user.", "operationId": "getUserGroups", "responses": { "200": { "description": "A list of groups associated with the current user.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GroupSummary" } } } } }, "401": { "description": "Missing authorization context. User must be authenticated." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "500": { "description": "Internal Server Error." } } } }, "/api/v1/usage/ai": { "get": { "tags": [ "Usage & Analytics" ], "summary": "Get organization usage metrics by AI", "description": "Returns the usage metrics of the organization broken down by AI.", "operationId": "getOrgUsageByAI", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgUsageByAI" } } } }, "404": { "description": "Organization not found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/usage/org": { "get": { "tags": [ "Usage & Analytics" ], "summary": "Get organization usage metrics", "description": "Returns usage metrics for the organization.", "operationId": "getOrgUsage", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgUsage" } } } }, "401": { "description": "Missing authorization context. User must be authenticated." }, "403": { "description": "Forbidden, the user is not authorized to perform this action." }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/files": { "post": { "tags": [ "Files" ], "summary": "Create a file record or upload a file", "description": "This endpoint supports two modes: 1) Create a file record with metadata (application/json), or 2) Upload a file directly (multipart/form-data). When creating a record, you'll need to upload the actual file separately. When uploading directly, the file is uploaded immediately.", "operationId": "createOrUploadFile", "requestBody": { "required": true, "description": "This endpoint supports two modes: Create a file record with metadata (application/json), or upload a file directly (multipart/form-data).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFileRequestDto" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload directly." } } } } } }, "responses": { "201": { "description": "File successfully created or uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDto" } } } }, "400": { "description": "Bad request - Missing required fields or invalid file data." }, "403": { "description": "Forbidden, the user is not authorized to upload files." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/chat/completions": { "post": { "tags": [ "Chat Completions" ], "summary": "Create a chat completion (OpenAI-compatible)", "description": "Creates a completion for the chat message. This endpoint is OpenAI-compatible and supports both regular prompts and tool output submissions. When the last message is a tool message, it will be treated as a tool output submission.", "operationId": "createChatCompletionV2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Server-sent events stream", "properties": { "message.created": { "$ref": "#/components/schemas/MessageCreatedChatEvent" }, "message.delta": { "$ref": "#/components/schemas/MessageDeltaChatEvent" }, "tool.call": { "$ref": "#/components/schemas/ToolCallChatEvent" }, "message.complete": { "$ref": "#/components/schemas/MessageCompleteChatEvent" }, "message.error": { "$ref": "#/components/schemas/MessageErrorChatEvent" }, "tool.message": { "$ref": "#/components/schemas/ToolMessageChatEvent" }, "error": { "$ref": "#/components/schemas/ErrorChatEvent" } } } } } }, "400": { "description": "Bad request - Invalid input (e.g. missing messages, invalid model, last message must be user or tool, duplicate custom function names, or custom function names conflicting with reserved internal tool names)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication" }, "403": { "description": "Forbidden - User does not have permission to access this resource" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/chats/completions": { "post": { "tags": [ "Chat Completions" ], "summary": "Create a chat completion (Deprecated)", "description": "**Deprecated:** This endpoint is deprecated. Please use `/api/v1/chat/completions` instead, which follows the OpenAI API convention and provides the same functionality.", "operationId": "createChatCompletion", "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "type": "object", "description": "Server-sent events stream", "properties": { "message.created": { "$ref": "#/components/schemas/MessageCreatedChatEvent" }, "message.delta": { "$ref": "#/components/schemas/MessageDeltaChatEvent" }, "tool.call": { "$ref": "#/components/schemas/ToolCallChatEvent" }, "message.complete": { "$ref": "#/components/schemas/MessageCompleteChatEvent" }, "message.error": { "$ref": "#/components/schemas/MessageErrorChatEvent" }, "tool.message": { "$ref": "#/components/schemas/ToolMessageChatEvent" }, "error": { "$ref": "#/components/schemas/ErrorChatEvent" } } } } } }, "400": { "description": "Bad request - Invalid input (e.g. missing messages, invalid model, duplicate custom function names, or custom function names conflicting with reserved internal tool names)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication" }, "403": { "description": "Forbidden - User does not have permission to access this resource" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v2/responses": { "post": { "operationId": "createResponse", "summary": "Create a response", "description": "Submit a prompt and receive a model response. When `stream=true` (default),\nreturns an SSE event stream following the OpenAI Responses streaming format.\nWhen `stream=false`, returns the completed response as JSON.\n\n**Execution modes:**\n- **Threaded**: when `previous_response_id` or `conversation` is provided.\n Signals a long-lived Temporal `ThreadWorkflow` that processes requests sequentially.\n- **Stateless**: when neither `previous_response_id` nor `conversation` is set.\n Starts a one-shot `SingleResponseWorkflow`.\n\nResponse headers include `x-response-id`, `x-response-status`, and, for streaming responses, `x-stream-epoch`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponseRequest" } } } }, "responses": { "200": { "description": "When `stream=true`: SSE event stream. When `stream=false`: completed Response object.\n", "headers": { "x-response-id": { "schema": { "type": "string" }, "description": "Unique response run identifier." }, "x-response-status": { "schema": { "type": "string" }, "description": "Initial response status." }, "x-stream-chat-id": { "schema": { "type": "string" }, "description": "**[devs.ai extension]** Set on streaming responses (`stream=true`). Equals the underlying chat-stream identifier and can be passed as `streamChatId` to `GET /api/v2/responses/{responseId}/stream` to reconnect after a network drop. Equal to `x-response-id`.", "x-devs-ai-extension": true }, "x-stream-epoch": { "schema": { "type": "string" }, "description": "**[devs.ai extension]** Redis stream epoch for reconnect handshakes. Persist this with `lastSequence` and pass it as `streamEpoch` to `GET /api/v2/responses/{responseId}/stream`.", "x-devs-ai-extension": true } }, "content": { "text/event-stream": { "schema": { "description": "SSE event stream. See Streaming Events section.", "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request (missing model, invalid file references, schema validation failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Responses API v2" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v2/responses/{responseId}": { "get": { "operationId": "getResponse", "summary": "Get a response", "description": "Retrieve a response run by ID. Returns the full response object including\noutput items, usage, and status.\n", "parameters": [ { "$ref": "#/components/parameters/responseId" } ], "responses": { "200": { "description": "Response object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Response not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Responses API v2" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v2/responses/{responseId}/stream": { "get": { "operationId": "streamResponse", "summary": "Reconnect to an in-flight response stream", "description": "**[devs.ai extension]** Re-attach to a still-running response's SSE event stream after a network drop. The path parameter `responseId` and the required query parameter `streamChatId` MUST be equal — `streamChatId` exists for explicit client-side intent and to align with the underlying chat-stream backend.\n\nWhen `lastSequence` is supplied, events with `sequence_number <= lastSequence` are suppressed so the client receives only events it has not yet seen. The first event delivered is therefore typically `response.in_progress` (or whatever event follows `lastSequence`), NOT `response.created`.\n\nThis endpoint has no equivalent in OpenAI's Responses API.\n\nReturns `404` when the run cannot be found, `streamChatId` does not equal `responseId`, or the underlying stream has already completed and can no longer be reattached.\n", "x-devs-ai-extension": true, "parameters": [ { "$ref": "#/components/parameters/responseId" }, { "name": "streamChatId", "in": "query", "required": true, "description": "**[devs.ai extension]** Must equal the path `responseId`. Identifies the underlying chat-stream to attach to.", "schema": { "type": "string", "minLength": 1 }, "x-devs-ai-extension": true }, { "name": "lastSequence", "in": "query", "required": false, "description": "**[devs.ai extension]** Last `sequence_number` the client has already processed. Events with `sequence_number <= lastSequence` are suppressed. Default `-1` (no events suppressed).", "schema": { "type": "integer", "minimum": -1, "default": -1 }, "x-devs-ai-extension": true } ], "responses": { "200": { "description": "SSE event stream identical in shape to the create-response stream (see Streaming Events section).", "headers": { "x-response-id": { "schema": { "type": "string" }, "description": "Echoed response run identifier." }, "x-stream-chat-id": { "schema": { "type": "string" }, "description": "**[devs.ai extension]** Echoed `streamChatId` query parameter.", "x-devs-ai-extension": true } }, "content": { "text/event-stream": { "schema": { "description": "SSE event stream. See Streaming Events section.", "type": "string" } } } }, "404": { "description": "Response not found, `streamChatId` does not match `responseId`, or the underlying stream has already completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Responses API v2" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v2/responses/{responseId}/cancel": { "post": { "operationId": "cancelResponse", "summary": "Cancel a response", "description": "Cancel an active response run. Only works for threaded execution mode.\nIdempotent — returns success if the response is already in a terminal state.\nSends a `CANCEL_ACTIVE_REQUEST` signal to the Temporal workflow.\n", "parameters": [ { "$ref": "#/components/parameters/responseId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResponseRequest" } } } }, "responses": { "200": { "description": "Cancel requested (or already terminal)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlResponse" } } } }, "404": { "description": "Response not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not a threaded response (stateless responses cannot be cancelled via this endpoint)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Responses API v2" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v2/responses/{responseId}/pause": { "post": { "operationId": "pauseResponse", "summary": "Pause a response", "description": "**[devs.ai extension]** Pause an active response run. Execution halts at the next safe checkpoint;\nin-flight work completes but no new model or tool steps are started.\nThe response becomes incomplete with incomplete_details.reason set to paused,\nand can be continued via POST /api/v2/responses/{responseId}/resume.\nOnly works for threaded execution mode. No equivalent in OpenAI's Responses API.\n", "x-devs-ai-extension": true, "parameters": [ { "$ref": "#/components/parameters/responseId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseResponseRequest" } } } }, "responses": { "200": { "description": "Pause requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlResponse" } } } }, "404": { "description": "Response not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not a threaded response or already terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Responses API v2" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v2/responses/{responseId}/resume": { "post": { "operationId": "resumeResponse", "summary": "Resume a response", "description": "**[devs.ai extension]** Resume a paused response run. Optionally provide tool outputs for\nhuman-in-the-loop tool calling (function tools that require client execution).\nOnly works for threaded execution mode. No equivalent in OpenAI's Responses API.\n", "x-devs-ai-extension": true, "parameters": [ { "$ref": "#/components/parameters/responseId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeResponseRequest" } } } }, "responses": { "200": { "description": "Resume requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlResponse" } } } }, "404": { "description": "Response not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not a threaded response or already terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Responses API v2" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v2/responses/{responseId}/deep-research/resume": { "post": { "operationId": "resumeDeepResearch", "summary": "Resume a deep research subagent", "description": "**[devs.ai extension]** Resume a paused deep research child workflow. Used to approve, deny,\nor provide clarification for a deep research run that is awaiting\nhuman input. Signals the deep research subagent workflow directly. No equivalent in OpenAI's Responses API.\n", "x-devs-ai-extension": true, "parameters": [ { "$ref": "#/components/parameters/responseId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeDeepResearchRequest" } } } }, "responses": { "200": { "description": "Resume requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchControlResponse" } } } }, "404": { "description": "Response not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Response is already terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Responses API v2" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/rate-limits/block": { "post": { "tags": [ "Tenant Rate Limits" ], "summary": "Block organization rate limits", "description": "Sets a BLOCKED override for the specified child organization. Caller must be the tenant owner organization with org settings write access.", "operationId": "blockOrgRateLimit", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization rate limits blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgRateLimitSimpleModeResponseDto" } } } }, "400": { "description": "Bad request - invalid path parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - missing or invalid authentication." }, "403": { "description": "Forbidden - caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not Found - organization does not exist or is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/rate-limits/override": { "get": { "tags": [ "Tenant Rate Limits" ], "summary": "Get organization rate limit override status", "description": "Returns effective rate limit mode and whether an explicit override exists for the organization.", "operationId": "getOrgRateLimitOverride", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current override and effective mode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgRateLimitOverrideResponseDto" } } } }, "400": { "description": "Bad request - invalid path parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - missing or invalid authentication." }, "403": { "description": "Forbidden - caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not Found - organization does not exist or is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Tenant Rate Limits" ], "summary": "Clear organization rate limit override", "description": "Removes any explicit BLOCKED or UNLIMITED override so the tenant default applies.", "operationId": "clearOrgRateLimitOverride", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Override cleared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgRateLimitSimpleModeResponseDto" } } } }, "400": { "description": "Bad request - invalid path parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - missing or invalid authentication." }, "403": { "description": "Forbidden - caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not Found - organization does not exist or is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/rate-limits/unblock": { "post": { "tags": [ "Tenant Rate Limits" ], "summary": "Unblock organization rate limits", "description": "Sets an UNLIMITED override for the specified child organization. Caller must be the tenant owner organization with org settings write access.", "operationId": "unblockOrgRateLimit", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization rate limits set to unlimited override.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgRateLimitSimpleModeResponseDto" } } } }, "400": { "description": "Bad request - invalid path parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - missing or invalid authentication." }, "403": { "description": "Forbidden - caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not Found - organization does not exist or is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/rate-limits/default": { "get": { "tags": [ "Tenant Rate Limits" ], "summary": "Get tenant default rate limit mode", "description": "Returns the default rate limit mode applied to child organizations when no per-org override exists. Only the tenant owner organization may call this.", "operationId": "getTenantDefaultRateLimit", "responses": { "200": { "description": "Tenant default configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDefaultRateLimitResponseDto" } } } }, "401": { "description": "Unauthorized - missing or invalid authentication." }, "403": { "description": "Forbidden - caller is not the tenant owner organization." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Tenant Rate Limits" ], "summary": "Set tenant default rate limit mode", "description": "Updates the default rate limit mode for child organizations. Only the tenant owner organization may call this.", "operationId": "setTenantDefaultRateLimit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTenantDefaultRateLimitRequestDto" } } } }, "responses": { "200": { "description": "Updated tenant default configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDefaultRateLimitResponseDto" } } } }, "400": { "description": "Bad request - invalid body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - missing or invalid authentication." }, "403": { "description": "Forbidden - caller is not the tenant owner organization." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/rate-limits/overrides": { "get": { "tags": [ "Tenant Rate Limits" ], "summary": "List tenant rate limit overrides", "description": "Paginated list of organizations with an explicit BLOCKED or UNLIMITED override. Only the tenant owner organization may call this.", "operationId": "listTenantRateLimitOverrides", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous response pagination.nextCursor.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Page of override rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTenantRateLimitOverridesResponseDto" } } } }, "400": { "description": "Bad request - invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - missing or invalid authentication." }, "403": { "description": "Forbidden - caller is not the tenant owner organization." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/create": { "post": { "tags": [ "Tenant Administration" ], "summary": "Create tenant organization", "description": "Creates a child organization under the tenant and returns the org ID and resolved admin user ID. When the tenant has subscription billing management enabled, the org is created without an automatic paid subscription (FREE bootstrap) so step 2 is POST .../subscription. Requires ORG_SETTINGS WRITE with a tenant-scoped API key from the tenant-owner org.", "operationId": "createTenantOrganization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantOrganizationRequestDto" } } } }, "responses": { "201": { "description": "Organization created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantOrganizationResponseDto" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/subscription": { "get": { "tags": [ "Tenant Administration" ], "summary": "Get organization subscription", "description": "Returns the active subscription for the target org. Poll after async create/patch/cancel operations. Reconcile cancellation on cancelledAt (status may remain ACTIVE until period close). Requires ORG_SUBSCRIPTIONS READ.", "operationId": "getTenantOrgSubscription", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Active subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSubscriptionDto" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tenant Administration" ], "summary": "Create organization subscription", "description": "Starts the subscription-created workflow (202 Accepted, empty body). Requires X-Idempotency-Key. Returns 403 when subscriptionBillingManagementEnabled is false on the tenant. Returns 409 when the org already has an active non-FREE subscription. Replay with the same idempotency key returns 202 again. Requires ORG_SUBSCRIPTIONS WRITE.", "operationId": "createTenantOrgSubscription", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantOrgSubscriptionRequestDto" } } } }, "responses": { "202": { "description": "Subscription creation accepted (async workflow)." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "Tenant Administration" ], "summary": "Update organization subscription", "description": "Updates plan, seats, or external identifiers. Entitlement changes run via async workflow (202, empty body). Trivial field-only edits may return 200 with OrgSubscriptionDto. Requires X-Idempotency-Key and ORG_SUBSCRIPTIONS WRITE. Returns 403 when subscriptionBillingManagementEnabled is false.", "operationId": "patchTenantOrgSubscription", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchTenantOrgSubscriptionRequestDto" } } } }, "responses": { "200": { "description": "Subscription updated synchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSubscriptionDto" } } } }, "202": { "description": "Subscription change accepted (async workflow)." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Tenant Administration" ], "summary": "Cancel organization subscription", "description": "Starts the cancel lifecycle workflow (202 Accepted, empty body). Sets cancelledAt while status may remain ACTIVE until period close. Requires X-Idempotency-Key. Optional request body for provenance metadata. Requires ORG_SUBSCRIPTIONS WRITE. Returns 403 when subscriptionBillingManagementEnabled is false.", "operationId": "cancelTenantOrgSubscription", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XIdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelTenantOrgSubscriptionRequestDto" } } } }, "responses": { "202": { "description": "Cancellation accepted (async workflow)." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/billing/balances": { "get": { "tags": [ "Tenant Administration" ], "summary": "List organization balances", "description": "Returns current included and extra balances per balance type. Requires BILLING_BALANCES READ.", "operationId": "getTenantOrgBalances", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization balances.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgBalanceDto" } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tenant Administration" ], "summary": "Top up organization balance", "description": "Credits the org balance (positive amounts only). Requires X-Idempotency-Key mapped to the ledger referenceId; replays return alreadyRecorded: true. Partner convention: balanceType CHAT and targetColumn EXTRA for purchased credits. Requires BILLING_BALANCES WRITE. Returns 403 when subscriptionBillingManagementEnabled is false.", "operationId": "topUpTenantOrgBalance", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/XIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantAdjustBalanceRequestDto" } } } }, "responses": { "201": { "description": "Balance credited (or idempotent replay).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustBalanceResponseDto" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/billing/balances/ledger": { "get": { "tags": [ "Tenant Administration" ], "summary": "List organization balance ledger", "description": "Paginated ledger entries for reconciliation. Requires BILLING_BALANCES READ.", "operationId": "getTenantOrgBalanceLedger", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "name": "balanceType", "in": "query", "schema": { "$ref": "#/components/schemas/BalanceTypeDto" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "entryType", "in": "query", "schema": { "$ref": "#/components/schemas/LedgerEntryTypeDto" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Ledger page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceLedgerPageDto" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/billing/invoices": { "get": { "tags": [ "Tenant Administration" ], "summary": "List organization invoices", "description": "Paginated invoices for the org subscription. Requires BILLING_INVOICES READ.", "operationId": "listTenantOrgInvoices", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Invoice page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePageDto" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/billing/allocations": { "get": { "tags": [ "Tenant Administration" ], "summary": "List organization allocation limits", "description": "Returns org-level monthly/daily allocation limits per balance type. Requires BILLING_ALLOCATIONS READ.", "operationId": "getTenantOrgAllocations", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Allocation limits.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgAllocationDto" } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/members": { "get": { "tags": [ "Tenant Administration" ], "summary": "List organization members", "description": "Paginated member list for seat reconciliation. Requires ORG_SETTINGS READ.", "operationId": "listTenantOrgMembers", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Member page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOrganizationMembersPageDto" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/invitations": { "get": { "tags": [ "Tenant Administration" ], "summary": "List organization invitations", "description": "Paginated invitation list for reconciliation. Requires ORG_SETTINGS READ.", "operationId": "listTenantOrgInvitations", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "accepted", "revoked" ], "default": "pending" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Invitation page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOrganizationInvitationsPageDto" } } } }, "400": { "description": "Bad request." }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found." }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Tenant Administration" ], "summary": "Invite organization member", "description": "Sends an invitation email to add a member by email. Seat caps enforced. Requires ORG_SETTINGS WRITE.", "operationId": "inviteTenantOrgMember", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantOrganizationInvitationRequestDto" } } } }, "responses": { "201": { "description": "Invitation sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOrganizationInvitationSuccessDto" } } } }, "400": { "description": "Bad request." }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found." }, "409": { "description": "Conflict — seat cap exceeded." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/members/{userId}": { "put": { "tags": [ "Tenant Administration" ], "summary": "Update organization member", "description": "Updates role and/or membership type. At least one field required. Requires ORG_SETTINGS WRITE.", "operationId": "updateTenantOrgMember", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "Target user ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantOrganizationMemberRequestDto" } } } }, "responses": { "200": { "description": "Member updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMemberUpdateSuccessDto" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Tenant Administration" ], "summary": "Unassign organization member", "description": "Removes membership and cancels seat assignment. Idempotent: returns 204 even if the member was already removed. Requires ORG_SETTINGS WRITE. Uses a Redis-backed lock; returns 503 when Redis is unavailable. Returns 400 when another deletion is already in progress for the org.", "operationId": "unassignTenantOrgMember", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "Target user ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Member unassigned (or already absent)." }, "400": { "description": "Bad request — e.g. another member deletion is already in progress for this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication." }, "403": { "description": "Forbidden — caller is not the tenant owner or cannot access this organization." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable — member deletion requires Redis for the concurrency lock.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/roles": { "get": { "tags": [ "Roles" ], "summary": "List roles", "description": "Lists built-in and custom roles with their permission sets. The organization comes from the API key unless orgId is supplied. Requires ROLES READ at organization or instance level; tenant-level access alone is not accepted.", "operationId": "listRoles", "parameters": [ { "name": "orgId", "in": "query", "required": false, "description": "Target organization ID. Defaults to the caller's organization. Cross-organization targeting requires INSTANCE access, or TENANT access where the target organization belongs to the caller's tenant.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Roles for the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRolesResponseDto" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing ROLES READ, or orgId targets an organization the caller cannot reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Roles" ], "summary": "Create a custom role", "description": "Creates a custom role. Requires ROLES WRITE at organization or instance level. Permissions that the platform reserves for superusers are dropped silently, so confirm the created role's permissions in the response.", "operationId": "createRole", "parameters": [ { "name": "orgId", "in": "query", "required": false, "description": "Target organization ID. Defaults to the caller's organization. Cross-organization targeting requires INSTANCE access, or TENANT access where the target organization belongs to the caller's tenant.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleRequestDto" } } } }, "responses": { "201": { "description": "The created role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRoleDto" } } } }, "400": { "description": "Bad request — invalid JSON, failed validation, or no grantable permission left after filtering.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing ROLES WRITE, or orgId targets an organization the caller cannot reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict — a role with this name already exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/roles/{roleId}": { "put": { "tags": [ "Roles" ], "summary": "Update a role", "description": "Updates a role's name, description or permissions. Supplying permissions replaces the existing set rather than merging. The built-in Admin role cannot be modified; the built-in User role can be, but no other system role can. Requires ROLES WRITE.", "operationId": "updateRole", "parameters": [ { "name": "roleId", "in": "path", "required": true, "description": "Public identifier of the role, as returned in CustomRoleDto.id.", "schema": { "type": "string" } }, { "name": "orgId", "in": "query", "required": false, "description": "Target organization ID. Defaults to the caller's organization. Cross-organization targeting requires INSTANCE access, or TENANT access where the target organization belongs to the caller's tenant.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleRequestDto" } } } }, "responses": { "200": { "description": "The updated role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRoleDto" } } } }, "400": { "description": "Bad request — invalid JSON, no fields supplied, or no grantable permission left after filtering.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing ROLES WRITE, or the role is a protected system role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Role not found in the target organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict — another role in the organization already uses that name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Roles" ], "summary": "Delete a custom role", "description": "Soft-deletes a custom role, first unassigning it from every user in the organization. The built-in Admin and User roles cannot be deleted, nor can any other system role. Requires ROLES WRITE.", "operationId": "deleteRole", "parameters": [ { "name": "roleId", "in": "path", "required": true, "description": "Public identifier of the role, as returned in CustomRoleDto.id.", "schema": { "type": "string" } }, { "name": "orgId", "in": "query", "required": false, "description": "Target organization ID. Defaults to the caller's organization. Cross-organization targeting requires INSTANCE access, or TENANT access where the target organization belongs to the caller's tenant.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Role deleted. Empty body." }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing ROLES WRITE, or the role is a protected system role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Role not found in the target organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/api-keys/{apiKeyId}": { "put": { "tags": [ "API Keys" ], "summary": "Update an API key", "description": "Renames a key and replaces its scope list. The key must belong to the calling user in the calling organization. Scopes the caller does not hold are dropped, and the response reflects what was actually saved. The secret token is never returned here. Requires API_KEYS WRITE.", "operationId": "updateApiKey", "parameters": [ { "name": "apiKeyId", "in": "path", "required": true, "description": "Identifier of the API key.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRequestDto" } } } }, "responses": { "200": { "description": "The updated key metadata, without the token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDto" } } } }, "400": { "description": "Bad request — invalid JSON or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — the key belongs to another user or organization, or none of the requested scopes may be granted by the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "API Keys" ], "summary": "Delete an API key", "description": "Permanently deletes a key belonging to the calling user in the calling organization. Requires API_KEYS WRITE. Note that deleting a key that does not exist, or belongs to someone else, currently reports 500 rather than 404.", "operationId": "deleteApiKey", "parameters": [ { "name": "apiKeyId", "in": "path", "required": true, "description": "Identifier of the API key.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Key deleted. Empty body." }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing API_KEYS WRITE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error, including the case where no matching key exists for this user and organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/api-keys/{apiKeyId}/reset": { "post": { "tags": [ "API Keys" ], "summary": "Reset an API key", "description": "Rotates the key's secret and returns the new token. The previous token stops working immediately, and the new one is shown only in this response, so capture it before discarding the result. The key must belong to the calling user in the calling organization. Requires API_KEYS WRITE.", "operationId": "resetApiKey", "parameters": [ { "name": "apiKeyId", "in": "path", "required": true, "description": "Identifier of the API key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The key metadata together with the new plaintext token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyWithTokenDto" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — the key belongs to another user or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/organizations/api-keys": { "get": { "tags": [ "API Keys" ], "summary": "List organization API keys", "description": "Lists every API key in the caller's organization as a bare array; this endpoint is not paginated and takes no query parameters. Tokens are never included. Requires API_KEYS or ORG_SETTINGS READ at tenant, organization or instance level. A caller whose API_KEYS access is only tenant-level sees just the keys carrying a tenant scope.", "operationId": "listOrganizationApiKeys", "responses": { "200": { "description": "API keys in the organization, without tokens.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyDto" } } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — the caller has no organization-level or instance-level read over API keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/organizations/api-keys/{apiKeyId}": { "delete": { "tags": [ "API Keys" ], "summary": "Revoke an organization API key", "description": "Revokes any key in the caller's organization, including keys belonging to other users. Unlike the user-scoped delete, this returns 200 with a body rather than 204. Requires API_KEYS or ORG_SETTINGS WRITE at tenant, organization or instance level.", "operationId": "revokeOrganizationApiKey", "parameters": [ { "name": "apiKeyId", "in": "path", "required": true, "description": "Identifier of the API key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Key revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeOrgApiKeyResponseDto" } } } }, "400": { "description": "Bad request — the key exists but belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — insufficient scope, or a tenant-scoped caller targeting a key without a tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/org-settings": { "get": { "tags": [ "Organization Settings" ], "summary": "Get organization settings", "description": "Returns the organization's settings. The response is filtered to what the caller may read: full org-settings read returns every field, while a caller holding only app-branding, app-integrations or app-deploy-approvals receives just that slice. Tenant callers read a child organization by passing orgId.", "operationId": "getOrgSettings", "parameters": [ { "name": "orgId", "in": "query", "required": false, "description": "Target organization ID. Defaults to the caller's organization. Cross-organization targeting requires INSTANCE access, or TENANT access where the target organization belongs to the caller's tenant.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization settings, filtered by read permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSettingsDto" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — no read access to any settings group, or orgId targets an organization outside the caller's tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Organization Settings" ], "summary": "Upsert organization settings", "description": "Replaces the organization's settings. This is a whole-object upsert rather than a per-field patch: the required fields must be present on every call, so read the settings first and send the modified object back. Optional fields you omit keep their current values, and fields you are not permitted to write are silently left unchanged instead of returning an error, so compare the response against what you sent. The target organization is taken from the body's orgId. Requires write access on the relevant settings group at tenant, organization or instance level.", "operationId": "upsertOrgSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOrgSettingsRequestDto" } } } }, "responses": { "201": { "description": "The saved settings, filtered by read permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSettingsDto" } } } }, "400": { "description": "Bad request — invalid JSON, a missing required field, an unknown property, or legacy orgPrompt sent alongside orgPromptConfig.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required — App Builder branding, integration policies or deploy approvals need an entitlement this organization lacks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — no write access to the settings group, orgId is outside the caller's tenant, or tenant policy blocks child organization branding overrides.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/org-memberships": { "get": { "tags": [ "Organization Members" ], "summary": "List organization members", "description": "Returns a cursor-paginated page of members along with the roles available in the organization and current seat usage. The invitations array is always empty here. Callers without roles read permission see empty role lists and isClerkAdmin false. Requires USERS READ at organization, tenant or instance level.", "operationId": "listOrgMemberships", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 10; values above 100 are capped at 100.", "schema": { "type": "integer", "minimum": 1, "default": 10 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from pagination.nextCursor of the previous page.", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "search", "in": "query", "required": false, "description": "Free-text match on member name or email.", "schema": { "type": "string", "minLength": 1 } }, { "name": "seatTier", "in": "query", "required": false, "description": "Filter by membership type.", "schema": { "$ref": "#/components/schemas/OrgMembershipTypeDto" } }, { "name": "roleId", "in": "query", "required": false, "description": "Filter by assigned role. Ignored unless the caller may read roles for the target organization.", "schema": { "type": "string", "minLength": 1 } }, { "name": "orgId", "in": "query", "required": false, "description": "Target organization ID. Defaults to the caller's organization. Cross-organization targeting requires INSTANCE access, or TENANT access where the target organization belongs to the caller's tenant.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of members with roles and seat usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgMembersPageDto" } } } }, "400": { "description": "Bad request — invalid or unknown query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing USERS READ, or orgId targets an organization outside the caller's tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/org-memberships/invitations": { "post": { "tags": [ "Organization Members" ], "summary": "Invite members to an organization", "description": "Invites up to 100 email addresses in one call. Addresses that already belong to the organization or already have a pending invitation are skipped, so a successful call can report invitedCount 0. Seat availability is checked before sending. Assigning an admin role also requires roles write permission. Requires USERS WRITE at organization, tenant or instance level. Organizations billed through AppDirect cannot invite members here. Sending more than 100 billable invitations in an hour is rate limited, and that response is plain text rather than JSON.", "operationId": "createOrgMemberInvitations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgMemberInvitationsRequestDto" } } } }, "responses": { "201": { "description": "Invitations processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgMemberInvitationsResponseDto" } } } }, "400": { "description": "Bad request — invalid JSON, failed validation, or insufficient seats.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing USERS WRITE, an AppDirect-managed organization, or an admin role assignment without roles write permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests — the organization has exceeded 100 billable invitations in the last hour. The body is plain text, not JSON.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}": { "get": { "tags": [ "Tenant Administration" ], "summary": "Get child organization", "description": "Returns the child organization's name and logo from the identity provider. This is not the settings object; use /api/v1/org-settings with orgId for that. Requires ORG_SETTINGS READ at tenant or instance level, and the organization must belong to the caller's tenant.", "operationId": "getTenantOrganization", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The child organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOrganizationDto" } } } }, "400": { "description": "Bad request — organization ID missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — caller is not a tenant owner, or the organization belongs to another tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found, deleted, or absent from the identity provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Tenant Administration" ], "summary": "Update child organization name or logo", "description": "Updates a child organization's display name and logo. The body is multipart/form-data, not JSON, and at least one of name, logo or removeLogo must be present. Sending both logo and removeLogo applies the new logo and ignores the removal. This route covers name and logo only; plan tier, region and limits are not settable here. Requires ORG_SETTINGS WRITE at tenant or instance level.", "operationId": "updateTenantOrganization", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "description": "At least one of name, logo or removeLogo is required.", "properties": { "name": { "type": "string", "maxLength": 256, "description": "New display name. Trimmed, and must not be empty after trimming." }, "logo": { "type": "string", "format": "binary", "description": "PNG, JPEG or WebP image of 5 MB or less." }, "removeLogo": { "type": "string", "enum": [ "true" ], "description": "Send the string true to delete the current logo. Any other value is ignored." } } } } } }, "responses": { "200": { "description": "The updated organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOrganizationDto" } } } }, "400": { "description": "Bad request — no fields supplied, an empty or over-long name, an unsupported image type, or a logo larger than 5 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — caller is not a tenant owner, or the organization belongs to another tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error, including identity provider failures.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Tenant Administration" ], "summary": "Detach child organization from the tenant", "description": "Removes the organization's tenant association by clearing its tenant ID. This is not a deprovision: the organization, its users and its data all survive, and the identity provider record is untouched. The tenant's own owner organization cannot be detached, nor can an organization that owns another tenant. Requires ORG_SETTINGS WRITE at tenant or instance level.", "operationId": "detachTenantOrganization", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Organization detached from the tenant. Empty body." }, "400": { "description": "Bad request — the target is the tenant's owner organization, or it owns another tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — caller is not a tenant owner, or the organization belongs to another tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tenant/organizations/{orgId}/invitations/{invitationId}": { "delete": { "tags": [ "Tenant Administration" ], "summary": "Revoke organization invitation", "description": "Revokes a pending invitation. This is not idempotent: the invitation state is not checked locally before the call is forwarded to the identity provider, so revoking an invitation that was already accepted or never existed surfaces as a 500 rather than a 404. Requires ORG_SETTINGS WRITE at tenant or instance level. Organizations billed through AppDirect cannot revoke invitations here.", "operationId": "revokeTenantOrganizationInvitation", "parameters": [ { "name": "orgId", "in": "path", "required": true, "description": "Target organization ID (must belong to the tenant).", "schema": { "type": "string" } }, { "name": "invitationId", "in": "path", "required": true, "description": "Identifier of the invitation to revoke.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Invitation revoked. Empty body." }, "400": { "description": "Bad request — organization ID missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — caller is not a tenant owner, the organization belongs to another tenant, or the organization is AppDirect-managed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found or deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error, including an invitation that is already accepted or does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "tags": [ { "name": "AI Management", "description": "Create, retrieve, and manage AI assistants" }, { "name": "Chat Sessions", "description": "Manage chat sessions and send messages to AI assistants" }, { "name": "Data Sources", "description": "Manage knowledge bases and data sources for AI assistants" }, { "name": "API Keys", "description": "Create and manage API keys" }, { "name": "Groups", "description": "Manage user groups for AI access control" }, { "name": "Usage & Analytics", "description": "Monitor organization and AI usage metrics" }, { "name": "Files", "description": "Upload and manage files for chat sessions" }, { "name": "Chat Completions", "description": "OpenAI-compatible chat completion API" }, { "name": "Responses API v2", "description": "OpenAI Responses-compatible API (v2). Supports streaming (SSE) and non-streaming runs, threaded and stateless execution, and lifecycle control (cancel / pause / resume).\n\nThe shape mirrors the [official OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) for inputs, outputs, tools, and streaming events. Items below labelled **[devs.ai extension]** have no equivalent in OpenAI's spec; everything else is intended to be 1:1 compatible.\n\n### Vendor extensions used to flag devs.ai additions\n\nEvery devs.ai-specific element in this spec is also tagged with a machine-readable [OpenAPI specification extension](https://swagger.io/docs/specification/openapi-extensions/) so tooling can detect them programmatically without parsing description text:\n\n- **`x-devs-ai-extension: true`** — applied to schemas, schema properties, parameters, response headers, and operations that have no OpenAI counterpart.\n- **`x-devs-ai-extension-values: [string, ...]`** — applied to enum schemas/properties whose enum is OpenAI-aligned but where devs.ai accepts/emits additional values. Lists only the extra values (e.g. `[\"cancelled\"]` on `ResponseStatus`).\n- **`x-devs-ai-extension-behavior: \"\"`** — applied where the field name itself is OpenAI-standard but devs.ai's handling differs (e.g. `optional-on-request` on `MessageInputItem.type` because devs.ai accepts the field being omitted while OpenAI requires it).\n\n### devs.ai Extensions\n\nA single reference list of every devs.ai-specific addition exposed by this API. Each entry below is also marked `**[devs.ai extension]**` at its source and carries one of the `x-devs-ai-extension*` vendor extensions described above.\n\n**Request fields (`CreateResponseRequest`)**\n- `chat_mode` — `execute` / `chat` / `plan` execution mode.\n- `user_secrets` — short-lived per-request API keys / secrets for tools.\n- `thread_mode` — concurrent-request handling on an existing thread (`collect` / `steer` / `interrupt` / `force`).\n- `options` — internal devs.ai chat options (provider routing, tracing, etc.).\n- `reasoning.effort` extra values `none` and `xhigh` (in addition to OpenAI's `minimal` / `low` / `medium` / `high`).\n\n**Input content-part flags**\n- `input_text.invisible` / `input_image.invisible` / `input_file.invisible` — content sent to the model but hidden from end-user transcripts.\n- `input_text.metadata` — arbitrary metadata attached to a content part (not forwarded to the model).\n- `output_text.logprobs` (when `output_text` appears inside an `OutputMessageInputItem`).\n\n**Input item enum**\n- `FunctionCallOutputInputItem.status` uses `[\"success\", \"error\", \"cancelled\"]` instead of OpenAI's `[\"in_progress\", \"completed\", \"incomplete\"]` (incompatible enum).\n\n**Tools (`ToolDefinition`)** — only `function` and `web_search` mirror OpenAI; everything below is devs.ai-specific.\n- `python` — emits `server_tool_call` items (not OpenAI's `code_interpreter_call`).\n- `image_generation` — shares the type name with OpenAI but uses devs.ai's input shape and emits `server_tool_call` items.\n- `mcp_server` — references a configured devs.ai MCP integration; does not emit OpenAI's `mcp_list_tools` discovery events or `mcp_approval_request` / `mcp_approval_response` items.\n- `spreadsheet`, `memory`, `sandbox`, `deep_research` — no OpenAI counterpart.\n- `web_search.includeXSearch` — extra X (Twitter) search inclusion flag.\n\n**Output items (`OutputItem`)**\n- `server_tool_call` and `server_tool_call_output` — emitted instead of OpenAI's `code_interpreter_call` / `image_generation_call` items for devs.ai's server-side tools.\n\n**Response fields (`Response`)**\n- `selection_metadata` — model routing / selection metadata (chosen provider, fallback chain, latency hints).\n- `status` extra value `cancelled` (in addition to OpenAI's `in_progress` / `completed` / `failed` / `incomplete`).\n- `incomplete_details.reason` extra value `paused` (in addition to OpenAI's `max_output_tokens` / `content_filter`).\n\n**Streaming events** (full list and payloads in the `x-streaming-events` reference under `components`)\n- `response.server_tool_call.in_progress` / `.completed` / `.failed`.\n- `response.server_tool_call_arguments.delta` / `.done`.\n- `response.subagent.started` / `.progress` / `.completed`.\n- `response.output_item.added.status_hints` (optional field on `response.output_item.added`).\n- Every event payload includes a monotonically increasing `sequence_number` field.\n- Terminal sentinel `event: done` / `data: [DONE]` after the last lifecycle event.\n\n**Endpoints / headers**\n- `POST /api/v2/responses/{responseId}/pause` — pause an active threaded response run.\n- `POST /api/v2/responses/{responseId}/resume` — resume a paused threaded response run, optionally supplying tool outputs.\n- `GET /api/v2/responses/{responseId}/stream` — reconnect to an in-flight SSE stream after a network drop, resuming from `lastSequence`.\n- `POST /api/v2/responses/{responseId}/deep-research/resume` — approve / deny / clarify a paused deep research subagent.\n- `x-stream-chat-id` response header on streaming `POST /api/v2/responses` and on the `/stream` reconnect endpoint." }, { "name": "Tenant Rate Limits", "description": "Tenant owner APIs to configure default rate limits and per-organization overrides" }, { "name": "Tenant Administration", "description": "Tenant-owner M2M APIs for provisioning and managing child organizations (org create, subscription lifecycle, balance top-up, member seats). Requires a tenant-scoped API key from the tenant-owner org." }, { "name": "Roles", "description": "Create and manage custom roles and their permission sets" }, { "name": "Organization Settings", "description": "Read and update organization-wide settings and policies" }, { "name": "Organization Members", "description": "List organization members and invite new ones" } ] }