{ "openapi": "3.1.0", "servers": [ { "url": "https://ai.hatz.ai/v1", "description": "Hatz API Production Server" } ], "info": { "title": "Hatz API", "description": "Hatz AI's API", "termsOfService": "https://www.hatz.ai/terms-of-use", "contact": { "name": "Hatz AI", "url": "https://www.hatz.ai/", "email": "help@hatz.ai" }, "version": "0.1.0" }, "paths": { "/chat/models": { "get": { "tags": [ "Completions" ], "summary": "Get Models", "description": "Get the list of available ai models.", "operationId": "get_models_v1_chat_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "name": { "type": "string", "title": "Name", "description": "The unique identifier/name of the AI model. Use this to specify the model in requests." }, "developer": { "type": "string", "title": "Developer", "description": "The company/organization that developed this model" }, "display_name": { "type": "string", "title": "Display Name", "description": "The human-readable display name for this model" }, "max_tokens": { "type": "integer", "title": "Max Tokens", "description": "The maximum number of tokens this model can process" }, "vision": { "type": "boolean", "title": "Vision", "description": "Whether this model has vision/image processing capabilities" } }, "type": "object", "required": [ "name", "developer", "display_name", "max_tokens", "vision" ], "title": "AIModel" }, "type": "array", "title": "Data", "description": "The list of available AI models" } }, "type": "object", "required": [ "data" ], "title": "ModelsResponse" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/chat/completions": { "post": { "tags": [ "Completions" ], "summary": "Post Completions", "description": "Post a completion request to the ai model.\n\nReturns:\n\n - StreamingResponse when request.stream=True\n\n - CompletionResponse when request.stream=False", "operationId": "post_completions_v1_chat_completions_post", "requestBody": { "content": { "application/json": { "schema": { "properties": { "messages": { "items": { "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ], "title": "Role", "description": "The role of the message sender" }, "content": { "type": "string", "title": "Content", "description": "The content of the message" } }, "type": "object", "required": [ "role", "content" ], "title": "Message" }, "type": "array", "title": "Messages", "description": "The list of messages to process" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "The AI model to use for processing. Please use the unique name of the model, not the display name", "default": "gpt-4o" }, "stream": { "type": "boolean", "title": "Stream", "description": "Whether to stream the response", "default": false }, "file_uuids": { "anyOf": [ { "items": { "type": "string", "format": "uuid4" }, "type": "array" }, { "type": "null" } ], "title": "File Uuids", "description": "The list of file uuids to process", "default": [] } }, "type": "object", "required": [ "messages" ], "title": "CompletionRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "choices": { "items": { "properties": { "message": { "description": "The message response from the AI", "properties": { "content": { "type": "string", "title": "Content", "description": "The content of the response message" }, "role": { "type": "string", "enum": [ "assistant" ], "const": "assistant", "title": "Role", "description": "The role of the message sender" } }, "type": "object", "required": [ "content", "role" ], "title": "CompletionResponseMessage" } }, "type": "object", "required": [ "message" ], "title": "CompletionResponseChoice" }, "type": "array", "title": "Choices", "description": "List of completion choices" }, "model": { "type": "string", "title": "Model", "description": "The AI model used for processing" }, "usage": { "description": "Token usage statistics", "properties": { "input_tokens": { "type": "integer", "title": "Input Tokens", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "title": "Output Tokens", "description": "Number of output tokens used" } }, "type": "object", "required": [ "input_tokens", "output_tokens" ], "title": "Usage" } }, "type": "object", "required": [ "choices", "model", "usage" ], "title": "CompletionResponse" }, { "properties": { "type": { "type": "string", "title": "Type", "description": "The type of response (e.g. completion)" }, "message": { "type": "string", "title": "Message", "description": "The message to be streamed" } }, "type": "object", "required": [ "type", "message" ], "title": "CompletionsStreamingResponse" } ], "title": "Response Post Completions V1 Chat Completions Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/files/upload": { "post": { "tags": [ "File Upload" ], "summary": "Upload File", "operationId": "upload_file_v1_files_upload_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "only_calculate_tokens": { "type": "boolean", "title": "Only Calculate Tokens", "default": false } }, "type": "object", "required": [ "file" ], "title": "Body_upload_file_v1_files_upload_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/files/": { "get": { "tags": [ "File Upload" ], "summary": "Get Files", "operationId": "get_files_v1_files__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/app/models": { "get": { "tags": [ "App Builder" ], "summary": "Get Models", "description": "Get the list of available ai models.", "operationId": "get_models_v1_app_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "name": { "type": "string", "title": "Name", "description": "The unique identifier/name of the AI model. Use this to specify the model in requests." }, "developer": { "type": "string", "title": "Developer", "description": "The company/organization that developed this model" }, "display_name": { "type": "string", "title": "Display Name", "description": "The human-readable display name for this model" }, "max_tokens": { "type": "integer", "title": "Max Tokens", "description": "The maximum number of tokens this model can process" }, "vision": { "type": "boolean", "title": "Vision", "description": "Whether this model has vision/image processing capabilities" } }, "type": "object", "required": [ "name", "developer", "display_name", "max_tokens", "vision" ], "title": "AIModel" }, "type": "array", "title": "Data", "description": "The list of available AI models" } }, "type": "object", "required": [ "data" ], "title": "ModelsResponse" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/app/list": { "get": { "tags": [ "App Builder" ], "summary": "List All Apps", "operationId": "list_all_apps_v1_app_list_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the app" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The description of the app" }, "default_model": { "type": "string", "title": "Default Model", "description": "The default AI model to use", "default": "gpt-4o" }, "files": { "items": { "properties": { "size": { "type": "integer", "title": "Size", "description": "The size of the file in bytes" }, "module": { "type": "string", "title": "Module", "description": "The module this file belongs to" }, "file_id": { "type": "string", "title": "File Id", "description": "The unique identifier for this file", "default": "" }, "type_id": { "type": "string", "title": "Type Id", "description": "The type identifier for this file", "default": "" }, "file_key": { "type": "string", "title": "File Key", "description": "The key/name of the file" }, "file_type": { "type": "string", "title": "File Type", "description": "The type of file (e.g. PDF)" }, "object_id": { "type": "string", "title": "Object Id", "description": "The object identifier for this file" }, "description": { "type": "string", "title": "Description", "description": "A description of the file" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name of the file" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name associated with this file" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of variable this file represents" } }, "type": "object", "required": [ "size", "module", "file_key", "file_type", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppFileResponse" }, "type": "array", "title": "Files", "description": "The files associated with this app" }, "constants": { "items": { "properties": { "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this constant" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "A description of this constant" }, "variable_type": { "type": "string", "enum": [ "text" ], "const": "text", "title": "Variable Type", "description": "The type of constant (only 'text' supported)" }, "value": { "type": "string", "title": "Value", "description": "The value of this constant" } }, "type": "object", "required": [ "object_id", "variable_name", "display_name", "variable_type", "value" ], "title": "AppConstant" }, "type": "array", "title": "Constants", "description": "The constants associated with this app", "default": [] }, "user_inputs": { "items": { "properties": { "position": { "type": "integer", "title": "Position", "description": "The position/order of this input field" }, "required": { "type": "boolean", "title": "Required", "description": "Whether this input is required" }, "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this input" }, "description": { "type": "string", "title": "Description", "description": "A description of this input field" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of input (e.g. short_answer)" } }, "type": "object", "required": [ "position", "required", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppUserInputResponse" }, "type": "array", "title": "User Inputs", "description": "The user inputs associated with this app" }, "prompt_sections": { "items": { "properties": { "body": { "type": "string", "title": "Body" }, "position": { "type": "integer", "title": "Position" } }, "type": "object", "required": [ "body", "position" ], "title": "PromptSection" }, "type": "array", "title": "Prompt Sections", "description": "The prompt sections associated with this app" } }, "type": "object", "required": [ "name", "files", "user_inputs", "prompt_sections" ], "title": "AppResponse" }, "type": "array", "title": "Data", "description": "The list of apps" } }, "type": "object", "required": [ "data" ], "title": "AppListResponse" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/app/{app_id}": { "get": { "tags": [ "App Builder" ], "summary": "Get App By Id", "description": "Get an app's data by its id.", "operationId": "get_app_by_id_v1_app__app_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the app to retrieve", "title": "App Id" }, "description": "The unique identifier of the app to retrieve" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the app" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The description of the app" }, "default_model": { "type": "string", "title": "Default Model", "description": "The default AI model to use", "default": "gpt-4o" }, "files": { "items": { "properties": { "size": { "type": "integer", "title": "Size", "description": "The size of the file in bytes" }, "module": { "type": "string", "title": "Module", "description": "The module this file belongs to" }, "file_id": { "type": "string", "title": "File Id", "description": "The unique identifier for this file", "default": "" }, "type_id": { "type": "string", "title": "Type Id", "description": "The type identifier for this file", "default": "" }, "file_key": { "type": "string", "title": "File Key", "description": "The key/name of the file" }, "file_type": { "type": "string", "title": "File Type", "description": "The type of file (e.g. PDF)" }, "object_id": { "type": "string", "title": "Object Id", "description": "The object identifier for this file" }, "description": { "type": "string", "title": "Description", "description": "A description of the file" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name of the file" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name associated with this file" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of variable this file represents" } }, "type": "object", "required": [ "size", "module", "file_key", "file_type", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppFileResponse" }, "type": "array", "title": "Files", "description": "The files associated with this app" }, "constants": { "items": { "properties": { "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this constant" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "A description of this constant" }, "variable_type": { "type": "string", "enum": [ "text" ], "const": "text", "title": "Variable Type", "description": "The type of constant (only 'text' supported)" }, "value": { "type": "string", "title": "Value", "description": "The value of this constant" } }, "type": "object", "required": [ "object_id", "variable_name", "display_name", "variable_type", "value" ], "title": "AppConstant" }, "type": "array", "title": "Constants", "description": "The constants associated with this app", "default": [] }, "user_inputs": { "items": { "properties": { "position": { "type": "integer", "title": "Position", "description": "The position/order of this input field" }, "required": { "type": "boolean", "title": "Required", "description": "Whether this input is required" }, "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this input" }, "description": { "type": "string", "title": "Description", "description": "A description of this input field" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of input (e.g. short_answer)" } }, "type": "object", "required": [ "position", "required", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppUserInputResponse" }, "type": "array", "title": "User Inputs", "description": "The user inputs associated with this app" }, "prompt_sections": { "items": { "properties": { "body": { "type": "string", "title": "Body" }, "position": { "type": "integer", "title": "Position" } }, "type": "object", "required": [ "body", "position" ], "title": "PromptSection" }, "type": "array", "title": "Prompt Sections", "description": "The prompt sections associated with this app" } }, "type": "object", "required": [ "name", "files", "user_inputs", "prompt_sections" ], "title": "AppResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } } } }, "/app/{app_id}/query": { "post": { "tags": [ "App Builder" ], "summary": "Query App", "description": "Post a completion request to the ai model given an app id and set of inputs.\n\nInputs are usually in the form of JSON object like:\n\n`{'': ''}` \n\nExample: `{'name': 'John', 'age': 25}`\n\n\nThe variable name should be the same as the variable name in the app.\n\nReturns:\n\n - StreamingResponse when request.stream=True\n\n - CompletionResponse when request.stream=False", "operationId": "query_app_v1_app__app_id__query_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the app to query", "title": "App Id" }, "description": "The unique identifier of the app to query" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "inputs": { "type": "object", "title": "Inputs", "description": "The list of inputs on the app to process. Usually in the form of JSON object like {'\\': '\\'}. The variable name should be the same as the variable name in the app." }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "The AI model to use for processing. Please use the unique name of the model, not the display name", "default": "gpt-4o" }, "stream": { "type": "boolean", "title": "Stream", "description": "Whether to stream the response", "default": false }, "file_uuids": { "anyOf": [ { "items": { "type": "string", "format": "uuid4" }, "type": "array" }, { "type": "null" } ], "title": "File Uuids", "description": "The list of file uuids to process", "default": [] } }, "type": "object", "required": [ "inputs" ], "title": "AppQueryRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "choices": { "items": { "properties": { "message": { "description": "The message response from the AI", "properties": { "content": { "type": "string", "title": "Content", "description": "The content of the response message" }, "role": { "type": "string", "enum": [ "assistant" ], "const": "assistant", "title": "Role", "description": "The role of the message sender" } }, "type": "object", "required": [ "content", "role" ], "title": "CompletionResponseMessage" } }, "type": "object", "required": [ "message" ], "title": "CompletionResponseChoice" }, "type": "array", "title": "Choices", "description": "List of completion choices" }, "model": { "type": "string", "title": "Model", "description": "The AI model used for processing" }, "usage": { "description": "Token usage statistics", "properties": { "input_tokens": { "type": "integer", "title": "Input Tokens", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "title": "Output Tokens", "description": "Number of output tokens used" } }, "type": "object", "required": [ "input_tokens", "output_tokens" ], "title": "Usage" } }, "type": "object", "required": [ "choices", "model", "usage" ], "title": "CompletionResponse" }, { "properties": { "type": { "type": "string", "title": "Type", "description": "The type of response (e.g. completion)" }, "message": { "type": "string", "title": "Message", "description": "The message to be streamed" } }, "type": "object", "required": [ "type", "message" ], "title": "CompletionsStreamingResponse" } ], "title": "Response Query App V1 App App Id Query Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } } } }, "/admin/users/invite": { "post": { "tags": [ "Admin Management - Users" ], "summary": "Invite Users", "description": "Invite users to a tenant. Accepts JSON array of users. Requires tenant_id in HashID format.", "operationId": "invite_users_v1_admin_users_invite_post", "requestBody": { "content": { "application/json": { "schema": { "properties": { "tenant_id": { "type": "string", "pattern": "^tenant_[a-zA-Z0-9]+$", "title": "Tenant Id", "description": "Tenant HashID" }, "users": { "items": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "User role in the organization" } }, "type": "object", "required": [ "email" ], "title": "NewUser" }, "type": "array", "minItems": 1, "maxItems": 100, "title": "Users", "description": "List of users to invite" } }, "type": "object", "required": [ "tenant_id", "users" ], "title": "AdminInviteUsersInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "title": "Message", "description": "Success message" }, "total_new_users_created": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total New Users Created", "description": "Number of new users successfully created", "default": 0 }, "total_existing_users_added": { "type": "integer", "title": "Total Existing Users Added", "description": "Number of users who already had a Hatz account and were added to the entity" }, "total_new_users_failed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total New Users Failed", "description": "Number of new users that failed to create", "default": 0 }, "new_users_failed_emails": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "New Users Failed Emails", "description": "Email addresses of users that failed", "default": [] }, "results": { "anyOf": [ { "items": { "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results", "description": "Per-user results with any errors" } }, "type": "object", "required": [ "message" ], "title": "AdminInviteUsersOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/users/invite/msp": { "post": { "tags": [ "Admin Management - Users" ], "summary": "Invite MSP Users", "description": "Invite users to the MSP entity. Uses the authenticated user's managed entity.", "operationId": "invite_msp_users_v1_admin_users_invite_msp_post", "requestBody": { "content": { "application/json": { "schema": { "properties": { "users": { "items": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "User role in the organization" } }, "type": "object", "required": [ "email" ], "title": "NewUser" }, "type": "array", "minItems": 1, "maxItems": 100, "title": "Users", "description": "List of users to invite" } }, "type": "object", "required": [ "users" ], "title": "AdminInviteMspUsersInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "title": "Message", "description": "Success message" }, "total_new_users_created": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total New Users Created", "description": "Number of new users successfully created", "default": 0 }, "total_existing_users_added": { "type": "integer", "title": "Total Existing Users Added", "description": "Number of users who already had a Hatz account and were added to the entity" }, "total_new_users_failed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total New Users Failed", "description": "Number of new users that failed to create", "default": 0 }, "new_users_failed_emails": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "New Users Failed Emails", "description": "Email addresses of users that failed", "default": [] }, "results": { "anyOf": [ { "items": { "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results", "description": "Per-user results with any errors" } }, "type": "object", "required": [ "message" ], "title": "AdminInviteUsersOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/users": { "get": { "tags": [ "Admin Management - Users" ], "summary": "Get User By Email", "description": "Search for a user by email address. Returns user details or null if not found. For listing users in a tenant, use GET /tenants/{tenant_id}/users instead.", "operationId": "get_user_by_email_v1_admin_users_get", "parameters": [ { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "description": "User email address to search for", "title": "Email" }, "description": "User email address to search for" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "id": { "type": "string", "title": "Id", "description": "User HashID" }, "email": { "type": "string", "title": "Email", "description": "User email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id", "description": "Tenant HashID" }, "role_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role Name", "description": "User role" }, "last_sign_in_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sign In At", "description": "Last sign in timestamp" } }, "type": "object", "required": [ "id", "email" ], "title": "AdminUserOutput" }, { "type": "null" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/users/msp": { "get": { "tags": [ "Admin Management - Users" ], "summary": "Get MSP Users", "description": "Get users for the MSP entity. Returns user details including role_name and last_sign_in_at.", "operationId": "get_msp_users_v1_admin_users_msp_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "string", "title": "Id", "description": "User HashID" }, "email": { "type": "string", "title": "Email", "description": "User email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role Name", "description": "User role" }, "last_sign_in_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sign In At", "description": "Last sign in timestamp" } }, "type": "object", "required": [ "id", "email" ], "title": "AdminMSPUserOutput" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/users/{user_id}": { "get": { "tags": [ "Admin Management - Users" ], "summary": "Get User", "description": "Get a specific user by HashID.", "operationId": "get_user_v1_admin_users__user_id__get", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "description": "User HashID", "title": "User Id" }, "description": "User HashID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "title": "Id", "description": "User HashID" }, "email": { "type": "string", "title": "Email", "description": "User email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id", "description": "Tenant HashID" }, "role_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role Name", "description": "User role" }, "last_sign_in_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sign In At", "description": "Last sign in timestamp" } }, "type": "object", "required": [ "id", "email" ], "title": "AdminUserOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "delete": { "tags": [ "Admin Management - Users" ], "summary": "Delete User", "description": "Delete a user by HashID. Removes the user from their entity/tenant.", "operationId": "delete_user_v1_admin_users__user_id__delete", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "description": "User HashID", "title": "User Id" }, "description": "User HashID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "title": "Message", "description": "Success message" }, "user_id": { "type": "string", "title": "User Id", "description": "HashID of deleted user" } }, "type": "object", "required": [ "message", "user_id" ], "title": "AdminDeleteUserOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "patch": { "tags": [ "Admin Management - Users" ], "summary": "Update User", "description": "Update a user's profile, role, or move them to a different tenant. All fields are optional - provide only the fields you want to update.", "operationId": "update_user_v1_admin_users__user_id__patch", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "description": "User HashID", "title": "User Id" }, "description": "User HashID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role Name", "description": "New role name" }, "tenant_id": { "anyOf": [ { "type": "string", "pattern": "^tenant_[a-zA-Z0-9]+$" }, { "type": "null" } ], "title": "Tenant Id", "description": "Move user to this tenant" } }, "type": "object", "title": "AdminUpdateUserInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "title": "Message", "description": "Success message" }, "user_id": { "type": "string", "title": "User Id", "description": "HashID of updated user" } }, "type": "object", "required": [ "message", "user_id" ], "title": "AdminUpdateUserOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/tenants": { "get": { "tags": [ "Admin Management - Tenants" ], "summary": "Get Tenants", "description": "Get all tenants managed by the authenticated user. Returns tenant details with HashIDs and usage statistics.", "operationId": "get_tenants_v1_admin_tenants_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "string", "title": "Id", "description": "Tenant HashID" }, "name": { "type": "string", "title": "Name", "description": "Tenant name" }, "primary_package_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Package Name", "description": "Primary package name" }, "additional_package_names": { "items": { "type": "string" }, "type": "array", "title": "Additional Package Names", "description": "Additional packages", "default": [] }, "user_count": { "type": "integer", "title": "User Count", "description": "Number of users", "default": 0 }, "status": { "type": "string", "title": "Status", "description": "Tenant status", "default": "Active" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp" }, "total_credits_used": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credits Used", "description": "Credits used" }, "total_credit_limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credit Limit", "description": "Total credit limit" }, "tenant_config": { "description": "Tenant configuration settings", "properties": { "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled", "default": false }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required for this tenant", "default": false }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o')" } }, "type": "object", "title": "TenantConfig" }, "disabled_model_names": { "items": { "type": "string" }, "type": "array", "title": "Disabled Model Names", "description": "List of disabled AI model names", "default": [] } }, "type": "object", "required": [ "id", "name" ], "title": "AdminTenantOutput" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "Admin Management - Tenants" ], "summary": "Create Tenants", "description": "Create multiple tenants with users. Accepts JSON array of tenants. Package or template must be a HashID.", "operationId": "create_tenants_v1_admin_tenants_post", "requestBody": { "content": { "application/json": { "schema": { "properties": { "tenants": { "items": { "properties": { "tenant_name": { "type": "string", "minLength": 1, "maxLength": 255, "title": "Tenant Name", "description": "Tenant name (spaces allowed)" }, "package_id": { "anyOf": [ { "type": "string", "pattern": "^package_[a-zA-Z0-9]+$" }, { "type": "null" } ], "title": "Package Id", "description": "Package HashID. Optional if template_id is provided." }, "template_id": { "anyOf": [ { "type": "string", "pattern": "^tentemplate_[a-zA-Z0-9]+$" }, { "type": "null" } ], "title": "Template Id", "description": "Tenant creation template HashID. If provided, license_type_id will be resolved from template. Optional if package_id is provided." }, "users": { "items": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "User role in the organization" } }, "type": "object", "required": [ "email" ], "title": "NewUser" }, "type": "array", "maxItems": 1000, "title": "Users", "description": "Initial users for the tenant (optional)", "default": [] } }, "type": "object", "required": [ "tenant_name" ], "title": "TenantCreateInput" }, "type": "array", "minItems": 1, "maxItems": 100, "title": "Tenants", "description": "List of tenants to create" } }, "type": "object", "required": [ "tenants" ], "title": "AdminCreateTenantsInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "title": "Message", "description": "Operation summary message" }, "total_tenants_created": { "type": "integer", "title": "Total Tenants Created", "description": "Number of tenants successfully created" }, "total_tenants_failed": { "type": "integer", "title": "Total Tenants Failed", "description": "Number of tenants that failed to create" }, "tenants": { "items": { "type": "object" }, "type": "array", "title": "Tenants", "description": "Detailed results for each tenant" } }, "type": "object", "required": [ "message", "total_tenants_created", "total_tenants_failed", "tenants" ], "title": "AdminCreateTenantsOutput" } } } }, "400": { "description": "Validation error - duplicate tenant names or emails, or invalid package/template ID" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/tenants/msp": { "get": { "tags": [ "Admin Management - Tenants" ], "summary": "Get MSP Tenant", "description": "Get the MSP entity details. Returns MSP usage statistics and user counts.", "operationId": "get_msp_tenant_v1_admin_tenants_msp_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "title": "Name", "description": "MSP name" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp" }, "primary_package_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Package Name", "description": "Primary package name" }, "additional_package_names": { "items": { "type": "string" }, "type": "array", "title": "Additional Package Names", "description": "Additional package names", "default": [] }, "packages": { "type": "object", "title": "Packages", "description": "Package details", "default": {} }, "total_credits_used": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credits Used", "description": "Total credits used", "default": 0 }, "total_credit_limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credit Limit", "description": "Total credit limit", "default": 0 }, "admin_user_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Admin User Count", "description": "Admin user count", "default": 0 }, "admin_recent_signin_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Admin Recent Signin Count", "description": "Recent admin sign-ins", "default": 0 }, "admin_login_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Admin Login Rate", "description": "Admin login rate", "default": 0 }, "tenant_user_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tenant User Count", "description": "Tenant user count", "default": 0 }, "tenant_recent_signin_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tenant Recent Signin Count", "description": "Recent tenant sign-ins", "default": 0 }, "tenant_login_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Tenant Login Rate", "description": "Tenant login rate", "default": 0 } }, "type": "object", "required": [ "name" ], "title": "AdminMSPOutput" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/tenants/{tenant_id}": { "get": { "tags": [ "Admin Management - Tenants" ], "summary": "Get Tenant", "description": "Get a specific tenant by HashID.", "operationId": "get_tenant_v1_admin_tenants__tenant_id__get", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant HashID", "title": "Tenant Id" }, "description": "Tenant HashID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "title": "Id", "description": "Tenant HashID" }, "name": { "type": "string", "title": "Name", "description": "Tenant name" }, "primary_package_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Package Name", "description": "Primary package name" }, "additional_package_names": { "items": { "type": "string" }, "type": "array", "title": "Additional Package Names", "description": "Additional packages", "default": [] }, "user_count": { "type": "integer", "title": "User Count", "description": "Number of users", "default": 0 }, "status": { "type": "string", "title": "Status", "description": "Tenant status", "default": "Active" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp" }, "total_credits_used": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credits Used", "description": "Credits used" }, "total_credit_limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credit Limit", "description": "Total credit limit" }, "tenant_config": { "description": "Tenant configuration settings", "properties": { "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled", "default": false }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required for this tenant", "default": false }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o')" } }, "type": "object", "title": "TenantConfig" }, "disabled_model_names": { "items": { "type": "string" }, "type": "array", "title": "Disabled Model Names", "description": "List of disabled AI model names", "default": [] } }, "type": "object", "required": [ "id", "name" ], "title": "AdminTenantOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/tenants/{tenant_id}/config": { "patch": { "tags": [ "Admin Management - Tenants" ], "summary": "Update Tenant Config", "description": "Update tenant configuration settings (beta_features, mfa_required, default_model_name).", "operationId": "update_tenant_config_v1_admin_tenants__tenant_id__config_patch", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant HashID", "title": "Tenant Id" }, "description": "Tenant HashID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "beta_features": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Beta Features", "description": "Whether beta features are enabled" }, "mfa_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "MFA Required", "description": "Whether MFA is required for this tenant" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o'). Set to empty string to clear." } }, "type": "object", "title": "TenantConfigUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled", "default": false }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required for this tenant", "default": false }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o')" } }, "type": "object", "title": "TenantConfig" } } } }, "400": { "description": "Invalid tenant ID format or AI model not found" }, "404": { "description": "Tenant not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/packages": { "get": { "tags": [ "Admin Management - Packages" ], "summary": "Get Packages", "description": "Get package(s) by ID or name. Must provide at least one parameter.", "operationId": "get_packages_v1_admin_packages_get", "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^package_[a-zA-Z0-9]+$", "description": "Package HashID to fetch", "title": "Id" }, "description": "Package HashID to fetch" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "description": "Package name to search for", "title": "Name" }, "description": "Package name to search for" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "string", "title": "Id", "description": "Package HashID" }, "name": { "type": "string", "title": "Name", "description": "Package name" } }, "type": "object", "required": [ "id", "name" ], "title": "AdminPackageOutput" } } } } }, "400": { "description": "Must provide either 'id' or 'name' parameter, or invalid package ID format" }, "404": { "description": "Package not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/tenants/{tenant_id}/users": { "get": { "tags": [ "Admin Management - Tenants" ], "summary": "Get Tenant Users", "description": "Get all users in a specific tenant.", "operationId": "get_tenant_users_v1_admin_tenants__tenant_id__users_get", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant HashID", "title": "Tenant Id" }, "description": "Tenant HashID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "string", "title": "Id", "description": "User HashID" }, "email": { "type": "string", "title": "Email", "description": "User email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id", "description": "Tenant HashID" }, "role_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role Name", "description": "User role" }, "last_sign_in_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sign In At", "description": "Last sign in timestamp" } }, "type": "object", "required": [ "id", "email" ], "title": "AdminUserOutput" } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/tenants/templates": { "get": { "tags": [ "Admin Management - Tenant Templates" ], "summary": "List Tenant Templates", "description": "List all tenant creation templates for the current user's managed entity. Uses cursor-based pagination.", "operationId": "list_tenant_templates_v1_admin_tenants_templates_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100, "title": "Limit" }, "description": "Number of results to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "description": "Pagination cursor (created_at timestamp from previous response)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "templates": { "items": { "properties": { "id": { "type": "string", "title": "Id", "description": "Template HashID" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "package_name": { "type": "string", "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name" }, "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled" }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "package_name", "beta_features", "mfa_required", "created_at", "updated_at" ], "title": "AdminTenantTemplateOutput" }, "type": "array", "title": "Templates", "description": "List of templates" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for next page" } }, "type": "object", "required": [ "templates" ], "title": "AdminTenantTemplatesListOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "Admin Management - Tenant Templates" ], "summary": "Create Tenant Template", "description": "Create a new tenant creation template.", "operationId": "create_tenant_template_v1_admin_tenants_templates_post", "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 255, "title": "Name", "description": "Template name" }, "package_name": { "type": "string", "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o')" }, "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Enable beta features", "default": false }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Require MFA", "default": false } }, "type": "object", "required": [ "name", "package_name" ], "title": "AdminTenantTemplateCreateInput" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "title": "Id", "description": "Template HashID" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "package_name": { "type": "string", "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name" }, "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled" }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "package_name", "beta_features", "mfa_required", "created_at", "updated_at" ], "title": "AdminTenantTemplateOutput" } } } }, "400": { "description": "Bad Request - invalid model name or managed entity not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/admin/tenants/templates/{template_id}": { "get": { "tags": [ "Admin Management - Tenant Templates" ], "summary": "Get Tenant Template", "description": "Get a specific tenant creation template by HashID.", "operationId": "get_tenant_template_v1_admin_tenants_templates_template_id_get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id", "description": "Template HashID (e.g., tentemplate_abc123)" }, "description": "Template HashID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "title": "Id", "description": "Template HashID" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "package_name": { "type": "string", "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name" }, "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled" }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "package_name", "beta_features", "mfa_required", "created_at", "updated_at" ], "title": "AdminTenantTemplateOutput" } } } }, "400": { "description": "Invalid template ID format" }, "404": { "description": "Template not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "put": { "tags": [ "Admin Management - Tenant Templates" ], "summary": "Update Tenant Template", "description": "Update an existing tenant creation template. Only provided fields will be updated.", "operationId": "update_tenant_template_v1_admin_tenants_templates_template_id_put", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id", "description": "Template HashID (e.g., tentemplate_abc123)" }, "description": "Template HashID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "Template name" }, "package_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o'). Set to empty string to clear." }, "beta_features": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Beta Features", "description": "Enable beta features" }, "mfa_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "MFA Required", "description": "Require MFA" } }, "type": "object", "title": "AdminTenantTemplateUpdateInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "title": "Id", "description": "Template HashID" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "package_name": { "type": "string", "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name" }, "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled" }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "package_name", "beta_features", "mfa_required", "created_at", "updated_at" ], "title": "AdminTenantTemplateOutput" } } } }, "400": { "description": "Bad Request - invalid template ID, model not found, or no fields to update" }, "404": { "description": "Template not found or insufficient permissions" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "delete": { "tags": [ "Admin Management - Tenant Templates" ], "summary": "Delete Tenant Template", "description": "Delete a tenant creation template.", "operationId": "delete_tenant_template_v1_admin_tenants_templates_template_id_delete", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id", "description": "Template HashID (e.g., tentemplate_abc123)" }, "description": "Template HashID" } ], "responses": { "204": { "description": "No Content - template deleted successfully" }, "400": { "description": "Invalid template ID format" }, "404": { "description": "Template not found or insufficient permissions" } }, "security": [ { "APIKeyHeader": [] } ] } }, "/workflows/run": { "post": { "tags": [ "Workflows" ], "summary": "Run Workflow", "description": "Submit a workflow for asynchronous execution. Returns a job_id to poll for status and results.", "operationId": "run_workflow_v1_workflows_run_post", "requestBody": { "content": { "application/json": { "schema": { "properties": { "app_id": { "type": "string", "format": "uuid", "title": "App Id", "description": "The unique identifier of the workflow to run" }, "inputs": { "type": "object", "title": "Inputs", "description": "User inputs for the workflow. Key-value pairs where keys are variable_name from the workflow's input fields." }, "is_draft_app": { "type": "boolean", "title": "Is Draft App", "description": "Whether to run the draft version of the workflow", "default": false } }, "type": "object", "required": [ "app_id", "inputs" ], "title": "WorkflowJobRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "title": "Status", "description": "The status of the workflow job" }, "job_id": { "type": "string", "title": "Job Id", "description": "The unique identifier of the job run" } }, "type": "object", "required": [ "status", "job_id" ], "title": "WorkflowJobResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } }, "429": { "description": "Rate limited due to credit overage" } }, "security": [ { "APIKeyHeader": [] } ] } }, "/workflows/{job_id}": { "get": { "tags": [ "Workflows" ], "summary": "Get Workflow Job Status", "description": "Get the status of a workflow job and all its step outputs. Poll this endpoint to check for completion.", "operationId": "get_job_status_v1_workflows_job_id_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id", "description": "The job ID returned from the run endpoint" }, "description": "The job ID returned from the run endpoint" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "The job id" }, "app_id": { "type": "string", "title": "App Id", "description": "The app/workflow id" }, "entity_id": { "type": "string", "title": "Entity Id", "description": "The entity id" }, "user_id": { "type": "string", "title": "User Id", "description": "The user id who created this job" }, "created_at": { "type": "string", "title": "Created At", "description": "Job creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Job last update timestamp" }, "start_time": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Time", "description": "Start time in milliseconds" }, "end_time": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Time", "description": "End time in milliseconds" }, "number_of_steps": { "type": "integer", "title": "Number Of Steps", "description": "Total number of steps in this job" }, "status": { "type": "string", "title": "Status", "description": "The status of the job (pending, running, complete, failed)" }, "user_inputs": { "type": "object", "title": "User Inputs", "description": "The user inputs provided for this job" }, "app_data": { "type": "object", "title": "App Data", "description": "The app/workflow configuration data" }, "step_outputs": { "items": { "properties": { "step_id": { "type": "string", "title": "Step Id", "description": "The unique identifier for this workflow step" }, "job_id": { "type": "string", "title": "Job Id", "description": "The job id this step belongs to" }, "step_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Step Type", "description": "The type of step (e.g., 'prompt')" }, "status": { "type": "string", "title": "Status", "description": "The status of the step (e.g., 'complete')" }, "output_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Type", "description": "The type of output produced by this step" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp" }, "start_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time", "description": "Start time in milliseconds" }, "end_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time", "description": "End time in milliseconds" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration", "description": "Duration in milliseconds" }, "output_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Data", "description": "The output data produced by this step" }, "payload": { "type": "object", "title": "Payload", "description": "The configuration payload for this step" } }, "type": "object", "required": [ "step_id", "job_id", "status", "created_at", "updated_at", "payload" ], "title": "WorkflowStepRunResponse" }, "type": "array", "title": "Step Outputs", "description": "The step run results for this job" } }, "type": "object", "required": [ "job_id", "app_id", "entity_id", "user_id", "created_at", "updated_at", "number_of_steps", "status", "user_inputs", "app_data", "step_outputs" ], "title": "JobStatusResponse" } } } }, "404": { "description": "Job not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/workflows/presigned-url": { "post": { "tags": [ "Workflows" ], "summary": "Get Presigned URL for Workflow Output", "description": "Get a temporary download URL for a document produced by a workflow step.", "operationId": "presigned_url_v1_workflows_presigned_url_post", "requestBody": { "content": { "application/json": { "schema": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "Workflow job run ID" }, "step_id": { "type": "string", "title": "Step Id", "description": "Workflow step ID whose outputs contain the target file" }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Expiration in seconds", "default": 3600 } }, "type": "object", "required": [ "job_id", "step_id" ], "title": "PresignedUrlRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "title": "Url", "description": "Pre-signed URL for accessing the file" }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Expiration time in seconds" } }, "type": "object", "required": [ "url", "expires_in" ], "title": "PresignedUrlResponse" } } } }, "403": { "description": "Not authorized for this job" }, "404": { "description": "Job, step, or document not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "detail": { "items": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/chat/agents": { "get": { "tags": [ "Completions" ], "summary": "List Agents", "description": "Get the list of available agents. Agents are pre-configured AI assistants with custom instructions, tools, and knowledge sources. Use the agent's `id` with the `agent-{id}` model format in completions requests.", "operationId": "get_agents_v1_chat_agents_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentsListResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" } }, "security": [ { "APIKeyHeader": [] } ] } }, "/openai/responses": { "post": { "tags": [ "OpenAI Responses" ], "summary": "Create Response", "description": "OpenAI Responses-compatible endpoint. Mirrors OpenAI's `/v1/responses` wire format for use with OpenAI-compatible clients such as OpenCode and the AI SDK OpenAI provider.\n\nThis route is client-managed for tools: the model may return function call output items, but the server does not execute tools. Your client is responsible for executing tools and sending results back.", "operationId": "post_openai_responses", "security": [ { "APIKeyHeader": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "The model to use. Use model IDs from `/chat/models` (e.g. `gpt-5.2`, `gpt-4o`, `anthropic.claude-haiku-4-5`).", "example": "gpt-5.2" }, "input": { "description": "The input messages. An array of message objects following the OpenAI Responses input format.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system", "developer" ], "description": "The role of the message sender." }, "content": { "description": "The message content. Can be a string or an array of content parts.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The content part type (e.g. `input_text`, `input_image`)." }, "text": { "type": "string", "description": "The text content (for `input_text` type)." } } } } ] } } } } ] }, "instructions": { "type": "string", "description": "System-level instructions prepended to the conversation.", "nullable": true }, "stream": { "type": "boolean", "default": false, "description": "Whether to stream the response via Server-Sent Events." }, "temperature": { "type": "number", "nullable": true, "description": "Sampling temperature (0.0 to 2.0)." }, "top_p": { "type": "number", "nullable": true, "description": "Nucleus sampling parameter." }, "max_output_tokens": { "type": "integer", "nullable": true, "description": "Maximum number of tokens to generate." }, "tools": { "type": "array", "nullable": true, "description": "A list of tool definitions (function tools) the model may call.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The tool type. Currently only `function` is supported." }, "function": { "type": "object", "description": "The function definition.", "properties": { "name": { "type": "string", "description": "The function name." }, "description": { "type": "string", "description": "A description of the function." }, "parameters": { "type": "object", "description": "JSON Schema describing the function parameters." } } } } } }, "tool_choice": { "description": "Controls tool selection. Can be `auto`, `none`, `required`, or an object specifying a function.", "nullable": true }, "parallel_tool_calls": { "type": "boolean", "nullable": true, "description": "Whether the model can make multiple tool calls in parallel." }, "text": { "type": "object", "nullable": true, "description": "Text output configuration.", "properties": { "format": { "type": "object", "description": "Output format configuration.", "properties": { "type": { "type": "string", "enum": [ "text", "json_object" ], "description": "The output format type. `json_schema` is not yet supported." } } } } }, "store": { "type": "boolean", "nullable": true, "description": "Accepted for OpenAI/OpenCode compatibility but currently ignored." }, "include": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Accepted for OpenAI/OpenCode compatibility but currently ignored." }, "reasoning": { "description": "Accepted for OpenAI/OpenCode compatibility but currently ignored.", "nullable": true } } } } } }, "responses": { "200": { "description": "Successful response. Returns an OpenAI Responses-format object when `stream` is false, or a stream of Server-Sent Events when `stream` is true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique response identifier (e.g. `resp_...`).", "example": "resp_abc123def456" }, "object": { "type": "string", "enum": [ "response" ], "description": "The object type." }, "created_at": { "type": "integer", "description": "Unix timestamp of when the response was created." }, "status": { "type": "string", "enum": [ "completed", "incomplete" ], "description": "Whether the response completed successfully." }, "model": { "type": "string", "description": "The model used." }, "output": { "type": "array", "description": "The output items. Can include message items and function call items.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "function_call" ] }, "role": { "type": "string", "description": "The role (for message items)." }, "status": { "type": "string" }, "content": { "type": "array", "description": "Message content parts (for message items).", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" }, "annotations": { "type": "array", "items": { "type": "object" } } } } }, "call_id": { "type": "string", "description": "The tool call ID (for function_call items)." }, "name": { "type": "string", "description": "The function name (for function_call items)." }, "arguments": { "type": "string", "description": "JSON-encoded function arguments (for function_call items)." } } } }, "output_text": { "type": "string", "description": "Convenience field with the full assistant text output." }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "incomplete_details": { "type": "object", "nullable": true, "description": "Present only when status is `incomplete`.", "properties": { "reason": { "type": "string" } } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream (when `stream: true`). Events include `response.created`, `response.output_item.added`, `response.output_text.delta`, `response.function_call_arguments.delta`, `response.output_item.done`, `response.completed`, and `response.incomplete`." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "502": { "description": "Upstream model provider error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } } }, "/payments/invoices": { "get": { "tags": [ "Billing" ], "summary": "List Invoices", "description": "List your organization's finalized invoices, newest first.\n\nDraft invoices are excluded: a draft is a bill Stripe is still assembling, so its amounts can still change and it may never be issued.\n\n`start` and `end` are whole UTC dates (`YYYY-MM-DD`) and filter on the date the invoice was **issued** (`created`), not the billing period it covers. `end` is inclusive of that entire day.\n\nMonetary fields are integers in the smallest currency unit (cents for USD), matching Stripe — divide by 100 before displaying.\n\nResults are cursor-paginated: when `has_more` is true, pass `next_cursor` as `starting_after`. Page until `has_more` is false, not until a page comes back empty — drafts are removed after Stripe has counted them toward the page, so a page can hold fewer invoices than `limit`, or none, while `has_more` is still true.\n\nRequires the `billing_report` permission. An API key carries the permissions of the user it belongs to.", "operationId": "list_invoices_v1_payments_invoices_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Start" }, "description": "Only invoices issued on or after this UTC date (YYYY-MM-DD)." }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End" }, "description": "Only invoices issued on or before this UTC date (YYYY-MM-DD), inclusive of the whole day." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "title": "Limit" }, "description": "Invoices per page (1-100)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Starting After" }, "description": "Invoice ID to page after — pass the previous response's next_cursor." }, { "name": "entity_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Id" }, "description": "Which of your organizations to read. Required only if you hold billing access to more than one." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListResponse" } } } }, "400": { "description": "The `entity_id` value is not a recognizable id: not a UUID, a tenant external id, or a `tenant_` HashID.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "403": { "description": "You do not have permission to view invoices for this account.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "404": { "description": "No billing account found for this organization.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "409": { "description": "You have billing access to more than one account. Pass `entity_id` to choose one.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "422": { "description": "Invalid parameters — for example `start` after `end`, or a limit outside 1-100.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "503": { "description": "Billing account or permissions could not be verified. Retry.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } } } } }, "/payments/invoices/{invoice_id}/pdf": { "get": { "tags": [ "Billing" ], "summary": "Get Invoice PDF Link", "description": "Return the download link for one invoice's PDF.\n\nThe link points at Stripe and carries its own access token, so you download the file directly from Stripe rather than through this API. Draft invoices are not served by this API and return 404.\n\nRequires the `billing_report` permission. An invoice belonging to another organization returns 404.", "operationId": "get_invoice_pdf_v1_payments_invoices_invoice_id_pdf_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Invoice Id" }, "description": "Stripe invoice ID, as returned by GET /payments/invoices." }, { "name": "entity_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Id" }, "description": "Which of your organizations the invoice belongs to. Required only if you hold billing access to more than one." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePdfResponse" } } } }, "400": { "description": "The `entity_id` value is not a recognizable id: not a UUID, a tenant external id, or a `tenant_` HashID.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "403": { "description": "You do not have permission to view invoices for this account.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "404": { "description": "No such invoice for this organization, the invoice is a draft, or it has no PDF.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "409": { "description": "You have billing access to more than one account. Pass `entity_id` to choose one.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "422": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "503": { "description": "Billing account or permissions could not be verified. Retry.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } } } } }, "/payments/invoices/{invoice_id}/breakdown": { "get": { "tags": [ "Billing" ], "summary": "Get Invoice Tenant Breakdown", "description": "Split one invoice's total across the tenants it charges for.\n\nUse this to re-bill: the list endpoint tells you what you owe, this tells you who incurred it. Each line is traced through its subscription item to the tenant holding that license, and amounts are summed per tenant.\n\n`total_cents` always equals the sum of `tenants[].amount_cents` plus `unallocated_cents`, so the split reconciles to what is actually owed rather than to a pre-tax subtotal. Charges that belong to no tenant — one-off items, invoice-level discounts, credits, tax — land in `unallocated_cents`, which can be negative when a credit exceeds them.\n\n`lines` carries every line on the invoice regardless, each naming the tenant it reached or, in `unallocated_reason`, why it reached none. That is what an invoice with nothing tenant-attributable returns instead of a bare `unallocated_cents` equal to the total.\n\nDraft invoices return 404.\n\nRequires the `billing_report` permission.", "operationId": "get_invoice_tenant_breakdown_v1_payments_invoices_invoice_id_breakdown_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Invoice Id" }, "description": "Stripe invoice ID, as returned by GET /payments/invoices." }, { "name": "entity_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Id" }, "description": "Which of your organizations the invoice belongs to. Required only if you hold billing access to more than one." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceTenantBreakdownResponse" } } } }, "400": { "description": "The `entity_id` value is not a recognizable id: not a UUID, a tenant external id, or a `tenant_` HashID.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "403": { "description": "You do not have permission to view invoices for this account.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "404": { "description": "No such invoice for this organization, or the invoice is a draft.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "409": { "description": "You have billing access to more than one account. Pass `entity_id` to choose one.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "422": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } }, "503": { "description": "Billing account or permissions could not be verified. Retry.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "path": { "type": "string" } } } }, "type": "object", "title": "ErrorResponse" } } } } } } }, "/academy/reporting/exports": { "post": { "tags": [ "Hatz Learn Reporting" ], "summary": "Export Learning Report", "operationId": "export_learning_report_v1_academy_reporting_exports_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportReportRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportReportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/academy/reporting/exports/capability": { "get": { "tags": [ "Hatz Learn Reporting" ], "summary": "Get Export Capability", "operationId": "get_export_capability_v1_academy_reporting_exports_capability_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCapabilityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/academy/reporting/portfolio": { "get": { "tags": [ "Hatz Learn Reporting" ], "summary": "Get Learning Portfolio", "operationId": "get_learning_portfolio_v1_academy_reporting_portfolio_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Opaque cursor from the prior page; reuse with the same sort settings.", "title": "Cursor" }, "description": "Opaque cursor from the prior page; reuse with the same sort settings." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Tenants per page.", "default": 50, "title": "Limit" }, "description": "Tenants per page." }, { "name": "sort_direction", "in": "query", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string", "description": "Case-insensitive tenant-name order.", "default": "asc", "title": "Sort Direction" }, "description": "Case-insensitive tenant-name order." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortfolioResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/academy/reporting/portfolio/summary": { "get": { "tags": [ "Hatz Learn Reporting" ], "summary": "Get Learning Portfolio Summary", "operationId": "get_learning_portfolio_summary_v1_academy_reporting_portfolio_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortfolioSummaryResponse" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/academy/reporting/tenants/{tenant_id}/summary": { "get": { "tags": [ "Hatz Learn Reporting" ], "summary": "Get Tenant Learning Summary", "operationId": "get_tenant_learning_summary_v1_academy_reporting_tenants__tenant_id__summary_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantLearningSummary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/academy/reporting/tenants/{tenant_id}/learners": { "get": { "tags": [ "Hatz Learn Reporting" ], "summary": "List Tenant Learners", "operationId": "list_tenant_learners_v1_academy_reporting_tenants__tenant_id__learners_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Learner name or email search.", "title": "Search" }, "description": "Learner name or email search." }, { "name": "course_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Restrict to one course.", "title": "Course Id" }, "description": "Restrict to one course." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "not_enrolled", "not_started", "in_progress", "completed", "access_revoked", "retired" ], "type": "string" }, { "type": "null" } ], "description": "Restrict to one effective course status.", "title": "Status" }, "description": "Restrict to one effective course status." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Opaque cursor from the prior page; reuse with the same filters and sort.", "title": "Cursor" }, "description": "Opaque cursor from the prior page; reuse with the same filters and sort." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Learners per page.", "default": 50, "title": "Limit" }, "description": "Learners per page." }, { "name": "sort_direction", "in": "query", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string", "description": "Case-insensitive learner-name order.", "default": "asc", "title": "Sort Direction" }, "description": "Case-insensitive learner-name order." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearnerListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/academy/reporting/tenants/{tenant_id}/courses": { "get": { "tags": [ "Hatz Learn Reporting" ], "summary": "List Tenant Courses", "operationId": "list_tenant_courses_v1_academy_reporting_tenants__tenant_id__courses_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Course-title search.", "title": "Search" }, "description": "Course-title search." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Opaque cursor from the prior page; reuse with the same filters and sort.", "title": "Cursor" }, "description": "Opaque cursor from the prior page; reuse with the same filters and sort." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Courses per page.", "default": 50, "title": "Limit" }, "description": "Courses per page." }, { "name": "sort_direction", "in": "query", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string", "description": "Case-insensitive course-title order.", "default": "asc", "title": "Sort Direction" }, "description": "Case-insensitive course-title order." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/academy/reporting/tenants/{tenant_id}/learners/{learner_id}": { "get": { "tags": [ "Hatz Learn Reporting" ], "summary": "Get Learner Learning Detail", "operationId": "get_learner_learning_detail_v1_academy_reporting_tenants__tenant_id__learners__learner_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } }, { "name": "learner_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Learner Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearnerDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/academy/reporting/tenants/{tenant_id}/courses/{course_id}": { "get": { "tags": [ "Hatz Learn Reporting" ], "summary": "Get Course Learning Detail", "operationId": "get_course_learning_detail_v1_academy_reporting_tenants__tenant_id__courses__course_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } }, { "name": "course_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Course Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "not_enrolled", "not_started", "in_progress", "completed", "access_revoked", "retired" ], "type": "string" }, { "type": "null" } ], "description": "Restrict to one effective learner status.", "title": "Status" }, "description": "Restrict to one effective learner status." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Opaque cursor from the prior page; reuse with the same filters and sort.", "title": "Cursor" }, "description": "Opaque cursor from the prior page; reuse with the same filters and sort." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Learners per page.", "default": 50, "title": "Limit" }, "description": "Learners per page." }, { "name": "sort_direction", "in": "query", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string", "description": "Case-insensitive learner-name order.", "default": "asc", "title": "Sort Direction" }, "description": "Case-insensitive learner-name order." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AIModel": { "properties": { "name": { "type": "string", "title": "Name", "description": "The unique identifier/name of the AI model. Use this to specify the model in requests." }, "developer": { "type": "string", "title": "Developer", "description": "The company/organization that developed this model" }, "display_name": { "type": "string", "title": "Display Name", "description": "The human-readable display name for this model" }, "max_tokens": { "type": "integer", "title": "Max Tokens", "description": "The maximum number of tokens this model can process" }, "vision": { "type": "boolean", "title": "Vision", "description": "Whether this model has vision/image processing capabilities" } }, "type": "object", "required": [ "name", "developer", "display_name", "max_tokens", "vision" ], "title": "AIModel" }, "AppConstant": { "properties": { "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this constant" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "A description of this constant" }, "variable_type": { "type": "string", "enum": [ "text" ], "const": "text", "title": "Variable Type", "description": "The type of constant (only 'text' supported)" }, "value": { "type": "string", "title": "Value", "description": "The value of this constant" } }, "type": "object", "required": [ "object_id", "variable_name", "display_name", "variable_type", "value" ], "title": "AppConstant" }, "AppFileResponse": { "properties": { "size": { "type": "integer", "title": "Size", "description": "The size of the file in bytes" }, "module": { "type": "string", "title": "Module", "description": "The module this file belongs to" }, "file_id": { "type": "string", "title": "File Id", "description": "The unique identifier for this file", "default": "" }, "type_id": { "type": "string", "title": "Type Id", "description": "The type identifier for this file", "default": "" }, "file_key": { "type": "string", "title": "File Key", "description": "The key/name of the file" }, "file_type": { "type": "string", "title": "File Type", "description": "The type of file (e.g. PDF)" }, "object_id": { "type": "string", "title": "Object Id", "description": "The object identifier for this file" }, "description": { "type": "string", "title": "Description", "description": "A description of the file" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name of the file" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name associated with this file" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of variable this file represents" } }, "type": "object", "required": [ "size", "module", "file_key", "file_type", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppFileResponse" }, "AppListResponse": { "properties": { "data": { "items": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the app" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The description of the app" }, "default_model": { "type": "string", "title": "Default Model", "description": "The default AI model to use", "default": "gpt-4o" }, "files": { "items": { "properties": { "size": { "type": "integer", "title": "Size", "description": "The size of the file in bytes" }, "module": { "type": "string", "title": "Module", "description": "The module this file belongs to" }, "file_id": { "type": "string", "title": "File Id", "description": "The unique identifier for this file", "default": "" }, "type_id": { "type": "string", "title": "Type Id", "description": "The type identifier for this file", "default": "" }, "file_key": { "type": "string", "title": "File Key", "description": "The key/name of the file" }, "file_type": { "type": "string", "title": "File Type", "description": "The type of file (e.g. PDF)" }, "object_id": { "type": "string", "title": "Object Id", "description": "The object identifier for this file" }, "description": { "type": "string", "title": "Description", "description": "A description of the file" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name of the file" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name associated with this file" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of variable this file represents" } }, "type": "object", "required": [ "size", "module", "file_key", "file_type", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppFileResponse" }, "type": "array", "title": "Files", "description": "The files associated with this app" }, "constants": { "items": { "properties": { "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this constant" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "A description of this constant" }, "variable_type": { "type": "string", "enum": [ "text" ], "const": "text", "title": "Variable Type", "description": "The type of constant (only 'text' supported)" }, "value": { "type": "string", "title": "Value", "description": "The value of this constant" } }, "type": "object", "required": [ "object_id", "variable_name", "display_name", "variable_type", "value" ], "title": "AppConstant" }, "type": "array", "title": "Constants", "description": "The constants associated with this app", "default": [] }, "user_inputs": { "items": { "properties": { "position": { "type": "integer", "title": "Position", "description": "The position/order of this input field" }, "required": { "type": "boolean", "title": "Required", "description": "Whether this input is required" }, "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this input" }, "description": { "type": "string", "title": "Description", "description": "A description of this input field" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of input (e.g. short_answer)" } }, "type": "object", "required": [ "position", "required", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppUserInputResponse" }, "type": "array", "title": "User Inputs", "description": "The user inputs associated with this app" }, "prompt_sections": { "items": { "properties": { "body": { "type": "string", "title": "Body" }, "position": { "type": "integer", "title": "Position" } }, "type": "object", "required": [ "body", "position" ], "title": "PromptSection" }, "type": "array", "title": "Prompt Sections", "description": "The prompt sections associated with this app" } }, "type": "object", "required": [ "name", "files", "user_inputs", "prompt_sections" ], "title": "AppResponse" }, "type": "array", "title": "Data", "description": "The list of apps" } }, "type": "object", "required": [ "data" ], "title": "AppListResponse" }, "AppQueryRequest": { "properties": { "inputs": { "type": "object", "title": "Inputs", "description": "The list of inputs on the app to process. Usually in the form of JSON object like {'\\': '\\'}. The variable name should be the same as the variable name in the app." }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "The AI model to use for processing. Please use the unique name of the model, not the display name", "default": "gpt-4o" }, "stream": { "type": "boolean", "title": "Stream", "description": "Whether to stream the response", "default": false }, "file_uuids": { "anyOf": [ { "items": { "type": "string", "format": "uuid4" }, "type": "array" }, { "type": "null" } ], "title": "File Uuids", "description": "The list of file uuids to process", "default": [] } }, "type": "object", "required": [ "inputs" ], "title": "AppQueryRequest" }, "AppResponse": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the app" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The description of the app" }, "default_model": { "type": "string", "title": "Default Model", "description": "The default AI model to use", "default": "gpt-4o" }, "files": { "items": { "properties": { "size": { "type": "integer", "title": "Size", "description": "The size of the file in bytes" }, "module": { "type": "string", "title": "Module", "description": "The module this file belongs to" }, "file_id": { "type": "string", "title": "File Id", "description": "The unique identifier for this file", "default": "" }, "type_id": { "type": "string", "title": "Type Id", "description": "The type identifier for this file", "default": "" }, "file_key": { "type": "string", "title": "File Key", "description": "The key/name of the file" }, "file_type": { "type": "string", "title": "File Type", "description": "The type of file (e.g. PDF)" }, "object_id": { "type": "string", "title": "Object Id", "description": "The object identifier for this file" }, "description": { "type": "string", "title": "Description", "description": "A description of the file" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name of the file" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name associated with this file" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of variable this file represents" } }, "type": "object", "required": [ "size", "module", "file_key", "file_type", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppFileResponse" }, "type": "array", "title": "Files", "description": "The files associated with this app" }, "constants": { "items": { "properties": { "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this constant" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "A description of this constant" }, "variable_type": { "type": "string", "enum": [ "text" ], "const": "text", "title": "Variable Type", "description": "The type of constant (only 'text' supported)" }, "value": { "type": "string", "title": "Value", "description": "The value of this constant" } }, "type": "object", "required": [ "object_id", "variable_name", "display_name", "variable_type", "value" ], "title": "AppConstant" }, "type": "array", "title": "Constants", "description": "The constants associated with this app", "default": [] }, "user_inputs": { "items": { "properties": { "position": { "type": "integer", "title": "Position", "description": "The position/order of this input field" }, "required": { "type": "boolean", "title": "Required", "description": "Whether this input is required" }, "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this input" }, "description": { "type": "string", "title": "Description", "description": "A description of this input field" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of input (e.g. short_answer)" } }, "type": "object", "required": [ "position", "required", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppUserInputResponse" }, "type": "array", "title": "User Inputs", "description": "The user inputs associated with this app" }, "prompt_sections": { "items": { "properties": { "body": { "type": "string", "title": "Body" }, "position": { "type": "integer", "title": "Position" } }, "type": "object", "required": [ "body", "position" ], "title": "PromptSection" }, "type": "array", "title": "Prompt Sections", "description": "The prompt sections associated with this app" } }, "type": "object", "required": [ "name", "files", "user_inputs", "prompt_sections" ], "title": "AppResponse" }, "AppUserInputResponse": { "properties": { "position": { "type": "integer", "title": "Position", "description": "The position/order of this input field" }, "required": { "type": "boolean", "title": "Required", "description": "Whether this input is required" }, "object_id": { "type": "string", "title": "Object Id", "description": "The unique object identifier for this input" }, "description": { "type": "string", "title": "Description", "description": "A description of this input field" }, "display_name": { "type": "string", "title": "Display Name", "description": "The display name shown to users" }, "variable_name": { "type": "string", "title": "Variable Name", "description": "The variable name used internally" }, "variable_type": { "type": "string", "title": "Variable Type", "description": "The type of input (e.g. short_answer)" } }, "type": "object", "required": [ "position", "required", "object_id", "description", "display_name", "variable_name", "variable_type" ], "title": "AppUserInputResponse" }, "Body_upload_file_v1_files_upload_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "only_calculate_tokens": { "type": "boolean", "title": "Only Calculate Tokens", "default": false } }, "type": "object", "required": [ "file" ], "title": "Body_upload_file_v1_files_upload_post" }, "CompletionRequest": { "properties": { "messages": { "items": { "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ], "title": "Role", "description": "The role of the message sender" }, "content": { "type": "string", "title": "Content", "description": "The content of the message" } }, "type": "object", "required": [ "role", "content" ], "title": "Message" }, "type": "array", "title": "Messages", "description": "The list of messages to process" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "The AI model to use for processing. Please use the unique name of the model, not the display name", "default": "gpt-4o" }, "stream": { "type": "boolean", "title": "Stream", "description": "Whether to stream the response", "default": false }, "file_uuids": { "anyOf": [ { "items": { "type": "string", "format": "uuid4" }, "type": "array" }, { "type": "null" } ], "title": "File Uuids", "description": "The list of file uuids to process", "default": [] }, "tools_to_use": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tools To Use", "description": "A list of tool names to enable for this request. Tools allow the model to perform actions like web search, code execution, and more. See the documentation for available tool names.", "default": [] }, "auto_tool_selection": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Tool Selection", "description": "When true, the system will automatically select relevant tools based on the user's message. Defaults to false.", "default": false } }, "type": "object", "required": [ "messages" ], "title": "CompletionRequest" }, "CompletionResponse": { "properties": { "choices": { "items": { "properties": { "message": { "description": "The message response from the AI", "properties": { "content": { "type": "string", "title": "Content", "description": "The content of the response message" }, "role": { "type": "string", "enum": [ "assistant" ], "const": "assistant", "title": "Role", "description": "The role of the message sender" } }, "type": "object", "required": [ "content", "role" ], "title": "CompletionResponseMessage" } }, "type": "object", "required": [ "message" ], "title": "CompletionResponseChoice" }, "type": "array", "title": "Choices", "description": "List of completion choices" }, "model": { "type": "string", "title": "Model", "description": "The AI model used for processing" }, "usage": { "description": "Token usage statistics", "properties": { "input_tokens": { "type": "integer", "title": "Input Tokens", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "title": "Output Tokens", "description": "Number of output tokens used" } }, "type": "object", "required": [ "input_tokens", "output_tokens" ], "title": "Usage" } }, "type": "object", "required": [ "choices", "model", "usage" ], "title": "CompletionResponse" }, "CompletionResponseChoice": { "properties": { "message": { "description": "The message response from the AI", "properties": { "content": { "type": "string", "title": "Content", "description": "The content of the response message" }, "role": { "type": "string", "enum": [ "assistant" ], "const": "assistant", "title": "Role", "description": "The role of the message sender" } }, "type": "object", "required": [ "content", "role" ], "title": "CompletionResponseMessage" } }, "type": "object", "required": [ "message" ], "title": "CompletionResponseChoice" }, "CompletionResponseMessage": { "properties": { "content": { "type": "string", "title": "Content", "description": "The content of the response message" }, "role": { "type": "string", "enum": [ "assistant" ], "const": "assistant", "title": "Role", "description": "The role of the message sender" } }, "type": "object", "required": [ "content", "role" ], "title": "CompletionResponseMessage" }, "CompletionsStreamingResponse": { "properties": { "type": { "type": "string", "title": "Type", "description": "The type of response (e.g. completion)" }, "message": { "type": "string", "title": "Message", "description": "The message to be streamed" } }, "type": "object", "required": [ "type", "message" ], "title": "CompletionsStreamingResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Message": { "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ], "title": "Role", "description": "The role of the message sender" }, "content": { "type": "string", "title": "Content", "description": "The content of the message" } }, "type": "object", "required": [ "role", "content" ], "title": "Message" }, "ModelsResponse": { "properties": { "data": { "items": { "properties": { "name": { "type": "string", "title": "Name", "description": "The unique identifier/name of the AI model. Use this to specify the model in requests." }, "developer": { "type": "string", "title": "Developer", "description": "The company/organization that developed this model" }, "display_name": { "type": "string", "title": "Display Name", "description": "The human-readable display name for this model" }, "max_tokens": { "type": "integer", "title": "Max Tokens", "description": "The maximum number of tokens this model can process" }, "vision": { "type": "boolean", "title": "Vision", "description": "Whether this model has vision/image processing capabilities" } }, "type": "object", "required": [ "name", "developer", "display_name", "max_tokens", "vision" ], "title": "AIModel" }, "type": "array", "title": "Data", "description": "The list of available AI models" } }, "type": "object", "required": [ "data" ], "title": "ModelsResponse" }, "PromptSection": { "properties": { "body": { "type": "string", "title": "Body" }, "position": { "type": "integer", "title": "Position" } }, "type": "object", "required": [ "body", "position" ], "title": "PromptSection" }, "Usage": { "properties": { "input_tokens": { "type": "integer", "title": "Input Tokens", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "title": "Output Tokens", "description": "Number of output tokens used" } }, "type": "object", "required": [ "input_tokens", "output_tokens" ], "title": "Usage" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "NewUser": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "User role in the organization" } }, "type": "object", "required": [ "email" ], "title": "NewUser" }, "AdminInviteUsersInput": { "properties": { "tenant_id": { "type": "string", "pattern": "^tenant_[a-zA-Z0-9]+$", "title": "Tenant Id", "description": "Tenant HashID" }, "users": { "items": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "User role in the organization" } }, "type": "object", "required": [ "email" ], "title": "NewUser" }, "type": "array", "minItems": 1, "maxItems": 100, "title": "Users", "description": "List of users to invite" } }, "type": "object", "required": [ "tenant_id", "users" ], "title": "AdminInviteUsersInput" }, "AdminInviteUsersOutput": { "properties": { "message": { "type": "string", "title": "Message", "description": "Success message" }, "total_new_users_created": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total New Users Created", "description": "Number of new users successfully created", "default": 0 }, "total_new_users_failed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total New Users Failed", "description": "Number of new users that failed to create", "default": 0 }, "new_users_failed_emails": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "New Users Failed Emails", "description": "Email addresses of users that failed", "default": [] }, "results": { "anyOf": [ { "items": { "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Results", "description": "Per-user results with any errors" } }, "type": "object", "required": [ "message" ], "title": "AdminInviteUsersOutput" }, "AdminUserOutput": { "properties": { "id": { "type": "string", "title": "Id", "description": "User HashID" }, "email": { "type": "string", "title": "Email", "description": "User email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id", "description": "Tenant HashID" }, "role_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role Name", "description": "User role" }, "last_sign_in_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sign In At", "description": "Last sign in timestamp" } }, "type": "object", "required": [ "id", "email" ], "title": "AdminUserOutput" }, "AdminMSPUserOutput": { "properties": { "id": { "type": "string", "title": "Id", "description": "User HashID" }, "email": { "type": "string", "title": "Email", "description": "User email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role Name", "description": "User role" }, "last_sign_in_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sign In At", "description": "Last sign in timestamp" } }, "type": "object", "required": [ "id", "email" ], "title": "AdminMSPUserOutput" }, "AdminDeleteUserOutput": { "properties": { "message": { "type": "string", "title": "Message", "description": "Success message" }, "user_id": { "type": "string", "title": "User Id", "description": "HashID of deleted user" } }, "type": "object", "required": [ "message", "user_id" ], "title": "AdminDeleteUserOutput" }, "AdminUpdateUserInput": { "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role Name", "description": "New role name" }, "tenant_id": { "anyOf": [ { "type": "string", "pattern": "^tenant_[a-zA-Z0-9]+$" }, { "type": "null" } ], "title": "Tenant Id", "description": "Move user to this tenant" } }, "type": "object", "title": "AdminUpdateUserInput" }, "AdminUpdateUserOutput": { "properties": { "message": { "type": "string", "title": "Message", "description": "Success message" }, "user_id": { "type": "string", "title": "User Id", "description": "HashID of updated user" } }, "type": "object", "required": [ "message", "user_id" ], "title": "AdminUpdateUserOutput" }, "AdminTenantOutput": { "properties": { "id": { "type": "string", "title": "Id", "description": "Tenant HashID" }, "name": { "type": "string", "title": "Name", "description": "Tenant name" }, "primary_package_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Package Name", "description": "Primary package name" }, "additional_package_names": { "items": { "type": "string" }, "type": "array", "title": "Additional Package Names", "description": "Additional packages", "default": [] }, "user_count": { "type": "integer", "title": "User Count", "description": "Number of users", "default": 0 }, "status": { "type": "string", "title": "Status", "description": "Tenant status", "default": "Active" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp" }, "total_credits_used": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credits Used", "description": "Credits used" }, "total_credit_limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credit Limit", "description": "Total credit limit" }, "tenant_config": { "description": "Tenant configuration settings", "properties": { "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled", "default": false }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required for this tenant", "default": false }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o')" } }, "type": "object", "title": "TenantConfig" }, "disabled_model_names": { "items": { "type": "string" }, "type": "array", "title": "Disabled Model Names", "description": "List of disabled AI model names", "default": [] } }, "type": "object", "required": [ "id", "name" ], "title": "AdminTenantOutput" }, "AdminMSPOutput": { "properties": { "name": { "type": "string", "title": "Name", "description": "MSP name" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp" }, "primary_package_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Package Name", "description": "Primary package name" }, "additional_package_names": { "items": { "type": "string" }, "type": "array", "title": "Additional Package Names", "description": "Additional package names", "default": [] }, "packages": { "type": "object", "title": "Packages", "description": "Package details", "default": {} }, "total_credits_used": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credits Used", "description": "Total credits used", "default": 0 }, "total_credit_limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Credit Limit", "description": "Total credit limit", "default": 0 }, "admin_user_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Admin User Count", "description": "Admin user count", "default": 0 }, "admin_recent_signin_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Admin Recent Signin Count", "description": "Recent admin sign-ins", "default": 0 }, "admin_login_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Admin Login Rate", "description": "Admin login rate", "default": 0 }, "tenant_user_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tenant User Count", "description": "Tenant user count", "default": 0 }, "tenant_recent_signin_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tenant Recent Signin Count", "description": "Recent tenant sign-ins", "default": 0 }, "tenant_login_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Tenant Login Rate", "description": "Tenant login rate", "default": 0 } }, "type": "object", "required": [ "name" ], "title": "AdminMSPOutput" }, "TenantCreateInput": { "properties": { "tenant_name": { "type": "string", "minLength": 1, "maxLength": 255, "title": "Tenant Name", "description": "Tenant name (spaces allowed)" }, "package_id": { "anyOf": [ { "type": "string", "pattern": "^package_[a-zA-Z0-9]+$" }, { "type": "null" } ], "title": "Package Id", "description": "Package HashID. Optional if template_id is provided." }, "template_id": { "anyOf": [ { "type": "string", "pattern": "^tentemplate_[a-zA-Z0-9]+$" }, { "type": "null" } ], "title": "Template Id", "description": "Tenant creation template HashID. If provided, license_type_id will be resolved from template. Optional if package_id is provided." }, "users": { "items": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "User role in the organization" } }, "type": "object", "required": [ "email" ], "title": "NewUser" }, "type": "array", "maxItems": 1000, "title": "Users", "description": "Initial users for the tenant (optional)", "default": [] } }, "type": "object", "required": [ "tenant_name" ], "title": "TenantCreateInput" }, "AdminCreateTenantsInput": { "properties": { "tenants": { "items": { "properties": { "tenant_name": { "type": "string", "minLength": 1, "maxLength": 255, "title": "Tenant Name", "description": "Tenant name (spaces allowed)" }, "package_id": { "anyOf": [ { "type": "string", "pattern": "^package_[a-zA-Z0-9]+$" }, { "type": "null" } ], "title": "Package Id", "description": "Package HashID. Optional if template_id is provided." }, "template_id": { "anyOf": [ { "type": "string", "pattern": "^tentemplate_[a-zA-Z0-9]+$" }, { "type": "null" } ], "title": "Template Id", "description": "Tenant creation template HashID. If provided, license_type_id will be resolved from template. Optional if package_id is provided." }, "users": { "items": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "User role in the organization" } }, "type": "object", "required": [ "email" ], "title": "NewUser" }, "type": "array", "maxItems": 1000, "title": "Users", "description": "Initial users for the tenant (optional)", "default": [] } }, "type": "object", "required": [ "tenant_name" ], "title": "TenantCreateInput" }, "type": "array", "minItems": 1, "maxItems": 100, "title": "Tenants", "description": "List of tenants to create" } }, "type": "object", "required": [ "tenants" ], "title": "AdminCreateTenantsInput" }, "AdminCreateTenantsOutput": { "properties": { "message": { "type": "string", "title": "Message", "description": "Operation summary message" }, "total_tenants_created": { "type": "integer", "title": "Total Tenants Created", "description": "Number of tenants successfully created" }, "total_tenants_failed": { "type": "integer", "title": "Total Tenants Failed", "description": "Number of tenants that failed to create" }, "tenants": { "items": { "type": "object" }, "type": "array", "title": "Tenants", "description": "Detailed results for each tenant" } }, "type": "object", "required": [ "message", "total_tenants_created", "total_tenants_failed", "tenants" ], "title": "AdminCreateTenantsOutput" }, "TenantConfig": { "properties": { "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled", "default": false }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required for this tenant", "default": false }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o')" } }, "type": "object", "title": "TenantConfig" }, "AdminPackageOutput": { "properties": { "id": { "type": "string", "title": "Id", "description": "Package HashID" }, "name": { "type": "string", "title": "Name", "description": "Package name" } }, "type": "object", "required": [ "id", "name" ], "title": "AdminPackageOutput" }, "TenantConfigUpdate": { "properties": { "beta_features": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Beta Features", "description": "Whether beta features are enabled" }, "mfa_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "MFA Required", "description": "Whether MFA is required for this tenant" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o'). Set to empty string to clear." } }, "type": "object", "title": "TenantConfigUpdate" }, "AdminTenantTemplateOutput": { "properties": { "id": { "type": "string", "title": "Id", "description": "Template HashID" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "package_name": { "type": "string", "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name" }, "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled" }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "package_name", "beta_features", "mfa_required", "created_at", "updated_at" ], "title": "AdminTenantTemplateOutput" }, "AdminTenantTemplatesListOutput": { "properties": { "templates": { "items": { "properties": { "id": { "type": "string", "title": "Id", "description": "Template HashID" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "package_name": { "type": "string", "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name" }, "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Whether beta features are enabled" }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Whether MFA is required" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "package_name", "beta_features", "mfa_required", "created_at", "updated_at" ], "title": "AdminTenantTemplateOutput" }, "type": "array", "title": "Templates", "description": "List of templates" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for next page" } }, "type": "object", "required": [ "templates" ], "title": "AdminTenantTemplatesListOutput" }, "AdminTenantTemplateCreateInput": { "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 255, "title": "Name", "description": "Template name" }, "package_name": { "type": "string", "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o')" }, "beta_features": { "type": "boolean", "title": "Beta Features", "description": "Enable beta features", "default": false }, "mfa_required": { "type": "boolean", "title": "MFA Required", "description": "Require MFA", "default": false } }, "type": "object", "required": [ "name", "package_name" ], "title": "AdminTenantTemplateCreateInput" }, "AdminTenantTemplateUpdateInput": { "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "Template name" }, "package_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Package Name", "description": "Package name" }, "default_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Model Name", "description": "Default AI model name (e.g., 'gpt-4o'). Set to empty string to clear." }, "beta_features": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Beta Features", "description": "Enable beta features" }, "mfa_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "MFA Required", "description": "Require MFA" } }, "type": "object", "title": "AdminTenantTemplateUpdateInput" }, "AdminInviteMspUsersInput": { "properties": { "users": { "items": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "User first name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "User last name" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "User role in the organization" } }, "type": "object", "required": [ "email" ], "title": "NewUser" }, "type": "array", "minItems": 1, "maxItems": 100, "title": "Users", "description": "List of users to invite" } }, "type": "object", "required": [ "users" ], "title": "AdminInviteMspUsersInput" }, "WorkflowJobRequest": { "properties": { "app_id": { "type": "string", "format": "uuid", "title": "App Id", "description": "The unique identifier of the workflow to run" }, "inputs": { "type": "object", "title": "Inputs", "description": "User inputs for the workflow" }, "is_draft_app": { "type": "boolean", "title": "Is Draft App", "description": "Whether to run the draft version", "default": false } }, "type": "object", "required": [ "app_id", "inputs" ], "title": "WorkflowJobRequest" }, "WorkflowJobResponse": { "properties": { "status": { "type": "string", "title": "Status", "description": "The status of the workflow job" }, "job_id": { "type": "string", "title": "Job Id", "description": "The unique identifier of the job run" } }, "type": "object", "required": [ "status", "job_id" ], "title": "WorkflowJobResponse" }, "WorkflowStepRunResponse": { "properties": { "step_id": { "type": "string", "title": "Step Id", "description": "The unique identifier for this workflow step" }, "job_id": { "type": "string", "title": "Job Id", "description": "The job id this step belongs to" }, "step_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Step Type", "description": "The type of step (e.g., 'prompt')" }, "status": { "type": "string", "title": "Status", "description": "The status of the step (e.g., 'complete')" }, "output_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Type", "description": "The type of output produced by this step" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp" }, "start_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time", "description": "Start time in milliseconds" }, "end_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time", "description": "End time in milliseconds" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration", "description": "Duration in milliseconds" }, "output_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Data", "description": "The output data produced by this step" }, "payload": { "type": "object", "title": "Payload", "description": "The configuration payload for this step" } }, "type": "object", "required": [ "step_id", "job_id", "status", "created_at", "updated_at", "payload" ], "title": "WorkflowStepRunResponse" }, "JobStatusResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "app_id": { "type": "string", "title": "App Id" }, "entity_id": { "type": "string", "title": "Entity Id" }, "user_id": { "type": "string", "title": "User Id" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "start_time": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Time" }, "end_time": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Time" }, "number_of_steps": { "type": "integer", "title": "Number Of Steps" }, "status": { "type": "string", "title": "Status" }, "user_inputs": { "type": "object", "title": "User Inputs" }, "app_data": { "type": "object", "title": "App Data" }, "step_outputs": { "items": { "properties": { "step_id": { "type": "string", "title": "Step Id", "description": "The unique identifier for this workflow step" }, "job_id": { "type": "string", "title": "Job Id", "description": "The job id this step belongs to" }, "step_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Step Type", "description": "The type of step (e.g., 'prompt')" }, "status": { "type": "string", "title": "Status", "description": "The status of the step (e.g., 'complete')" }, "output_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Type", "description": "The type of output produced by this step" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp" }, "start_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time", "description": "Start time in milliseconds" }, "end_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time", "description": "End time in milliseconds" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration", "description": "Duration in milliseconds" }, "output_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Data", "description": "The output data produced by this step" }, "payload": { "type": "object", "title": "Payload", "description": "The configuration payload for this step" } }, "type": "object", "required": [ "step_id", "job_id", "status", "created_at", "updated_at", "payload" ], "title": "WorkflowStepRunResponse" }, "type": "array", "title": "Step Outputs" } }, "type": "object", "required": [ "job_id", "app_id", "entity_id", "user_id", "created_at", "updated_at", "number_of_steps", "status", "user_inputs", "app_data", "step_outputs" ], "title": "JobStatusResponse" }, "PresignedUrlResponse": { "properties": { "url": { "type": "string", "title": "Url", "description": "Pre-signed URL for accessing the file" }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Expiration time in seconds" } }, "type": "object", "required": [ "url", "expires_in" ], "title": "PresignedUrlResponse" }, "AgentsResponse": { "properties": { "id": { "type": "string", "title": "ID", "description": "The unique identifier for this agent (UUID)" }, "name": { "type": "string", "title": "Name", "description": "The name of the agent" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "A description of what the agent does", "default": null }, "instructions": { "type": "string", "title": "Instructions", "description": "The system instructions configured for this agent" }, "tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tools", "description": "The tools available to this agent", "default": null }, "sources": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Sources", "description": "The knowledge sources available to this agent", "default": null } }, "type": "object", "required": [ "id", "name", "instructions" ], "title": "AgentsResponse" }, "AgentsListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AgentsResponse" }, "type": "array", "title": "Data", "description": "The list of available agents" } }, "type": "object", "required": [ "data" ], "title": "AgentsListResponse" }, "OpenAIError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "A human-readable error message." }, "type": { "type": "string", "description": "The error type (e.g. `invalid_request_error`, `authentication_error`, `rate_limit_error`, `server_error`)." }, "param": { "type": "string", "nullable": true, "description": "The parameter that caused the error, if applicable." }, "code": { "type": "string", "nullable": true, "description": "A machine-readable error code." } }, "required": [ "message", "type" ] } }, "required": [ "error" ] }, "Invoice": { "type": "object", "title": "Invoice", "properties": { "id": { "type": "string", "title": "Id", "description": "Stripe invoice ID. Pass this to the PDF endpoint." }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number", "description": "Human-readable invoice number, e.g. 'HSLNEQJJ-0006'" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "The invoice's Stripe status. Never draft. In practice open, paid, uncollectible or void, but this API filters on draft specifically rather than allowlisting the rest, so accept an unfamiliar non-draft status rather than rejecting it." }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "When the invoice was issued (UTC). This is what start/end filter on." }, "period_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Period Start", "description": "Start of the billing period the invoice covers (UTC)" }, "period_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Period End", "description": "End of the billing period the invoice covers (UTC)" }, "currency": { "type": "string", "title": "Currency", "description": "Three-letter ISO currency code, e.g. 'usd'" }, "total_cents": { "type": "integer", "title": "Total Cents", "description": "Invoice total in the smallest currency unit. 103500 is $1,035.00." }, "amount_due_cents": { "type": "integer", "title": "Amount Due Cents", "description": "Amount still owed, in the smallest currency unit" }, "amount_paid_cents": { "type": "integer", "title": "Amount Paid Cents", "description": "Amount already paid, in the smallest currency unit" }, "hosted_invoice_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hosted Invoice Url", "description": "Stripe-hosted invoice page. Null on the rare finalized invoice Stripe has not yet published a page for." }, "invoice_pdf": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invoice Pdf", "description": "Direct link to the invoice PDF. The signed token embeds when it was issued, so this is not a stable identifier; GET /v1/payments/invoices/{invoice_id}/pdf returns a freshly-issued link to the same PDF." } }, "required": [ "id", "created", "currency", "total_cents", "amount_due_cents", "amount_paid_cents" ] }, "InvoiceListResponse": { "type": "object", "title": "InvoiceListResponse", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" }, "title": "Invoices" }, "has_more": { "type": "boolean", "title": "Has More", "description": "True when Stripe has more invoices beyond this page. Drafts are removed after the page is fetched, so the next page can hold fewer invoices than `limit`, or none." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque pagination token. Pass it back verbatim as `starting_after`; it may name an invoice absent from `invoices` (including a draft that 404s if fetched by id). Null when `has_more` is false." } }, "required": [ "invoices", "has_more" ] }, "InvoicePdfResponse": { "type": "object", "title": "InvoicePdfResponse", "properties": { "id": { "type": "string", "title": "Id" }, "invoice_pdf": { "type": "string", "title": "Invoice Pdf", "description": "Direct link to the invoice PDF" }, "hosted_invoice_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hosted Invoice Url", "description": "Stripe-hosted invoice page for the same invoice" } }, "required": [ "id", "invoice_pdf" ] }, "InvoiceTenantBreakdownRow": { "type": "object", "title": "InvoiceTenantBreakdownRow", "properties": { "tenant_entity_id": { "type": "string", "title": "Tenant Entity Id" }, "tenant_name": { "type": "string", "title": "Tenant Name" }, "line_count": { "type": "integer", "title": "Line Count", "description": "How many invoice lines rolled up into this tenant" }, "amount_cents": { "type": "integer", "title": "Amount Cents", "description": "Amount attributed to this tenant, in the smallest currency unit" } }, "required": [ "tenant_entity_id", "tenant_name", "line_count", "amount_cents" ] }, "InvoiceLineDetail": { "type": "object", "title": "InvoiceLineDetail", "description": "One line of the invoice, and why it did or did not reach a tenant. Present on every breakdown response, so an invoice that splits cleanly and one that attributes to nobody are read the same way.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Stripe's description for the line, as it appears on the PDF" }, "amount_cents": { "type": "integer", "title": "Amount Cents", "description": "This line's amount in the smallest currency unit. Negative for credits and discounts applied as their own line." }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Quantity", "description": "Units billed on this line, e.g. seats" }, "period_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Period Start", "description": "Start of the period this line covers (UTC)" }, "period_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Period End", "description": "End of the period this line covers (UTC)" }, "tenant_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Entity Id", "description": "The tenant this line was attributed to, or null when it landed in unallocated_cents. Exactly one of this and unallocated_reason is ever set." }, "unallocated_reason": { "anyOf": [ { "type": "string", "enum": [ "no_subscription_item", "unmapped_subscription_item" ] }, { "type": "null" } ], "title": "Unallocated Reason", "description": "Why this line is not attributed to a tenant. `no_subscription_item` — not tied to a subscription item; one-off charges, credits and inline tax genuinely have no tenant, but metered usage and overage lines also land here and often name a tenant in their description. `unmapped_subscription_item` — tied to one, but no license on your account holds that item. Null when attributed, so exactly one of this and tenant_entity_id is ever set." } }, "required": [ "amount_cents" ] }, "InvoiceTenantBreakdownResponse": { "type": "object", "title": "InvoiceTenantBreakdownResponse", "properties": { "invoice_id": { "type": "string", "title": "Invoice Id" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "The invoice's Stripe status. A void or uncollectible invoice splits across tenants exactly like a live one, but the underlying bill is not owed and must not be re-issued." }, "currency": { "type": "string", "title": "Currency" }, "total_cents": { "type": "integer", "title": "Total Cents", "description": "Invoice total in the smallest currency unit (cents for USD). Stripe does not reduce this when a credit note is issued against a finalized invoice." }, "unallocated_cents": { "type": "integer", "title": "Unallocated Cents", "description": "Total minus everything attributable to a tenant: one-off charges, lines with no matching tenant, and invoice-level discounts, credits and tax. Can be negative when a credit exceeds the unattributed lines." }, "tenants": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceTenantBreakdownRow" }, "title": "Tenants", "description": "Highest amount first. Empty when no line maps to a tenant." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineDetail" }, "title": "Lines", "description": "Every line on the invoice, in Stripe's order, whether or not it reached a tenant. Capped — check `lines_truncated` before reconciling line by line." }, "lines_truncated": { "type": "boolean", "title": "Lines Truncated", "description": "True when the invoice carried more lines than this response returns. The tenant amounts and unallocated_cents are computed from every line either way and remain exact; only `lines` is shortened." } }, "required": [ "invoice_id", "currency", "total_cents", "unallocated_cents", "tenants", "lines", "lines_truncated" ] }, "CourseDetailResponse": { "properties": { "tenant": { "$ref": "#/components/schemas/TenantContext" }, "course": { "$ref": "#/components/schemas/CourseSummaryRow" }, "learners": { "items": { "$ref": "#/components/schemas/LearningPairDetail" }, "type": "array", "title": "Learners" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "status_counts": { "$ref": "#/components/schemas/LearningStatusCounts" } }, "type": "object", "required": [ "tenant", "course", "learners", "status_counts" ], "title": "CourseDetailResponse" }, "CourseListResponse": { "properties": { "courses": { "items": { "$ref": "#/components/schemas/CourseSummaryRow" }, "type": "array", "title": "Courses" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "courses" ], "title": "CourseListResponse" }, "CourseSummaryRow": { "properties": { "course_id": { "type": "string", "format": "uuid", "title": "Course Id" }, "course_slug": { "type": "string", "title": "Course Slug" }, "course_title": { "type": "string", "title": "Course Title" }, "enrollment_coverage": { "$ref": "#/components/schemas/CoverageMetric", "description": "Coverage across the currently applicable learner population." }, "completion_coverage": { "$ref": "#/components/schemas/CoverageMetric", "description": "Completion across currently applicable stable course identities; completion on an earlier course version remains complete." } }, "type": "object", "required": [ "course_id", "course_slug", "course_title", "enrollment_coverage", "completion_coverage" ], "title": "CourseSummaryRow" }, "CoverageMetric": { "properties": { "numerator": { "type": "integer", "title": "Numerator" }, "denominator": { "type": "integer", "title": "Denominator" }, "percentage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Percentage" }, "gap": { "type": "integer", "title": "Gap", "description": "Denominator minus numerator." } }, "type": "object", "required": [ "numerator", "denominator", "percentage", "gap" ], "title": "CoverageMetric", "description": "A named coverage fraction; percentage is absent when denominator is zero." }, "ExportCapabilityResponse": { "properties": { "can_export": { "type": "boolean", "title": "Can Export" } }, "type": "object", "required": [ "can_export" ], "title": "ExportCapabilityResponse" }, "ExportReportRequest": { "properties": { "report_type": { "type": "string", "enum": [ "portfolio_summary", "learner_summary", "course_summary", "activity_detail" ], "title": "Report Type" }, "tenant_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Tenant Id" } }, "additionalProperties": false, "type": "object", "required": [ "report_type" ], "title": "ExportReportRequest" }, "ExportReportResponse": { "properties": { "filename": { "type": "string", "title": "Filename" }, "csv": { "type": "string", "title": "Csv" }, "row_count": { "type": "integer", "title": "Row Count" } }, "type": "object", "required": [ "filename", "csv", "row_count" ], "title": "ExportReportResponse" }, "LearnerDetailResponse": { "properties": { "tenant": { "$ref": "#/components/schemas/TenantContext" }, "learner": { "$ref": "#/components/schemas/LearnerSummaryRow" }, "courses": { "items": { "$ref": "#/components/schemas/LearningPairDetail" }, "type": "array", "title": "Courses" } }, "type": "object", "required": [ "tenant", "learner", "courses" ], "title": "LearnerDetailResponse" }, "LearnerListResponse": { "properties": { "learners": { "items": { "$ref": "#/components/schemas/LearnerSummaryRow" }, "type": "array", "title": "Learners" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "learners" ], "title": "LearnerListResponse" }, "LearnerSummaryRow": { "properties": { "learner_id": { "type": "string", "format": "uuid", "title": "Learner Id" }, "learner_external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Learner External Id" }, "learner_name": { "type": "string", "title": "Learner Name" }, "learner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Learner Email" }, "applicable_courses": { "type": "integer", "title": "Applicable Courses", "description": "Current published courses applicable to this learner." }, "courses_enrolled": { "type": "integer", "title": "Courses Enrolled", "description": "Applicable courses with an active or completed enrollment." }, "courses_completed": { "type": "integer", "title": "Courses Completed", "description": "Applicable stable course identities completed by this learner." }, "last_learning_activity_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Learning Activity At" } }, "type": "object", "required": [ "learner_id", "learner_name", "applicable_courses", "courses_enrolled", "courses_completed" ], "title": "LearnerSummaryRow" }, "LearningPairDetail": { "properties": { "tenant_id": { "type": "string", "format": "uuid", "title": "Tenant Id" }, "tenant_name": { "type": "string", "title": "Tenant Name" }, "academy_enabled": { "type": "boolean", "title": "Academy Enabled" }, "can_manage_enrollments": { "type": "boolean", "title": "Can Manage Enrollments" }, "learner_id": { "type": "string", "format": "uuid", "title": "Learner Id" }, "learner_external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Learner External Id" }, "learner_name": { "type": "string", "title": "Learner Name" }, "learner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Learner Email" }, "course_id": { "type": "string", "format": "uuid", "title": "Course Id" }, "course_slug": { "type": "string", "title": "Course Slug" }, "course_title": { "type": "string", "title": "Course Title" }, "is_eligible_pair": { "type": "boolean", "title": "Is Eligible Pair" }, "is_current_course": { "type": "boolean", "title": "Is Current Course" }, "enrollment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Enrollment Id" }, "status": { "type": "string", "enum": [ "not_enrolled", "not_started", "in_progress", "completed", "access_revoked", "retired" ], "title": "Status" }, "progress_pct": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Progress Pct" }, "enrolled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Enrolled At" }, "last_activity_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Activity At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" }, "access_revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Access Revoked At" } }, "type": "object", "required": [ "tenant_id", "tenant_name", "academy_enabled", "can_manage_enrollments", "learner_id", "learner_name", "course_id", "course_slug", "course_title", "is_eligible_pair", "is_current_course", "status", "progress_pct" ], "title": "LearningPairDetail" }, "LearningStatusCounts": { "properties": { "not_enrolled": { "type": "integer", "title": "Not Enrolled" }, "not_started": { "type": "integer", "title": "Not Started" }, "in_progress": { "type": "integer", "title": "In Progress" }, "completed": { "type": "integer", "title": "Completed" }, "access_revoked": { "type": "integer", "title": "Access Revoked" }, "retired": { "type": "integer", "title": "Retired" } }, "type": "object", "required": [ "not_enrolled", "not_started", "in_progress", "completed", "access_revoked", "retired" ], "title": "LearningStatusCounts", "description": "All reportable current and historical learner-course records." }, "LearningSummary": { "properties": { "learner_reach": { "$ref": "#/components/schemas/CoverageMetric" }, "enrollment_coverage": { "$ref": "#/components/schemas/CoverageMetric" }, "completion_coverage": { "$ref": "#/components/schemas/CoverageMetric" } }, "type": "object", "required": [ "learner_reach", "enrollment_coverage", "completion_coverage" ], "title": "LearningSummary" }, "PortfolioResponse": { "properties": { "scope": { "type": "string", "const": "msp", "title": "Scope" }, "tenants": { "items": { "$ref": "#/components/schemas/PortfolioTenantRow" }, "type": "array", "title": "Tenants" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "scope", "tenants" ], "title": "PortfolioResponse" }, "PortfolioSummaryResponse": { "properties": { "scope": { "type": "string", "const": "msp", "title": "Scope" }, "metrics": { "$ref": "#/components/schemas/LearningSummary" } }, "type": "object", "required": [ "scope", "metrics" ], "title": "PortfolioSummaryResponse" }, "PortfolioTenantRow": { "properties": { "tenant_id": { "type": "string", "format": "uuid", "title": "Tenant Id" }, "tenant_name": { "type": "string", "title": "Tenant Name" }, "academy_enabled": { "type": "boolean", "title": "Academy Enabled" }, "can_manage_enrollments": { "type": "boolean", "title": "Can Manage Enrollments" }, "metrics": { "$ref": "#/components/schemas/LearningSummary" }, "tenant_external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant External Id" } }, "type": "object", "required": [ "tenant_id", "tenant_name", "academy_enabled", "can_manage_enrollments", "metrics" ], "title": "PortfolioTenantRow" }, "TenantContext": { "properties": { "tenant_id": { "type": "string", "format": "uuid", "title": "Tenant Id" }, "tenant_name": { "type": "string", "title": "Tenant Name" }, "academy_enabled": { "type": "boolean", "title": "Academy Enabled" }, "can_manage_enrollments": { "type": "boolean", "title": "Can Manage Enrollments" } }, "type": "object", "required": [ "tenant_id", "tenant_name", "academy_enabled", "can_manage_enrollments" ], "title": "TenantContext" }, "TenantLearningSummary": { "properties": { "tenant_id": { "type": "string", "format": "uuid", "title": "Tenant Id" }, "tenant_name": { "type": "string", "title": "Tenant Name" }, "academy_enabled": { "type": "boolean", "title": "Academy Enabled" }, "can_manage_enrollments": { "type": "boolean", "title": "Can Manage Enrollments" }, "metrics": { "$ref": "#/components/schemas/LearningSummary" } }, "type": "object", "required": [ "tenant_id", "tenant_name", "academy_enabled", "can_manage_enrollments", "metrics" ], "title": "TenantLearningSummary" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key passed as a Bearer token. Accepted only on compatibility endpoints; in this OpenAPI reference that is POST /openai/responses. All other operations require the X-API-Key header." } } }, "x-ext-urls": {} }