{ "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", "properties": { "error": { "type": "string" } } }, "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", "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", "nullable": true, "description": "Email of the user associated with the API key." }, "name": { "type": "string", "description": "Name of the API key." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted to the API key." } } }, "ApiKeyWithTokenDto": { "allOf": [ { "$ref": "#/components/schemas/ApiKeyDto" }, { "type": "object", "properties": { "key": { "type": "string", "description": "The plain API key token. Only returned at creation time." } } } ] }, "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" }, "seed": { "type": "string" }, "src": { "type": "string" }, "orgId": { "type": "string" }, "userId": { "type": "string" }, "profile": { "$ref": "#/components/schemas/AIProfile" }, "userName": { "type": "string" }, "orgName": { "type": "string" }, "categoryId": { "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" } }, "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" } } } }, "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 AI configuration. Send only the fields you want to update.", "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" } } } }, "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" } ] }, "CreateSQLToolRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SQL" ] }, "databaseType": { "$ref": "#/components/schemas/SQLToolDatabaseType" }, "username": { "type": "string" }, "password": { "type": "string" }, "host": { "type": "string" }, "database": { "type": "string" }, "port": { "type": "integer" } }, "required": [ "type", "databaseType", "username", "password", "host", "database", "port" ] }, "UpdateSQLToolRequest": { "type": "object", "properties": { "databaseType": { "$ref": "#/components/schemas/SQLToolDatabaseType" }, "username": { "type": "string" }, "password": { "type": "string" }, "host": { "type": "string" }, "database": { "type": "string" }, "port": { "type": "integer" } }, "required": [ "databaseType", "username", "password", "host", "database", "port" ] }, "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 marketplace 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 marketplace 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 marketplace 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", "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" ] }, "membershipType": { "$ref": "#/components/schemas/OrgMembershipTypeDto" }, "createdAt": { "type": "string", "format": "date-time" }, "externalUserId": { "type": "string", "nullable": true } } }, "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 ] } } } }, "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": [] } ] }, "patch": { "tags": [ "AI Management" ], "summary": "Update AI", "description": "Updates fields on the specified AI.", "operationId": "updateAI", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIUpdateRequest" } } } }, "responses": { "200": { "description": "Updated AI details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIDetail" } } } }, "400": { "description": "Bad request - invalid input." }, "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": [] } ] }, "delete": { "tags": [ "AI Management" ], "summary": "Delete AI", "description": "Deletes the specified AI.", "operationId": "deleteAI", "parameters": [ { "name": "aiId", "in": "path", "required": true, "description": "The identifier of the AI to delete.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "AI deleted successfully." }, "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": { "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": [] } ] } }, "/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/CreateSQLToolRequest" }, { "$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/sql": { "post": { "tags": [ "Tools" ], "summary": "Create a SQL tool", "description": "Creates a SQL tool and associates it with the AI.", "operationId": "createSqlTool", "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/CreateSQLToolRequest" } } } }, "responses": { "201": { "description": "Tool created.", "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" ], "description": "The source of the file. Defaults to USER if not specified." } } } } } }, "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}/sql": { "put": { "tags": [ "Tools" ], "summary": "Update a SQL tool", "description": "Updates the SQL tool configuration.", "operationId": "updateSqlTool", "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/UpdateSQLToolRequest" } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } } }, "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 activities complete but no new turns are scheduled.\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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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": [] } ] }, "post": { "tags": [ "Tenant Marketplace Provisioning" ], "summary": "Assign organization member", "description": "Find-or-create user by email, grant membership, and create seat assignment. Synchronous 201. Requires ORG_SETTINGS WRITE.", "operationId": "assignTenantOrgMember", "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/CreateTenantOrganizationMemberRequestDto" } } } }, "responses": { "201": { "description": "Member assigned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOrganizationMemberDto" } } } }, "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/{userId}": { "put": { "tags": [ "Tenant Marketplace Provisioning" ], "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 Marketplace Provisioning" ], "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": [] } ] } } }, "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 Marketplace Provisioning", "description": "Tenant-owner M2M APIs for marketplace partners (org create, subscription lifecycle, balance top-up, member seats). Requires a tenant-scoped API key from the tenant-owner org." } ] }