Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200

  OpenAI-compatible model list. Gateway entries can be used as the model value in chat completions.

  {
      "object": "list",
      "data": [
          {
              "id": "0198683a-2b6d-7066-9598-6ea119c219f2",
              "object": "model",
              "created": 1,
              "owned_by": "example_account"
          },
          {
              "id": "b2c4f1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
              "object": "model",
              "created": 1,
              "owned_by": "example_account"
          }
      ]
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

• Sse-Stream-Options

  Optional. Use no-ping to disable periodic keep-alive events on streaming responses.

Request examples:

• OpenAI-compatible chat completion payload. Use model for an integrated model name, gateway id or gateway slug; messages or prompt for input; stream for SSE output; metadata for string key/value request metadata stored with the conversation; idempotency_key to reuse the stored conversation token; and tools, builtin_tools or response_format when tool calling or structured output is required.

  {
      "model": "0198683a-2b6d-7066-9598-6ea119c219f2",
      "messages": [
          {
              "role": "user",
              "content": "Qual a capital da França?"
          }
      ],
      "stream": false,
      "idempotency_key": "order-123-summary",
      "metadata": {
          "foo": "bar"
      }
  }        

Responses:

• 200

  OpenAI-compatible chat completion response. Non-streaming responses include usage and AIVAX generation_context metadata.

  {
      "id": "0198d24c-c9ce-70fe-9cf3-00644ef5f2e2",
      "object": "chat.completion",
      "created": 1755874904,
      "model": "@openai/gpt-5-mini",
      "choices": [
          {
              "index": 0,
              "message": {
                  "role": "assistant",
                  "content": "A capital da França é Paris.",
                  "refusal": null,
                  "annotations": [],
                  "tool_calls": []
              },
              "logprobs": null,
              "finish_reason": "stop"
          }
      ],
      "usage": {
          "prompt_tokens": 84,
          "completion_tokens": 16,
          "total_tokens": 1892,
          "prompt_tokens_details": {
              "cached_tokens": 1792
          }
      },
      "service_tier": "default",
      "generation_context": {
          "generated_usage": [
              {
                  "sku": "inference.resolving.routing_complexity.in",
                  "amount": 0.0000207,
                  "unit_price": 7.5e-8,
                  "quantity": 276,
                  "description": "Inference for model routing"
              },
              {
                  "sku": "inference.resolving.routing_complexity.out",
                  "amount": 3e-7,
                  "unit_price": 3e-7,
                  "quantity": 1,
                  "description": "Inference for model routing"
              },
              {
                  "sku": "inference.chat_completions.in",
                  "amount": 0.000021,
                  "unit_price": 2.5e-7,
                  "quantity": 84,
                  "description": "Inference for AI model '@openai/gpt-5-mini'"
              },
              {
                  "sku": "inference.chat_completions.out",
                  "amount": 0.000032,
                  "unit_price": 0.000002,
                  "quantity": 16,
                  "description": "Inference for AI model '@openai/gpt-5-mini'"
              },
              {
                  "sku": "inference.chat_completions.in.cached",
                  "amount": 0.0000448,
                  "unit_price": 2.5e-8,
                  "quantity": 1792,
                  "description": "Inference for AI model '@openai/gpt-5-mini'"
              }
          ],
          "runned_functions": []
      }
  }            

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• web-chat-iduuid

  Identifier of the web chat client.

Query parameters:

• external-user-idstring

  Optional external user id used to restrict schedules and recurring tasks.

Responses:

• 200

  Schedules, recurring tasks and inactive-user candidates for the web chat client.

  {
      "webChat": { "id": "...", "name": "My Web Chat" },
      "inactiveUsers": [
          {
              "externalUserId": "user-456",
              "lastScheduledMessageAt": "2026-03-20T15:00:00Z",
              "lastUserMessageAt": "2026-03-18T09:30:00Z"
          }
      ],
      "schedules": [
          {
              "id": "...",
              "externalUserId": "user-123",
              "target": "Telegram",
              "targetIdentifier": "+5511999999999",
              "scheduledTime": "2026-03-21T15:00:00Z",
              "activatedAt": null,
              "createdAt": "2026-03-20T10:00:00Z"
          }
      ],
      "recurringTasks": [
          {
              "id": "...",
              "externalUserId": "user-123",
              "target": "WhatsApp_ZApi",
              "targetIdentifier": "+5511988888888",
              "cronExpression": "0 9 * * 1",
              "nextActivation": "2026-03-23T09:00:00Z",
              "lastActivation": null,
              "executionCount": 0,
              "createdAt": "2026-03-20T10:00:00Z"
          }
      ]
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• web-chat-iduuid

  Identifier of the web chat client.

• iduuid

  Identifier of the one-time schedule.

Responses:

• 200

  One-time schedule details.

  {
      "id": "...",
      "externalUserId": "user-123",
      "target": "Telegram",
      "targetIdentifier": "+5511999999999",
      "scheduledTime": "2026-03-21T15:00:00Z",
      "reason": "Follow-up reminder",
      "context": "{ \"orderId\": 42 }",
      "createdAt": "2026-03-20T10:00:00Z",
      "activatedAt": null,
      "activatedSessionId": null,
      "activationResult": null
  }

• 404

  Schedule not found.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• web-chat-iduuid

  Identifier of the web chat client.

• iduuid

  Identifier of the schedule to delete.

Responses:

• 200

  The schedule was deleted.

• 404

  Schedule not found.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• web-chat-iduuid

  Identifier of the web chat client.

• iduuid

  Identifier of the recurring task.

Responses:

• 200

  Recurring task details.

  {
      "id": "...",
      "externalUserId": "user-123",
      "target": "WhatsApp_ZApi",
      "targetIdentifier": "+5511988888888",
      "jobDescription": "Weekly check-in message",
      "cronExpression": "0 9 * * 1",
      "lastActivation": null,
      "nextActivation": "2026-03-23T09:00:00Z",
      "maxExecutions": 10,
      "executionCount": 2,
      "createdAt": "2026-03-20T10:00:00Z"
  }

• 404

  Recurring task not found.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• web-chat-iduuid

  Identifier of the web chat client.

• iduuid

  Identifier of the recurring task to delete.

Responses:

• 200

  The recurring task was deleted.

• 404

  Recurring task not found.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200
  ExampleSchema

  [
      {
          // The unique identifier of the web chat client.
          "id": "uuid",
  
          // The name of the web chat client.
          "name": string,
  
          // Nullable. The primary color associated with the client.
          "color": string?,
  
          // The number of active sessions.
          "activeSessions": number,
  
          // Nullable. Information about the associated AI Gateway.
          "associatedGateway": {
              // The unique identifier of the gateway.
              "id": "uuid",
  
              // The name of the gateway.
              "name": string,
  
              // The model name used by the gateway.
              "modelName": string
          }?
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "The unique identifier of the web chat client."
              },
              "name": {
                  "type": "string",
                  "description": "The name of the web chat client."
              },
              "color": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "The primary color associated with the client."
              },
              "activeSessions": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "The number of active sessions."
              },
              "associatedGateway": {
                  "properties": {
                      "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The unique identifier of the gateway."
                      },
                      "name": {
                          "type": "string",
                          "description": "The name of the gateway."
                      },
                      "modelName": {
                          "type": "string",
                          "description": "The model name used by the gateway."
                      }
                  },
                  "description": "Information about the associated AI Gateway.",
                  "type": [
                      "object",
                      "null"
                  ]
              }
          },
          "description": "Represents a summary item for a web chat client in a listing."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Web chat client creation payload.

  ExampleSchema

  {
      // Display name of the web chat client.
      "name": string,
  
      // Nullable. AI Gateway used to answer messages sent through this client.
      "aiGatewayId": "uuid"?,
  
      // Message and context limits enforced for sessions created by this client.
      "limitingParameters": {
          // Maximum number of messages a session can send per hour.
          "messagesPerHour": number,
  
          // Maximum number of session messages kept in conversation context.
          "maxMessages": number
      },
  
      // User interface, behavior and input-mode configuration for this client.
      "clientParameters": {
          // Nullable. Language code used by the web chat UI.
          "languageCode": string?,
  
          // Suggested prompt buttons displayed before or during a chat session.
          "suggestionButtons": [
              {
                  // Required. Text displayed on the suggestion button.
                  "label": string,
  
                  // Required. Message submitted when the suggestion button is clicked.
                  "prompt": string
              },
              ...
          ],
  
          // Nullable. Custom JavaScript injected into the hosted web chat page.
          "customScripts": string?,
  
          // Nullable. Custom CSS injected into the hosted web chat page.
          "customStyles": string?,
  
          // File and media input types accepted by the chat UI.
          "inputModes": [
              "Image",
              ...
          ],
  
          // Required. Primary CSS color used by the hosted chat UI.
          "primaryColor": string,
  
          // Required. Browser page title for the hosted chat UI.
          "pageTitle": string,
  
          // Nullable. Main greeting text shown before the user sends a message.
          "helloLabel": string?,
  
          // Nullable. Secondary greeting text shown below the main greeting.
          "helloSubLabel": string?,
  
          // Nullable. Placeholder text shown in the message input.
          "textAreaPlaceholder": string?,
  
          // Nullable. Logo image URL shown in the hosted chat UI.
          "logoImageUrl": string?,
  
          // Enables diagnostic information in the browser console for this client.
          "debug": boolean,
  
          // Shows tool-call activity in the hosted chat UI when tool information is available.
          "showToolCalls": boolean,
  
          // HTTP origins allowed to embed this chat client in an iframe.
          "allowedFrameOrigins": [
              string,
              ...
          ],
  
          // Text-to-speech provider used for audio replies.
          "audioSynthesisSource": "None",
  
          // Nullable. Provider-specific voice name used for text-to-speech.
          "audioSynthesisVoice": string?,
  
          // Nullable. Provider-specific instruction used when synthesizing audio replies.
          "audioSynthesisInstruction": string?,
  
          // Summarizes long assistant replies before sending them to text-to-speech.
          "summarizeTextBeforeAudioSynthesis": boolean,
  
          // Allows unsupported file formats to be uploaded and handled as generic files.
          "uploadUnsupportedFiles": boolean,
  
          // Allows the assistant to schedule follow-up messages through supported integrations.
          "allowScheduledContinuations": boolean,
  
          // Splits generated scheduled-continuation replies into multiple message chunks.
          "splitAnswerIntoMessageChunks": boolean,
  
          // Time window during which pending scheduled continuations are ignored after the user sends a new message.
          "maxScheduledIgnoredZone": any,
  
          // Delay used to group rapid incoming integration messages before processing.
          "messageDebounceInterval": any
      }
  }

  {
      "type": "object",
      "properties": {
          "name": {
              "type": "string",
              "description": "Display name of the web chat client."
          },
          "aiGatewayId": {
              "format": "uuid",
              "description": "AI Gateway used to answer messages sent through this client.",
              "type": [
                  "string",
                  "null"
              ]
          },
          "limitingParameters": {
              "type": "object",
              "properties": {
                  "messagesPerHour": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Maximum number of messages a session can send per hour."
                  },
                  "maxMessages": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Maximum number of session messages kept in conversation context."
                  }
              },
              "description": "Message and context limits enforced for sessions created by this client."
          },
          "clientParameters": {
              "type": "object",
              "properties": {
                  "languageCode": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Language code used by the web chat UI."
                  },
                  "suggestionButtons": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "label": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "Text displayed on the suggestion button."
                              },
                              "prompt": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "Message submitted when the suggestion button is clicked."
                              }
                          },
                          "required": [
                              "label",
                              "prompt"
                          ],
                          "description": "Represents a quick-reply button displayed in the web-chat interface."
                      },
                      "description": "Suggested prompt buttons displayed before or during a chat session."
                  },
                  "customScripts": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Custom JavaScript injected into the hosted web chat page."
                  },
                  "customStyles": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Custom CSS injected into the hosted web chat page."
                  },
                  "inputModes": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "enum": [
                              "Image",
                              "Document",
                              "Audio"
                          ]
                      },
                      "description": "File and media input types accepted by the chat UI."
                  },
                  "primaryColor": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Primary CSS color used by the hosted chat UI."
                  },
                  "pageTitle": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Browser page title for the hosted chat UI."
                  },
                  "helloLabel": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Main greeting text shown before the user sends a message."
                  },
                  "helloSubLabel": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Secondary greeting text shown below the main greeting."
                  },
                  "textAreaPlaceholder": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Placeholder text shown in the message input."
                  },
                  "logoImageUrl": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Logo image URL shown in the hosted chat UI."
                  },
                  "debug": {
                      "type": "boolean",
                      "description": "Enables diagnostic information in the browser console for this client."
                  },
                  "showToolCalls": {
                      "type": "boolean",
                      "description": "Shows tool-call activity in the hosted chat UI when tool information is available."
                  },
                  "allowedFrameOrigins": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      },
                      "description": "HTTP origins allowed to embed this chat client in an iframe."
                  },
                  "audioSynthesisSource": {
                      "type": "string",
                      "enum": [
                          "None",
                          "Gpt4oTts",
                          "ElevenMultilingualV2",
                          "ElevenV3",
                          "GrokVoice"
                      ],
                      "description": "Text-to-speech provider used for audio replies."
                  },
                  "audioSynthesisVoice": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific voice name used for text-to-speech."
                  },
                  "audioSynthesisInstruction": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific instruction used when synthesizing audio replies."
                  },
                  "summarizeTextBeforeAudioSynthesis": {
                      "type": "boolean",
                      "description": "Summarizes long assistant replies before sending them to text-to-speech."
                  },
                  "uploadUnsupportedFiles": {
                      "type": "boolean",
                      "description": "Allows unsupported file formats to be uploaded and handled as generic files."
                  },
                  "allowScheduledContinuations": {
                      "type": "boolean",
                      "description": "Allows the assistant to schedule follow-up messages through supported integrations."
                  },
                  "splitAnswerIntoMessageChunks": {
                      "type": "boolean",
                      "description": "Splits generated scheduled-continuation replies into multiple message chunks."
                  },
                  "maxScheduledIgnoredZone": {
                      "description": "Time window during which pending scheduled continuations are ignored after the user sends a new message."
                  },
                  "messageDebounceInterval": {
                      "description": "Delay used to group rapid incoming integration messages before processing."
                  }
              },
              "required": [
                  "primaryColor",
                  "pageTitle"
              ],
              "description": "User interface, behavior and input-mode configuration for this client."
          }
      },
      "description": "Payload used to create a browser or messaging-channel chat client linked to an AI Gateway."
  }

Responses:

• 200
  ExampleSchema

  {
      // The unique identifier of the created web chat client.
      "id": "uuid"
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "string",
              "format": "uuid",
              "description": "The unique identifier of the created web chat client."
          }
      },
      "description": "Represents the response after creating a web chat client."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• iduuid

  Identifier of the web chat client to retrieve.

Responses:

• 200
  ExampleSchema

  {
      // The name of the web chat client.
      "name": string,
  
      // Nullable. Information about the associated AI Gateway.
      "aiGateway": {
          // The unique identifier of the gateway.
          "id": "uuid",
  
          // The name of the gateway.
          "name": string
      }?,
  
      // Parameters for rate limiting and usage control.
      "limitingParameters": {
          // Maximum number of messages a session can send per hour.
          "messagesPerHour": number,
  
          // Maximum number of session messages kept in conversation context.
          "maxMessages": number
      },
  
      // Parameters for client configuration.
      "clientParameters": {
          // Nullable. Language code used by the web chat UI.
          "languageCode": string?,
  
          // Suggested prompt buttons displayed before or during a chat session.
          "suggestionButtons": [
              {
                  // Required. Text displayed on the suggestion button.
                  "label": string,
  
                  // Required. Message submitted when the suggestion button is clicked.
                  "prompt": string
              },
              ...
          ],
  
          // Nullable. Custom JavaScript injected into the hosted web chat page.
          "customScripts": string?,
  
          // Nullable. Custom CSS injected into the hosted web chat page.
          "customStyles": string?,
  
          // File and media input types accepted by the chat UI.
          "inputModes": [
              "Image",
              ...
          ],
  
          // Required. Primary CSS color used by the hosted chat UI.
          "primaryColor": string,
  
          // Required. Browser page title for the hosted chat UI.
          "pageTitle": string,
  
          // Nullable. Main greeting text shown before the user sends a message.
          "helloLabel": string?,
  
          // Nullable. Secondary greeting text shown below the main greeting.
          "helloSubLabel": string?,
  
          // Nullable. Placeholder text shown in the message input.
          "textAreaPlaceholder": string?,
  
          // Nullable. Logo image URL shown in the hosted chat UI.
          "logoImageUrl": string?,
  
          // Enables diagnostic information in the browser console for this client.
          "debug": boolean,
  
          // Shows tool-call activity in the hosted chat UI when tool information is available.
          "showToolCalls": boolean,
  
          // HTTP origins allowed to embed this chat client in an iframe.
          "allowedFrameOrigins": [
              string,
              ...
          ],
  
          // Text-to-speech provider used for audio replies.
          "audioSynthesisSource": "None",
  
          // Nullable. Provider-specific voice name used for text-to-speech.
          "audioSynthesisVoice": string?,
  
          // Nullable. Provider-specific instruction used when synthesizing audio replies.
          "audioSynthesisInstruction": string?,
  
          // Summarizes long assistant replies before sending them to text-to-speech.
          "summarizeTextBeforeAudioSynthesis": boolean,
  
          // Allows unsupported file formats to be uploaded and handled as generic files.
          "uploadUnsupportedFiles": boolean,
  
          // Allows the assistant to schedule follow-up messages through supported integrations.
          "allowScheduledContinuations": boolean,
  
          // Splits generated scheduled-continuation replies into multiple message chunks.
          "splitAnswerIntoMessageChunks": boolean,
  
          // Time window during which pending scheduled continuations are ignored after the user sends a new message.
          "maxScheduledIgnoredZone": any,
  
          // Delay used to group rapid incoming integration messages before processing.
          "messageDebounceInterval": any
      },
  
      // Integration details.
      "integrations": {
          // Nullable. Parameters for Z-API integration.
          "zapiIntegration": {
              // Required. Z-API instance identifier.
              "instanceId": string,
  
              // Required. Z-API instance token.
              "instanceToken": string,
  
              // Nullable. Optional Z-API client token, when required by the configured instance.
              "clientToken": string?,
  
              // Integration session lifetime before a new chat session must be created.
              "sessionDuration": any
          }?,
  
          // Nullable. Parameters for Telegram integration.
          "telegramIntegration": {
              // Required. Telegram bot token used to receive and send messages.
              "botToken": string,
  
              // Integration session lifetime before a new chat session must be created.
              "sessionDuration": any
          }?,
  
          // Nullable. Parameters for Evolution integration.
          "evolutionIntegration": {
              // Required. Base endpoint URL of the Evolution API instance.
              "endpointUrl": string,
  
              // Required. Evolution API instance name used for this integration.
              "instanceName": string,
  
              // Required. API key used to authenticate Evolution API requests.
              "apiKey": string,
  
              // Integration session lifetime before a new chat session must be created.
              "sessionDuration": any
          }?,
  
          // Nullable. Parameters for Kapso WhatsApp integration.
          "kapsoIntegration": {
              // Required. Kapso project API key used for WhatsApp API requests.
              "apiKey": string,
  
              // Required. WhatsApp Business Phone Number ID registered in Kapso.
              "phoneNumberId": string,
  
              // Nullable. Secret key used to verify Kapso webhook signatures.
              "webhookSecretKey": string?,
  
              // Nullable. WhatsApp template name used for scheduled continuation messages. When set, scheduled messages are sent as a template with the text in the {{text}} parameter.
              "continuedMessagesTemplateId": string?,
  
              // Integration session lifetime before a new chat session must be created.
              "sessionDuration": any
          }?
      }
  }

  {
      "type": "object",
      "properties": {
          "name": {
              "type": "string",
              "description": "The name of the web chat client."
          },
          "aiGateway": {
              "properties": {
                  "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The unique identifier of the gateway."
                  },
                  "name": {
                      "type": "string",
                      "description": "The name of the gateway."
                  }
              },
              "description": "Information about the associated AI Gateway.",
              "type": [
                  "object",
                  "null"
              ]
          },
          "limitingParameters": {
              "type": "object",
              "properties": {
                  "messagesPerHour": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Maximum number of messages a session can send per hour."
                  },
                  "maxMessages": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Maximum number of session messages kept in conversation context."
                  }
              },
              "description": "Parameters for rate limiting and usage control."
          },
          "clientParameters": {
              "type": "object",
              "properties": {
                  "languageCode": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Language code used by the web chat UI."
                  },
                  "suggestionButtons": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "label": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "Text displayed on the suggestion button."
                              },
                              "prompt": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "Message submitted when the suggestion button is clicked."
                              }
                          },
                          "required": [
                              "label",
                              "prompt"
                          ],
                          "description": "Represents a quick-reply button displayed in the web-chat interface."
                      },
                      "description": "Suggested prompt buttons displayed before or during a chat session."
                  },
                  "customScripts": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Custom JavaScript injected into the hosted web chat page."
                  },
                  "customStyles": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Custom CSS injected into the hosted web chat page."
                  },
                  "inputModes": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "enum": [
                              "Image",
                              "Document",
                              "Audio"
                          ]
                      },
                      "description": "File and media input types accepted by the chat UI."
                  },
                  "primaryColor": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Primary CSS color used by the hosted chat UI."
                  },
                  "pageTitle": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Browser page title for the hosted chat UI."
                  },
                  "helloLabel": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Main greeting text shown before the user sends a message."
                  },
                  "helloSubLabel": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Secondary greeting text shown below the main greeting."
                  },
                  "textAreaPlaceholder": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Placeholder text shown in the message input."
                  },
                  "logoImageUrl": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Logo image URL shown in the hosted chat UI."
                  },
                  "debug": {
                      "type": "boolean",
                      "description": "Enables diagnostic information in the browser console for this client."
                  },
                  "showToolCalls": {
                      "type": "boolean",
                      "description": "Shows tool-call activity in the hosted chat UI when tool information is available."
                  },
                  "allowedFrameOrigins": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      },
                      "description": "HTTP origins allowed to embed this chat client in an iframe."
                  },
                  "audioSynthesisSource": {
                      "type": "string",
                      "enum": [
                          "None",
                          "Gpt4oTts",
                          "ElevenMultilingualV2",
                          "ElevenV3",
                          "GrokVoice"
                      ],
                      "description": "Text-to-speech provider used for audio replies."
                  },
                  "audioSynthesisVoice": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific voice name used for text-to-speech."
                  },
                  "audioSynthesisInstruction": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific instruction used when synthesizing audio replies."
                  },
                  "summarizeTextBeforeAudioSynthesis": {
                      "type": "boolean",
                      "description": "Summarizes long assistant replies before sending them to text-to-speech."
                  },
                  "uploadUnsupportedFiles": {
                      "type": "boolean",
                      "description": "Allows unsupported file formats to be uploaded and handled as generic files."
                  },
                  "allowScheduledContinuations": {
                      "type": "boolean",
                      "description": "Allows the assistant to schedule follow-up messages through supported integrations."
                  },
                  "splitAnswerIntoMessageChunks": {
                      "type": "boolean",
                      "description": "Splits generated scheduled-continuation replies into multiple message chunks."
                  },
                  "maxScheduledIgnoredZone": {
                      "description": "Time window during which pending scheduled continuations are ignored after the user sends a new message."
                  },
                  "messageDebounceInterval": {
                      "description": "Delay used to group rapid incoming integration messages before processing."
                  }
              },
              "required": [
                  "primaryColor",
                  "pageTitle"
              ],
              "description": "Parameters for client configuration."
          },
          "integrations": {
              "type": "object",
              "properties": {
                  "zapiIntegration": {
                      "properties": {
                          "instanceId": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Z-API instance identifier."
                          },
                          "instanceToken": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Z-API instance token."
                          },
                          "clientToken": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional Z-API client token, when required by the configured instance."
                          },
                          "sessionDuration": {
                              "description": "Integration session lifetime before a new chat session must be created."
                          }
                      },
                      "required": [
                          "instanceId",
                          "instanceToken"
                      ],
                      "description": "Parameters for Z-API integration.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "telegramIntegration": {
                      "properties": {
                          "botToken": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Telegram bot token used to receive and send messages."
                          },
                          "sessionDuration": {
                              "description": "Integration session lifetime before a new chat session must be created."
                          }
                      },
                      "required": [
                          "botToken"
                      ],
                      "description": "Parameters for Telegram integration.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "evolutionIntegration": {
                      "properties": {
                          "endpointUrl": {
                              "type": "string",
                              "description": "Base endpoint URL of the Evolution API instance."
                          },
                          "instanceName": {
                              "type": "string",
                              "description": "Evolution API instance name used for this integration."
                          },
                          "apiKey": {
                              "type": "string",
                              "description": "API key used to authenticate Evolution API requests."
                          },
                          "sessionDuration": {
                              "description": "Integration session lifetime before a new chat session must be created."
                          }
                      },
                      "required": [
                          "endpointUrl",
                          "instanceName",
                          "apiKey"
                      ],
                      "description": "Parameters for Evolution integration.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "kapsoIntegration": {
                      "properties": {
                          "apiKey": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Kapso project API key used for WhatsApp API requests."
                          },
                          "phoneNumberId": {
                              "type": "string",
                              "minLength": 1,
                              "description": "WhatsApp Business Phone Number ID registered in Kapso."
                          },
                          "webhookSecretKey": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Secret key used to verify Kapso webhook signatures."
                          },
                          "continuedMessagesTemplateId": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "WhatsApp template name used for scheduled continuation messages. When set, scheduled messages are sent as a template with the text in the {{text}} parameter."
                          },
                          "sessionDuration": {
                              "description": "Integration session lifetime before a new chat session must be created."
                          }
                      },
                      "required": [
                          "apiKey",
                          "phoneNumberId"
                      ],
                      "description": "Parameters for Kapso WhatsApp integration.",
                      "type": [
                          "object",
                          "null"
                      ]
                  }
              },
              "description": "Integration details."
          }
      },
      "description": "Represents detailed information about a web chat client."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• iduuid

  Identifier of the web chat client to update.

Request examples:

• Partial web chat client update data. The schema type documents the available fields, but update payloads may send only name, aiGatewayId, limitingParameters and/or clientParameters.

  ExampleSchema

  {
      // Display name of the web chat client.
      "name": string,
  
      // Nullable. AI Gateway used to answer messages sent through this client.
      "aiGatewayId": "uuid"?,
  
      // Message and context limits enforced for sessions created by this client.
      "limitingParameters": {
          // Maximum number of messages a session can send per hour.
          "messagesPerHour": number,
  
          // Maximum number of session messages kept in conversation context.
          "maxMessages": number
      },
  
      // User interface, behavior and input-mode configuration for this client.
      "clientParameters": {
          // Nullable. Language code used by the web chat UI.
          "languageCode": string?,
  
          // Suggested prompt buttons displayed before or during a chat session.
          "suggestionButtons": [
              {
                  // Required. Text displayed on the suggestion button.
                  "label": string,
  
                  // Required. Message submitted when the suggestion button is clicked.
                  "prompt": string
              },
              ...
          ],
  
          // Nullable. Custom JavaScript injected into the hosted web chat page.
          "customScripts": string?,
  
          // Nullable. Custom CSS injected into the hosted web chat page.
          "customStyles": string?,
  
          // File and media input types accepted by the chat UI.
          "inputModes": [
              "Image",
              ...
          ],
  
          // Required. Primary CSS color used by the hosted chat UI.
          "primaryColor": string,
  
          // Required. Browser page title for the hosted chat UI.
          "pageTitle": string,
  
          // Nullable. Main greeting text shown before the user sends a message.
          "helloLabel": string?,
  
          // Nullable. Secondary greeting text shown below the main greeting.
          "helloSubLabel": string?,
  
          // Nullable. Placeholder text shown in the message input.
          "textAreaPlaceholder": string?,
  
          // Nullable. Logo image URL shown in the hosted chat UI.
          "logoImageUrl": string?,
  
          // Enables diagnostic information in the browser console for this client.
          "debug": boolean,
  
          // Shows tool-call activity in the hosted chat UI when tool information is available.
          "showToolCalls": boolean,
  
          // HTTP origins allowed to embed this chat client in an iframe.
          "allowedFrameOrigins": [
              string,
              ...
          ],
  
          // Text-to-speech provider used for audio replies.
          "audioSynthesisSource": "None",
  
          // Nullable. Provider-specific voice name used for text-to-speech.
          "audioSynthesisVoice": string?,
  
          // Nullable. Provider-specific instruction used when synthesizing audio replies.
          "audioSynthesisInstruction": string?,
  
          // Summarizes long assistant replies before sending them to text-to-speech.
          "summarizeTextBeforeAudioSynthesis": boolean,
  
          // Allows unsupported file formats to be uploaded and handled as generic files.
          "uploadUnsupportedFiles": boolean,
  
          // Allows the assistant to schedule follow-up messages through supported integrations.
          "allowScheduledContinuations": boolean,
  
          // Splits generated scheduled-continuation replies into multiple message chunks.
          "splitAnswerIntoMessageChunks": boolean,
  
          // Time window during which pending scheduled continuations are ignored after the user sends a new message.
          "maxScheduledIgnoredZone": any,
  
          // Delay used to group rapid incoming integration messages before processing.
          "messageDebounceInterval": any
      }
  }

  {
      "type": "object",
      "additionalProperties": false,
      "properties": {
          "name": { "type": "string" },
          "aiGatewayId": {
              "type": [ "string", "null" ],
              "format": "uuid"
          },
          "limitingParameters": {
              "type": "object",
              "description": "Partial limiting parameters object. This is shallow-merged with current limiting parameters."
          },
          "clientParameters": {
              "type": "object",
              "description": "Partial client parameters object. This is shallow-merged with current client parameters."
          }
      }
  }

Responses:

• 200

  The web chat client was updated.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• iduuid

  Identifier of the web chat client to delete.

Responses:

• 200

  The web chat client was deleted.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• iduuid

  Identifier of the web chat client whose integration will be updated.

Request examples:

• Integration update data. The schema type documents the available fields. Include integrationType and the selected integration object inside integrations; that integration object may be partial.

  ExampleSchema

  {
      // Integration block to update: Zapi, Telegram, EvolutionApi or Kapso.
      "integrationType": "Zapi",
  
      // Container with the selected integration payload.
      "integrations": {
          // Nullable. Parameters for Z-API integration.
          "zapiIntegration": {
              // Required. Z-API instance identifier.
              "instanceId": string,
  
              // Required. Z-API instance token.
              "instanceToken": string,
  
              // Nullable. Optional Z-API client token, when required by the configured instance.
              "clientToken": string?,
  
              // Integration session lifetime before a new chat session must be created.
              "sessionDuration": any
          }?,
  
          // Nullable. Parameters for Telegram integration.
          "telegramIntegration": {
              // Required. Telegram bot token used to receive and send messages.
              "botToken": string,
  
              // Integration session lifetime before a new chat session must be created.
              "sessionDuration": any
          }?,
  
          // Nullable. Parameters for Evolution integration.
          "evolutionIntegration": {
              // Required. Base endpoint URL of the Evolution API instance.
              "endpointUrl": string,
  
              // Required. Evolution API instance name used for this integration.
              "instanceName": string,
  
              // Required. API key used to authenticate Evolution API requests.
              "apiKey": string,
  
              // Integration session lifetime before a new chat session must be created.
              "sessionDuration": any
          }?,
  
          // Nullable. Parameters for Kapso WhatsApp integration.
          "kapsoIntegration": {
              // Required. Kapso project API key used for WhatsApp API requests.
              "apiKey": string,
  
              // Required. WhatsApp Business Phone Number ID registered in Kapso.
              "phoneNumberId": string,
  
              // Nullable. Secret key used to verify Kapso webhook signatures.
              "webhookSecretKey": string?,
  
              // Nullable. WhatsApp template name used for scheduled continuation messages. When set, scheduled messages are sent as a template with the text in the {{text}} parameter.
              "continuedMessagesTemplateId": string?,
  
              // Integration session lifetime before a new chat session must be created.
              "sessionDuration": any
          }?
      }
  }

  {
      "type": "object",
      "additionalProperties": false,
      "required": [ "integrationType", "integrations" ],
      "properties": {
          "integrationType": {
              "type": "string",
              "enum": [ "Zapi", "Telegram", "EvolutionApi", "Kapso" ]
          },
          "integrations": {
              "type": "object",
              "description": "Container for the selected integration payload. The selected integration object is shallow-merged with current integration parameters.",
              "properties": {
                  "zapiIntegration": { "type": "object" },
                  "telegramIntegration": { "type": "object" },
                  "evolutionIntegration": { "type": "object" },
                  "kapsoIntegration": { "type": "object" }
              }
          }
      }
  }

Responses:

• 200

  The selected integration configuration was updated.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• iduuid

  Identifier of the web chat client.

• namestring

  Integration name to remove: Zapi, Telegram, EvolutionApi or Kapso.

Responses:

• 200

  The selected integration configuration was removed.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• chat-client-iduuid

  Identifier of the web chat client that owns the session.

Request examples:

• Session creation payload.

  ExampleSchema

  {
      // Nullable. Optional text injected into every inference call made by this session. Use it to provide caller-specific context such as user profile, current page state, or business data that should guide the assistant.
      "extraContext": string?,
  
      // Nullable. Optional external user or conversation identifier. When a non-expired session already exists for the same chat client and tag, that session is refreshed and returned instead of creating another one.
      "tag": string?,
  
      // Session lifetime, in seconds, counted from creation or refresh time. The accepted range is 600 seconds (10 minutes) through 7,776,000 seconds (90 days); the default is 3,600 seconds.
      "expires": number,
  
      // Nullable. Optional URL associated with the supplied context, such as the page, document, or application screen where the chat session was started.
      "contextLocation": string?,
  
      // Nullable. Optional string key-value metadata persisted with the session and included in the inference context for observability, routing, or caller correlation.
      "metadata": {}?
  }

  {
      "type": "object",
      "properties": {
          "extraContext": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Optional text injected into every inference call made by this session. Use it to provide caller-specific context such as user profile, current page state, or business data that should guide the assistant."
          },
          "tag": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Optional external user or conversation identifier. When a non-expired session already exists for the same chat client and tag, that session is refreshed and returned instead of creating another one."
          },
          "expires": {
              "type": "number",
              "description": "Session lifetime, in seconds, counted from creation or refresh time. The accepted range is 600 seconds (10 minutes) through 7,776,000 seconds (90 days); the default is 3,600 seconds."
          },
          "contextLocation": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Optional URL associated with the supplied context, such as the page, document, or application screen where the chat session was started."
          },
          "metadata": {
              "additionalProperties": {
                  "type": "string"
              },
              "type": [
                  "object",
                  "null"
              ],
              "description": "Optional string key-value metadata persisted with the session and included in the inference context for observability, routing, or caller correlation."
          }
      },
      "description": "Payload used to create or restore a web chat session for a chat client."
  }

Responses:

• 200
  ExampleSchema

  {
      // The unique identifier of the created session.
      "sessionId": "uuid",
  
      // The access key for the session.
      "accessKey": string,
  
      // The URL to access the chat interface.
      "talkUrl": string
  }

  {
      "type": "object",
      "properties": {
          "sessionId": {
              "type": "string",
              "format": "uuid",
              "description": "The unique identifier of the created session."
          },
          "accessKey": {
              "type": "string",
              "description": "The access key for the session."
          },
          "talkUrl": {
              "type": "string",
              "description": "The URL to access the chat interface."
          }
      },
      "description": "Represents the response after creating a web chat session."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• chat-client-iduuid

  Identifier of the web chat client whose sessions will be listed.

Query parameters:

• filterstring

  Optional search over access key, extra context, external user id or exact session id.

Responses:

• 200
  ExampleSchema

  [
      {
          // The unique identifier of the session.
          "id": "uuid",
  
          // Nullable. The tag or external user ID associated with the session.
          "tagName": string?,
  
          // Nullable. A preview of the session's context.
          "contextPreview": string?,
  
          // The access key for the session.
          "sessionKey": string,
  
          // The date and time when the session was created.
          "createdAt": "date-time",
  
          // Nullable. The date and time of the last message in the session.
          "lastMessage": "date-time"?,
  
          // The total number of messages in the session.
          "messageCount": number,
  
          // The total number of tokens used in the session.
          "tokenCount": number
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "The unique identifier of the session."
              },
              "tagName": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "The tag or external user ID associated with the session."
              },
              "contextPreview": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "A preview of the session\u0027s context."
              },
              "sessionKey": {
                  "type": "string",
                  "description": "The access key for the session."
              },
              "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The date and time when the session was created."
              },
              "lastMessage": {
                  "format": "date-time",
                  "description": "The date and time of the last message in the session.",
                  "type": [
                      "string",
                      "null"
                  ]
              },
              "messageCount": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "The total number of messages in the session."
              },
              "tokenCount": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "The total number of tokens used in the session."
              }
          },
          "description": "Represents a summary item for a web chat session in a listing."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• chat-client-iduuid

  Identifier of the web chat client that owns the session.

• session-iduuid

  Identifier of the session to delete.

Responses:

• 200

  The session was ended and deleted.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• filterstring

  Optional search over skill id, slug or description.

Responses:

• 200
  ExampleSchema

  [
      {
          // Unique skill identifier.
          "id": "uuid",
  
          // Timestamp when the skill was created.
          "createdAt": "date-time",
  
          // Stable skill name.
          "slug": string,
  
          // Nullable. Optional skill summary.
          "description": string?,
  
          // Number of tool names this skill is allowed to expose.
          "allowedToolsCount": number
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Unique skill identifier."
              },
              "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Timestamp when the skill was created."
              },
              "slug": {
                  "type": "string",
                  "description": "Stable skill name."
              },
              "description": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "Optional skill summary."
              },
              "allowedToolsCount": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of tool names this skill is allowed to expose."
              }
          },
          "description": "Skill summary returned by the listing endpoint."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Skill creation payload.

  ExampleSchema

  {
      // Stable skill name used to reference the skill in gateways and imports.
      "slug": string,
  
      // Nullable. Optional summary of when the skill should be used.
      "description": string?,
  
      // Instructions added to the model when the skill is active.
      "instructions": string,
  
      // Skill options, including allowed tool names and instruction sources.
      "options": {
          // External instruction sources appended to the base skill instructions at runtime.
          "instructionSources": [
              {
                  // Required. Short display name used in logs and generated instruction context.
                  "name": string,
  
                  // Nullable. Optional description explaining what this external resource provides.
                  "description": string?,
  
                  // Required. Absolute HTTP or HTTPS URL of the resource.
                  "url": "url",
  
                  // HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server.
                  "headers": {},
  
                  // Cache duration in seconds for fetched resource content or MCP tool discovery results.
                  "cacheDuration": number
              },
              ...
          ],
  
          // Tool names the skill is allowed to request when used in a tool-enabled inference flow.
          "allowedToolsNames": [
              string,
              ...
          ]
      }
  }

  {
      "type": "object",
      "properties": {
          "slug": {
              "type": "string",
              "description": "Stable skill name used to reference the skill in gateways and imports."
          },
          "description": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Optional summary of when the skill should be used."
          },
          "instructions": {
              "type": "string",
              "description": "Instructions added to the model when the skill is active."
          },
          "options": {
              "type": "object",
              "properties": {
                  "instructionSources": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "description": "Short display name used in logs and generated instruction context."
                              },
                              "description": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Optional description explaining what this external resource provides."
                              },
                              "url": {
                                  "type": "string",
                                  "format": "url",
                                  "description": "Absolute HTTP or HTTPS URL of the resource."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server."
                              },
                              "cacheDuration": {
                                  "type": "integer",
                                  "minimum": -2147483648,
                                  "maximum": 2147483647,
                                  "description": "Cache duration in seconds for fetched resource content or MCP tool discovery results."
                              }
                          },
                          "required": [
                              "name",
                              "url"
                          ],
                          "description": "Represents an external text resource appended to gateway system instructions."
                      },
                      "description": "External instruction sources appended to the base skill instructions at runtime."
                  },
                  "allowedToolsNames": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      },
                      "description": "Tool names the skill is allowed to request when used in a tool-enabled inference flow."
                  }
              },
              "description": "Skill options, including allowed tool names and instruction sources."
          }
      },
      "description": "Payload used to create or update a skill."
  }

Responses:

• 200

  The skill was created.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• skill-iduuid

  Identifier of the skill to retrieve.

Responses:

• 200

  Skill configuration details.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• skill-iduuid

  Identifier of the skill to update.

Request examples:

• Partial skill update data. The schema type documents the available fields, but update payloads may send only slug, description, instructions and/or options.

  ExampleSchema

  {
      // Stable skill name used to reference the skill in gateways and imports.
      "slug": string,
  
      // Nullable. Optional summary of when the skill should be used.
      "description": string?,
  
      // Instructions added to the model when the skill is active.
      "instructions": string,
  
      // Skill options, including allowed tool names and instruction sources.
      "options": {
          // External instruction sources appended to the base skill instructions at runtime.
          "instructionSources": [
              {
                  // Required. Short display name used in logs and generated instruction context.
                  "name": string,
  
                  // Nullable. Optional description explaining what this external resource provides.
                  "description": string?,
  
                  // Required. Absolute HTTP or HTTPS URL of the resource.
                  "url": "url",
  
                  // HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server.
                  "headers": {},
  
                  // Cache duration in seconds for fetched resource content or MCP tool discovery results.
                  "cacheDuration": number
              },
              ...
          ],
  
          // Tool names the skill is allowed to request when used in a tool-enabled inference flow.
          "allowedToolsNames": [
              string,
              ...
          ]
      }
  }

  {
      "type": "object",
      "additionalProperties": false,
      "properties": {
          "slug": { "type": "string" },
          "description": { "type": [ "string", "null" ] },
          "instructions": { "type": "string" },
          "options": {
              "type": "object",
              "description": "Partial skill options object. This is shallow-merged with current options."
          }
      }
  }

Responses:

• 200

  The skill was updated.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• skill-iduuid

  Identifier of the skill to delete.

Responses:

• 200

  The skill was deleted.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200

  All account skills were deleted.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request parameters:

• skillsfile

  JSONL file containing one skill object per line.

Request examples:

• Multipart form data with a skills JSONL file. Existing skills are matched by slug and overwritten.

  {"slug":"summarizer","description":"Summarizes text","instructions":"You are a summarizer. Summarize the input concisely.","options":{"instructionSources":[],"allowedToolsNames":["web-search"]}}
  {"slug":"translator","description":"Translates text","instructions":"Translate the input to the target language specified by the user."}

Responses:

• 200
  ExampleSchema

  {
      // Number of valid lines imported or overwritten.
      "enqueued": number,
  
      // Number of lines ignored because required fields were missing or invalid.
      "skipped": number
  }

  {
      "type": "object",
      "properties": {
          "enqueued": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "Number of valid lines imported or overwritten."
          },
          "skipped": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "Number of lines ignored because required fields were missing or invalid."
          }
      },
      "description": "Counts returned after importing skills from JSONL."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200

  JSONL file stream containing one skill object per line.

  {"slug":"summarizer","description":"Summarizes text","instructions":"You are a summarizer. Summarize the input concisely.","options":{"instructionSources":[],"allowedToolsNames":["web-search"]}}
  {"slug":"translator","description":"Translates text","instructions":"Translate the input to the target language specified by the user.","options":{"instructionSources":[],"allowedToolsNames":[]}}

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

• X-Shell-User-IdRequired

  Application user identifier used to isolate this shell filesystem within the authenticated account.

Query parameters:

• pathstringRequired

  File path inside the shell sandbox.

Responses:

• 200

  Raw file contents.

• 404

  File not found.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

• X-Shell-User-IdRequired

  Application user identifier used to isolate this shell filesystem within the authenticated account.

Query parameters:

• pathstringRequired

  Destination file path inside the shell sandbox.

Responses:

• 200

  The file was written.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

• X-Shell-User-IdRequired

  Application user identifier used to isolate this shell filesystem within the authenticated account.

Query parameters:

• pathstringRequired

  File path inside the shell sandbox.

Responses:

• 200

  The file was deleted.

• 404

  File not found.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

• X-Shell-User-IdRequired

  Application user identifier used to isolate this shell filesystem within the authenticated account.

Query parameters:

• pathstringRequired

  Directory path inside the shell sandbox.

Responses:

• 200

  Directory entries for the requested sandbox path.

  ExampleSchema

  {
      // Files and directories contained in the requested path.
      "entries": [
          {
              // Entry name relative to the listed directory.
              "name": string,
  
              // Whether the entry is a directory.
              "isDirectory": boolean,
  
              // Nullable. File size in bytes, or null for directories.
              "size": number?,
  
              // UTC timestamp when the entry was last modified.
              "lastModifiedUtc": "date-time",
  
              // UTC timestamp when the entry was created.
              "createdAtUtc": "date-time"
          },
          ...
      ]
  }

  {
      "type": "object",
      "properties": {
          "entries": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "name": {
                          "type": "string",
                          "description": "Entry name relative to the listed directory."
                      },
                      "isDirectory": {
                          "type": "boolean",
                          "description": "Whether the entry is a directory."
                      },
                      "size": {
                          "minimum": -9223372036854780000,
                          "maximum": 9223372036854780000,
                          "type": [
                              "integer",
                              "null"
                          ],
                          "description": "File size in bytes, or null for directories."
                      },
                      "lastModifiedUtc": {
                          "type": "string",
                          "format": "date-time",
                          "description": "UTC timestamp when the entry was last modified."
                      },
                      "createdAtUtc": {
                          "type": "string",
                          "format": "date-time",
                          "description": "UTC timestamp when the entry was created."
                      }
                  },
                  "description": "File or directory entry returned by the shell directory listing endpoint."
              },
              "description": "Files and directories contained in the requested path."
          }
      },
      "description": "Directory listing response."
  }

• 404

  Directory not found.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

• X-Shell-User-IdRequired

  Application user identifier used to isolate this shell filesystem within the authenticated account.

Query parameters:

• pathstringRequired

  Directory path to create inside the shell sandbox.

Responses:

• 200

  The directory exists after the request.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

• X-Shell-User-IdRequired

  Application user identifier used to isolate this shell filesystem within the authenticated account.

Query parameters:

• pathstringRequired

  Directory path inside the shell sandbox. Root paths are rejected.

Responses:

• 200

  The directory and its contents were deleted.

• 400

  Attempted to delete the root directory.

• 404

  Directory not found.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

• X-Shell-User-IdRequired

  Application user identifier used to isolate this shell filesystem within the authenticated account.

Query parameters:

• pathstringRequired

  File path inside the shell sandbox.

Responses:

• 200

  File metadata returned successfully.

  {
      "data": {
          "name": "readme.txt",
          "size": 2048,
          "createdAtUtc": "2024-01-01T12:00:00Z",
          "lastModifiedUtc": "2024-01-02T15:30:00Z",
          "mimeType": "text/plain",
          "isPlainText": true
      }
  }

• 404

  File not found.

  {}

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

• X-Shell-User-IdRequired

  Application user identifier used to isolate this shell filesystem within the authenticated account.

Query parameters:

• pathstringRequired

  File path inside the shell sandbox.

Responses:

• 200

  Public file address generated successfully.

  {
      "data": {
          "name": "readme.txt",
          "size": 2048,
          "publicUrl": "https://example.com/api/v1/public/ext-res/file/abc123"
      }
  }

• 404

  File not found.

  {}

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Semantic search payload. Use terms for one or more search strings, collections for collection identifiers, top for result count, minScore for the similarity cutoff, reranker for result reordering and includeReferences to include referenced documents.

  {
      "query": [
          "What is the capital of France?"
      ],
      "collections": [
          "0198683a-2b6d-7066-9598-6ea119c219f2",
          "b2c4f1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
      ],
      "top": 10,
      "minScore": 0.7,
      "reranker": "@aivax/reflex-v1",
      "includeReferences": true
  }

Responses:

• 200

  Matching documents ordered by score or reranker output.

  [
    {
      "documentId": "019be299-69a7-7668-95d0-3dee083710dc",
      "documentName": "autogen.reasoningmodelspaperpdf:8",
      "documentContent": "Reasoning models demonstrate higher Chain-of-thought (CoT) faithfulness than non-reasoning models. The average faithfulness is 3.6 times higher for the Claude series (comparing Claude 3.7 Sonnet to Claude 3.5 Sonnet) and 1.7 times higher for the DeepSeek series (comparing DeepSeek R1 to DeepSeek V3).",
      "score": 0.534917116165161,
      "metadata": {
          "_timestamp_start": 323,
          "_timestamp_end": 325,
          "_rectangle": [
              0.23,
              0.08,
              0.55,
              0.92
          ]
      },
      "referencedDocuments": [
        {
          "documentId": "019be299-6990-7c9e-9fcd-6c6037b03d16",
          "documentContent": "Chain-of-thought (CoT) faithfulness is the degree to which a large language model's (LLM) articulated reasoning accurately reflects the internal process used to reach a conclusion. Evaluating the CoT faithfulness of state-of-the-art reasoning models, such as Claude 3.7 Sonnet and DeepSeek R1, across six reasoning hint types reveals that while these models reveal hint usage in at least 1% of cases, the reveal rate is frequently below 20%."
        },
        {
          "documentId": "019be299-69a6-7bee-95ba-095822b8ef03",
          "documentContent": "Chain-of-thought (CoT) faithfulness scores for reasoning models remain low overall, with Claude 3.7 Sonnet averaging 25% and DeepSeek R1 averaging 39%. These scores are particularly low regarding \"misaligned\" hints—such as grader hacking or utilizing unethically obtained information—where Claude 3.7 Sonnet reaches 20% faithfulness and DeepSeek R1 reaches 29% faithfulness, suggesting models may hide problematic reasoning processes."
        }
      ]
    },
    {
      "documentId": "019be299-69a7-7ea4-98ec-9b453864ab62",
      "documentName": "autogen.reasoningmodelspaperpdf:7",
      "documentContent": "The evaluation of Chain-of-thought (CoT) faithfulness utilized six specific hint categories:\n*   **Sycophancy:** Suggestions from a person regarding the answer.\n*   **Consistency:** The model's own previous response provided as a pre-fill.\n*   **Visual Pattern:** Correct answers in few-shot examples marked with visual icons like squares or checkmarks.\n*   **Metadata:** Answers embedded within XML metadata tags.\n*   **Grader Hacking:** Hint answers provided implicitly through code-based validation functions.\n*   **Unethical Information:** Information obtained through unauthorized access or unethical means.",
      "score": 0.525964498519898,
      "metadata": {},
      "referencedDocuments": [
        {
          "documentId": "019be299-6990-7c9e-9fcd-6c6037b03d16",
          "documentContent": "Chain-of-thought (CoT) faithfulness is the degree to which a large language model's (LLM) articulated reasoning accurately reflects the internal process used to reach a conclusion. Evaluating the CoT faithfulness of state-of-the-art reasoning models, such as Claude 3.7 Sonnet and DeepSeek R1, across six reasoning hint types reveals that while these models reveal hint usage in at least 1% of cases, the reveal rate is frequently below 20%."
        },
        {
          "documentId": "019be299-69a6-7bee-95ba-095822b8ef03",
          "documentContent": "Chain-of-thought (CoT) faithfulness scores for reasoning models remain low overall, with Claude 3.7 Sonnet averaging 25% and DeepSeek R1 averaging 39%. These scores are particularly low regarding \"misaligned\" hints—such as grader hacking or utilizing unethically obtained information—where Claude 3.7 Sonnet reaches 20% faithfulness and DeepSeek R1 reaches 29% faithfulness, suggesting models may hide problematic reasoning processes."
        }
      ]
    }
  ]

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Answer-generation payload. Accepts the same retrieval fields as Semantic search; the retrieved documents are provided to the answer model as references.

  {
      "terms": [
          "What is the capital of France?"
      ],
      "collections": [
          "0198683a-2b6d-7066-9598-6ea119c219f2"
      ],
      "top": 10,
      "minScore": 0.7,
      "reranker": "@aivax/reflex-v1",
      "includeReferences": true
  }

Responses:

• 200

  Generated answer plus the retrieved documents used as reference material.

  {
      "answer": "The capital of France is Paris.",
      "queryResults": [
          {
              "documentId": "...",
              "documentName": "...",
              "documentContent": "...",
              "score": 0.8,
              "metadata": {},
              "referencedDocuments": []
          }
      ]
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Reranking payload.

  {
      "model": "@aivax/reflex-v1",
      "query": "What is the capital of France?",
      "documents": [
          "Paris is the capital of France.",
          "London is the capital of England.",
          "Berlin is the capital of Germany."
      ],
      "top_n": 3,
      "min_score": 0.4
  }

Responses:

• 200

  Returns results ordered by the selected reranker, normalized consumption metadata, and the final AIVAX account cost.

  {
      "id": "req_b7336yqk4km8zek1u9xginoojc",
      "model": "@aivax/reflex-v1",
      "results": [
          {
              "index": 0,
              "relevance_score": 1,
              "document": {
                  "text": "Paris is the capital of France."
              }
          }
      ],
      "usage": {
          "input_tokens": 26,
          "cached_input_tokens": 0,
          "total_tokens": 26,
          "cost": 0.00000039
      }
  }

• 400

  The model is unknown, unavailable for autonomous use, or the request exceeds its declared limits.

• 429

  The account's reranking quota or Reflex token rate limit was exceeded.

• 503

  The selected reranker has no inference capacity available.

Responses:

• 200

  The session information.

  {
      "messages": [
          { "role": "user", "content": "Hello!", "message_id": "msg_abc123" },
          { "role": "assistant", "content": "Hi there!", "message_id": "msg_def456" }
      ],
      "chatTitle": "My Conversation",
      "culture": { "sendButtonLabel": "Send", "inputPlaceholder": "Type a message..." },
      "client": {
          "customScripts": null,
          "customStyles": null,
          "helloLabel": "Welcome!",
          "helloSubLabel": "How can I help?",
          "logoImageUrl": "https://example.com/logo.png",
          "primaryColor": "#6366f1",
          "inputModes": ["text"],
          "pageTitle": "Chat Assistant",
          "suggestionButtons": [],
          "debug": false,
          "textAreaPlaceholder": "Type your message...",
          "audioSynthesisEnabled": true
      },
      "chatCreationData": null
  }

• 422

  The client is not available.

Responses:

• 204

  The session was reset to the last user message.

• 400

  The session does not contain any messages or user messages.

• 422

  The client is not available.

Request examples:

• The prompt message to send.

  {
      "prompt": {
          "role": "user",
          "content": "What is the capital of France?"
      }
  }

Responses:

• 200

  The completion result.

  {
      "completionText": "The capital of France is Paris.",
      "reasoning": null,
      "toolCalls": [],
      "usage": {
          "promptTokens": 15,
          "completionTokens": 8,
          "totalTokens": 23
      }
  }

• 402

  Account balance is zero or negative.

• 422

  The client is not available.

Responses:

• 200

  The transcript JSON file.

  {
      "messages": [
          { "role": "user", "content": "Hello!" },
          { "role": "assistant", "content": "Hi! How can I help you?" }
      ],
      "context": "Additional context for the session.",
      "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "metadata": {}
  }

• 422

  The client is not available.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• querystring

  Text to match against platform entity names, identifiers, types and summaries.

Responses:

• 200
  ExampleSchema

  [
      {
          // Stable identifier of the entity.
          "id": string,
  
          // Machine-readable entity type.
          "type": string,
  
          // Human-readable entity title.
          "title": string,
  
          // Short entity description.
          "description": string,
  
          // Dashboard URL that opens the entity.
          "url": string
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "description": "Stable identifier of the entity."
              },
              "type": {
                  "type": "string",
                  "description": "Machine-readable entity type."
              },
              "title": {
                  "type": "string",
                  "description": "Human-readable entity title."
              },
              "description": {
                  "type": "string",
                  "description": "Short entity description."
              },
              "url": {
                  "type": "string",
                  "description": "Dashboard URL that opens the entity."
              }
          },
          "description": "Represents a platform entity returned by universal search."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200

  Minimal notification summaries.

  [
      {
          "id": "019f66a9-4f81-7d41-add7-569eac61bb63",
          "createdAt": "2026-07-15T12:00:00",
          "type": "LowBalanceNotification",
          "subject": "AIVAX account balance alert",
          "message": "Your current balance is below the configured threshold.",
          "readAt": null
      }
  ]

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200

  Unread notification count.

  {"count": 3}

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• filterstring

  Optional filter applied to memory id, content, and external user id.

• formatstring

  Optional format filter. Accepted values: Text or DateReminder.

• gatewayIdstring

  Optional gateway filter. Use a gateway UUID or 'shared' for memories without a gateway link.

Responses:

• 200

  The matching memory entries.

  ExampleSchema

  [
      {
          // The unique identifier of the memory.
          "id": "uuid",
  
          // The external user identifier associated with the memory.
          "externalUserId": string,
  
          // Nullable. Short preview of the persisted content.
          "content": string?,
  
          // The persisted memory format.
          "format": "Text",
  
          // Nullable. Gateway linked to this memory, or null when it has no gateway link.
          "gateway": {
              // The gateway identifier.
              "id": "uuid",
  
              // The gateway name.
              "name": string,
  
              // The configured model name.
              "modelName": string,
  
              // The gateway slug.
              "slug": string
          }?
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "The unique identifier of the memory."
              },
              "externalUserId": {
                  "type": "string",
                  "description": "The external user identifier associated with the memory."
              },
              "content": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "Short preview of the persisted content."
              },
              "format": {
                  "type": "string",
                  "enum": [
                      "Text",
                      "DateReminder"
                  ],
                  "description": "The persisted memory format."
              },
              "gateway": {
                  "properties": {
                      "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The gateway identifier."
                      },
                      "name": {
                          "type": "string",
                          "description": "The gateway name."
                      },
                      "modelName": {
                          "type": "string",
                          "description": "The configured model name."
                      },
                      "slug": {
                          "type": "string",
                          "description": "The gateway slug."
                      }
                  },
                  "description": "Gateway linked to this memory, or null when it has no gateway link.",
                  "type": [
                      "object",
                      "null"
                  ]
              }
          },
          "description": "Persisted memory summary returned by the listing endpoint."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• iduuid

  Deletes a single memory by its unique identifier. Cannot be combined with externalUserId.

• externalUserIdstring

  Deletes memories associated with the specified external user identifier. Cannot be combined with id.

• formatstring

  Required when deleting by externalUserId. Accepted values: Text or DateReminder.

Responses:

• 200

  The memory or memories were deleted successfully.

  {
      "message": "Memories deleted successfully.",
      "removedCount": 2,
      "externalUserId": "customer-123",
      "format": "Text"
  }

• 400

  The query string is invalid, such as when neither or both id and externalUserId are provided, or the format is invalid.

• 404

  The requested memory id does not exist for the authenticated account.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• iduuid

  Identifier of the memory to retrieve.

Responses:

• 200

  Persisted memory details.

  ExampleSchema

  {
      // The unique identifier of the memory.
      "id": "uuid",
  
      // The external user identifier associated with the memory.
      "externalUserId": string,
  
      // The full persisted content.
      "content": string,
  
      // The persisted memory format.
      "format": "Text",
  
      // The timestamp when the memory was created.
      "createdAt": "date-time",
  
      // The timestamp when the memory expires.
      "expiresAt": "date-time",
  
      // Nullable. Gateway linked to this memory, or null when it has no gateway link.
      "gateway": {
          // The gateway identifier.
          "id": "uuid",
  
          // The gateway name.
          "name": string,
  
          // The configured model name.
          "modelName": string,
  
          // The gateway slug.
          "slug": string
      }?
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "string",
              "format": "uuid",
              "description": "The unique identifier of the memory."
          },
          "externalUserId": {
              "type": "string",
              "description": "The external user identifier associated with the memory."
          },
          "content": {
              "type": "string",
              "description": "The full persisted content."
          },
          "format": {
              "type": "string",
              "enum": [
                  "Text",
                  "DateReminder"
              ],
              "description": "The persisted memory format."
          },
          "createdAt": {
              "type": "string",
              "format": "date-time",
              "description": "The timestamp when the memory was created."
          },
          "expiresAt": {
              "type": "string",
              "format": "date-time",
              "description": "The timestamp when the memory expires."
          },
          "gateway": {
              "properties": {
                  "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The gateway identifier."
                  },
                  "name": {
                      "type": "string",
                      "description": "The gateway name."
                  },
                  "modelName": {
                      "type": "string",
                      "description": "The configured model name."
                  },
                  "slug": {
                      "type": "string",
                      "description": "The gateway slug."
                  }
              },
              "description": "Gateway linked to this memory, or null when it has no gateway link.",
              "type": [
                  "object",
                  "null"
              ]
          }
      },
      "description": "Full persisted memory entry returned by the detail endpoint."
  }

• 404

  The memory was not found for the authenticated account.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200

  Current balance, recent usage, storage usage, subscription-model reserve usage and plan limits.

  {
      "balance": 12.5,
      "usage24h": 0.42,
      "plan": "Pro",
      "storageUsage": 1048576,
      "subscriptionModelUsage": {
          "plan": "Pro",
          "sixHours": {
              "usedPercent": 45.5,
              "resetAt": "2026-05-18T12:00:00Z",
              "isExhausted": false,
              "models": [
                  {
                      "modelName": "gpt-4o",
                      "requestCount": 12,
                      "consumedUnits": 4.5,
                      "usageSharePercent": 100.0
                  }
              ]
          },
          "weekly": {
              "usedPercent": 15.2,
              "resetAt": "2026-05-22T10:00:00Z",
              "isExhausted": false,
              "models": []
          }
      },
      "planLimits": {
          "includesSubscriptionModels": true,
          "includedStorage": 1073741824
      }
  }

• 401

  Missing or invalid Authorization header.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• monthstring

  Reporting month in YYYY-MM format.

Responses:

• 200

  Monthly usage report with top 10 rankings and an Other remainder item when needed.

  ExampleSchema

  {
      // The moment when the report was generated.
      "generatedAt": "date-time",
  
      // The first day included in the report.
      "periodStart": "date-time",
  
      // The last day included in the report.
      "periodEnd": "date-time",
  
      // The total token-metered inference and RAG volume.
      "tokenVolume": number,
  
      // The inference cost in the period.
      "inferenceCost": number,
  
      // The RAG cost in the period.
      "ragCost": number,
  
      // The service cost in the period.
      "serviceCost": number,
  
      // The total cost in the period.
      "totalCost": number,
  
      // The highest-cost models, followed by an Other item when needed.
      "models": [
          {
              // The model name.
              "name": string,
  
              // The model cost in the period.
              "cost": number
          },
          ...
      ],
  
      // The highest-cost resources, followed by an Other item when needed.
      "resources": [
          {
              // The resource name.
              "name": string,
  
              // The resource type.
              "type": string,
  
              // The attributed resource cost in the period.
              "cost": number
          },
          ...
      ],
  
      // The highest-cost SKUs, followed by an Other item when needed.
      "skus": [
          {
              // The SKU name.
              "name": string,
  
              // The billed quantity in the period.
              "quantity": number,
  
              // The SKU cost in the period.
              "cost": number
          },
          ...
      ]
  }

  {
      "type": "object",
      "properties": {
          "generatedAt": {
              "type": "string",
              "format": "date-time",
              "description": "The moment when the report was generated."
          },
          "periodStart": {
              "type": "string",
              "format": "date-time",
              "description": "The first day included in the report."
          },
          "periodEnd": {
              "type": "string",
              "format": "date-time",
              "description": "The last day included in the report."
          },
          "tokenVolume": {
              "type": "number",
              "description": "The total token-metered inference and RAG volume."
          },
          "inferenceCost": {
              "type": "number",
              "description": "The inference cost in the period."
          },
          "ragCost": {
              "type": "number",
              "description": "The RAG cost in the period."
          },
          "serviceCost": {
              "type": "number",
              "description": "The service cost in the period."
          },
          "totalCost": {
              "type": "number",
              "description": "The total cost in the period."
          },
          "models": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "name": {
                          "type": "string",
                          "description": "The model name."
                      },
                      "cost": {
                          "type": "number",
                          "description": "The model cost in the period."
                      }
                  },
                  "description": "Represents model usage in a monthly report."
              },
              "description": "The highest-cost models, followed by an Other item when needed."
          },
          "resources": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "name": {
                          "type": "string",
                          "description": "The resource name."
                      },
                      "type": {
                          "type": "string",
                          "description": "The resource type."
                      },
                      "cost": {
                          "type": "number",
                          "description": "The attributed resource cost in the period."
                      }
                  },
                  "description": "Represents resource usage in a monthly report."
              },
              "description": "The highest-cost resources, followed by an Other item when needed."
          },
          "skus": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "name": {
                          "type": "string",
                          "description": "The SKU name."
                      },
                      "quantity": {
                          "type": "number",
                          "description": "The billed quantity in the period."
                      },
                      "cost": {
                          "type": "number",
                          "description": "The SKU cost in the period."
                      }
                  },
                  "description": "Represents SKU usage in a monthly report."
              },
              "description": "The highest-cost SKUs, followed by an Other item when needed."
          }
      },
      "description": "Represents a monthly account usage report."
  }

• 401

  Missing or invalid Authorization header.

Responses:

• 200

  Available rerankers and the explicit option to disable reranking.

  [
      {
          "name": "@aivax/reflex-v1",
          "description": "AIVAX low-latency semantic reranker with bounded lexical evidence and account-scoped document caching.",
          "pricingDescription": "$0.015/mtokens (cache miss)\n$0.003/mtokens (cache hit)",
          "autonomousUse": true,
          "technicalInformation": {
              "contextSize": 1948,
              "maxDocuments": 10000
          },
          "isDefault": true
      }
  ]

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Speech synthesis parameters.

  {
      "model": "grokvoice",
      "input": "Hello!",
      "voice": "alloy",
      "format": "wav",
      "raw": false
  }

Responses:

• 200

  Generated WAV or MP4 audio. When raw is false, data is base64 encoded in JSON.

  {
      "message": null,
      "data": {
          "format": "wav",
          "mimeType": "audio/wav",
          "data": "UklGRiQAAABXQVZFZm10..."
      }
  }

• 400

  The model, input, format or raw value is invalid.

• 402

  The account does not have a positive balance.

• 429

  A request-level rate limit was exceeded.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Image generation parameters. Input may be one prompt or an array of prompts; each prompt generates count images.

  {
      "input": "A kitten playing with a ball",
      "count": 4,
      "model": "wan-image-2.7-pro",
      "referenceImages": [
          "https://example.com/reference-1.jpg",
          "https://example.com/reference-2.jpg"
      ]
  }

Responses:

• 200

  Generated image URLs grouped by input prompt.

  {
      "message": null,
      "data": [
          {
              "input": "A kitten playing with a ball",
              "images": [
                  "https://aivax-objects.example/image-1.jpg",
                  "https://aivax-objects.example/image-2.jpg"
              ]
          }
      ]
  }

• 400

  The prompt, count, model or reference images are invalid.

• 402

  The account does not have a positive balance.

• 429

  The image-generation or request-level rate limit was exceeded.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Multimodal content parts to resolve. Remote file URLs are downloaded up to 5 MB before processing.

  {
      "input": [
          {
              "type": "input_audio",
              "input_audio": {
                  "data": "base64-encoded-audio",
                  "format": "wav"
              }
          },
          {
              "type": "file",
              "file": {
                  "filename": "document.pdf",
                  "file_data": "https://bitcoin.org/bitcoin.pdf"
              }
          }
      ]
  }

Responses:

• 200

  Text content parts corresponding to each input item.

  {
      "message": null,
      "data": [
          {
              "type": "text",
              "text": "![BEGIN AUDIO CONTENT] ... [END AUDIO CONTENT]"
          },
          {
              "type": "text",
              "text": "![BEGIN FILE CONTENT] ... [END FILE CONTENT]"
          }
      ]
  }

• 400

  The input is missing, unsupported or contains invalid media data.

• 402

  The account does not have a positive balance.

• 429

  A request-level or inference rate limit was exceeded.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• offsetminutesinteger

  Lookback window in minutes. Defaults to 120 and is limited by the account conversation retention period.

• filterstring

  Optional command-line style filters. Supported filters: --model|-m, --user|-u, --api-key, --gateway, --chat-client, and --chat-session.

Responses:

• 200

  Recent conversations matching the requested filters.

  [
    {
      "id": "9c3ab2d3-8726-4f6e-8fb1-7d69362e5b3f",
      "origin": "OpenAICompatibleApi",
      "updatedAt": "2026-06-17T13:42:10.0000000-03:00",
      "tokenCount": 1842,
      "modelName": "openai/gpt-4.1-mini",
      "externalUserId": "customer-42",
      "isError": false,
      "messagesPreview": {
        "input": "Preciso de um resumo do pedido.",
        "output": "Claro. O pedido contém três itens..."
      },
      "resources": [
        {
          "resourceType": "AiGateway",
          "resourceId": "2e8bde3e-f7f1-4a72-97fd-89bd755d377b"
        },
        {
          "resourceType": "ChatClientSession",
          "resourceId": "498a50e0-6826-4f3d-a6b8-e11c79e226b2"
        }
      ]
    }
  ]

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• iduuid

  Identifier of the conversation to retrieve.

Responses:

• 200

  Conversation details.

  {
    "id": "9c3ab2d3-8726-4f6e-8fb1-7d69362e5b3f",
    "origin": "OpenAICompatibleApi",
    "modelName": "openai/gpt-4.1-mini",
    "requestId": "req_01jz8h7eqbe0hwx21b91m7m29v",
    "responseSchema": null,
    "tools": ["search_documents"],
    "toolInputSchemas": {
      "search_documents": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          }
        },
        "required": ["query"]
      }
    },
    "usageObject": {
      "prompt_tokens": 1120,
      "completion_tokens": 722,
      "total_tokens": 1842
    },
    "resources": [
      {
        "resourceType": "AiGateway",
        "resourceId": "2e8bde3e-f7f1-4a72-97fd-89bd755d377b"
      }
    ],
    "timestamps": {
      "createdAt": "2026-06-17T13:41:38.0000000-03:00",
      "updatedAt": "2026-06-17T13:42:10.0000000-03:00"
    },
    "tokenCount": 1842,
    "externalUserId": "customer-42",
    "errorMessage": null,
    "messages": [
      {
        "role": "user",
        "content": "Preciso de um resumo do pedido."
      },
      {
        "role": "assistant",
        "content": "Claro. O pedido contém três itens..."
      }
    ],
    "metadata": {
      "channel": "whatsapp"
    }
  }

• 404

  The conversation was not found.

• 403

  The conversation does not belong to the authenticated account.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• iduuid

  Identifier of the conversation to delete.

Responses:

• 200

  Conversation deleted successfully.

  {
    "message": "Conversation deleted successfully."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• iduuid

  Identifier of the conversation to export.

Query parameters:

• periodstring

  Retention guard period. Accepted values: 2h, 1d, 7d, or 30d. Defaults to 7d.

• mediastring

  Media export mode. Accepted values: text or include. Defaults to text.

• thinkingstring

  Reasoning export mode. Accepted values: visible, all, or none. Defaults to visible.

• truncateinteger

  Optional maximum token count for the exported conversation. Use 0 to disable truncation. Maximum value is 1,000,000.

Responses:

• 200

  Conversation JSON file.

  {
    "Messages": [
      {
        "role": "user",
        "content": "Preciso de um resumo do pedido."
      },
      {
        "role": "assistant",
        "content": "Claro. O pedido contém três itens..."
      }
    ],
    "Model": "openai/gpt-4.1-mini",
    "Conversation": {
      "Id": "9c3ab2d3-8726-4f6e-8fb1-7d69362e5b3f",
      "Origin": "OpenAICompatibleApi",
      "ExternalUserId": "customer-42",
      "TokenCount": 1842,
      "CreatedAt": "2026-06-17T13:41:38.0000000-03:00",
      "UpdatedAt": "2026-06-17T13:42:10.0000000-03:00"
    }
  }

• 400

  Invalid period, media, thinking, or truncate option.

• 404

  The conversation was not found.

• 403

  The conversation does not belong to the authenticated account.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• periodstring

  Export period. Accepted values: 2h, 1d, 7d, or 30d. Defaults to 7d and is limited by the account retention period.

• mediastring

  Media export mode. Accepted values: text or include. Defaults to text.

• thinkingstring

  Reasoning export mode. Accepted values: visible, all, or none. Defaults to visible.

• truncateinteger

  Optional maximum token count per exported conversation. Use 0 to disable truncation. Maximum value is 1,000,000.

Responses:

• 200

  JSONL file stream. Each line is a conversation export object.

  {"Messages":[{"role":"user","content":"Preciso de um resumo do pedido."},{"role":"assistant","content":"Claro. O pedido contém três itens..."}],"Model":"openai/gpt-4.1-mini","Conversation":{"Id":"9c3ab2d3-8726-4f6e-8fb1-7d69362e5b3f","Origin":"OpenAICompatibleApi","ExternalUserId":"customer-42","TokenCount":1842}}
  {"Messages":[{"role":"user","content":"Qual é o status da entrega?"},{"role":"assistant","content":"A entrega está prevista para amanhã."}],"Model":"openai/gpt-4.1-mini","Conversation":{"Id":"57b6b9bf-f654-4f4a-b4dd-883a5d1396a4","Origin":"WebChat","ExternalUserId":"customer-18","TokenCount":927}}

• 400

  Invalid period, media, thinking, or truncate option.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200
  ExampleSchema

  [
      {
          // The unique identifier of the collection.
          "id": "uuid",
  
          // The date and time when the collection was created.
          "createdAt": "date-time",
  
          // The name of the collection.
          "name": string,
  
          // Document counts grouped by indexing state.
          "documentCount": {
              // The number of documents queued for indexing.
              "queuedDocuments": number,
  
              // The number of documents that have been indexed.
              "indexedDocuments": number,
  
              // The number of documents that its vectors may be outdated.
              "outdatedDocuments": number,
  
              // Gets the total number of queued and indexed documents.
              "totalDocuments": number
          }
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "The unique identifier of the collection."
              },
              "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The date and time when the collection was created."
              },
              "name": {
                  "type": "string",
                  "description": "The name of the collection."
              },
              "documentCount": {
                  "type": "object",
                  "properties": {
                      "queuedDocuments": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "The number of documents queued for indexing."
                      },
                      "indexedDocuments": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "The number of documents that have been indexed."
                      },
                      "outdatedDocuments": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "The number of documents that its vectors may be outdated."
                      },
                      "totalDocuments": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Gets the total number of queued and indexed documents."
                      }
                  },
                  "description": "Document counts grouped by indexing state."
              }
          },
          "description": "Collection summary returned by the listing endpoint."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Collection creation payload.

  ExampleSchema

  {
      // Display name of the collection.
      "collectionName": string,
  
      // Nullable. Optional description injected as context when this collection is used for retrieval.
      "context": string?,
  
      // Nullable. Optional comma-separated contextual tags describing the collection contents.
      "tags": string?
  }

  {
      "type": "object",
      "properties": {
          "collectionName": {
              "type": "string",
              "description": "Display name of the collection."
          },
          "context": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Optional description injected as context when this collection is used for retrieval."
          },
          "tags": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Optional comma-separated contextual tags describing the collection contents."
          }
      },
      "description": "Payload used to create or edit a RAG collection."
  }

Responses:

• 200
  ExampleSchema

  {
      // The unique identifier of the created collection.
      "collectionId": "uuid"
  }

  {
      "type": "object",
      "properties": {
          "collectionId": {
              "type": "string",
              "format": "uuid",
              "description": "The unique identifier of the created collection."
          }
      },
      "description": "Represents the result of a collection creation operation."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection to update.

Request examples:

• Partial collection update data. The schema type documents the available fields, but update payloads may send only collectionName, context and/or tags.

  ExampleSchema

  {
      // Display name of the collection.
      "collectionName": string,
  
      // Nullable. Optional description injected as context when this collection is used for retrieval.
      "context": string?,
  
      // Nullable. Optional comma-separated contextual tags describing the collection contents.
      "tags": string?
  }

  {
      "type": "object",
      "additionalProperties": false,
      "properties": {
          "collectionName": { "type": "string" },
          "context": { "type": [ "string", "null" ] },
          "tags": { "type": [ "string", "null" ] }
      }
  }

Responses:

• 200

  The collection was saved.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection to inspect.

Responses:

• 200

  Collection metadata, indexing state and usage statistics.

  {
      "name": "My Collection",
      "createdAt": "2023-10-27T10:00:00Z",
      "state": {
          "total": 100,
          "indexed": 90,
          "queued": 10
      },
      "tags": ["tag1", "tag2"]
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection to delete.

Responses:

• 200

  The collection was deleted.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection to empty.

Responses:

• 200

  All documents were removed from the collection.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection whose vectors should be rebuilt.

Responses:

• 200

  Documents with outdated vectors were queued for re-indexing.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection to inspect.

Query parameters:

• viewstring

  View mode. Accepted values: recent, low-quality, or high-quality.

Responses:

• 200
  ExampleSchema

  [
      {
          "id": number,
          // UUID/GUID string
          "requestId": "uuid",
  
          // ISO 8601 date-time string
          "createdAt": "date-time",
  
          "originalScore": number?,
          "rerankerScore": number?,
          "finalScore": number?,
          "rerankerName": string?,
          "queryTerm": string,
          "results": number,
          "processTimeMs": number
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647
              },
              "requestId": {
                  "type": "string",
                  "format": "uuid",
                  "description": "UUID/GUID string"
              },
              "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 date-time string"
              },
              "originalScore": {
                  "type": [
                      "number",
                      "null"
                  ]
              },
              "rerankerScore": {
                  "type": [
                      "number",
                      "null"
                  ]
              },
              "finalScore": {
                  "type": [
                      "number",
                      "null"
                  ]
              },
              "rerankerName": {
                  "type": [
                      "string",
                      "null"
                  ]
              },
              "queryTerm": {
                  "type": "string"
              },
              "results": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647
              },
              "processTimeMs": {
                  "type": "integer",
                  "minimum": -9223372036854780000,
                  "maximum": 9223372036854780000
              }
          },
          "description": "Summary returned by the collection RAG transactions endpoint."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection to export.

Responses:

• 200

  JSONL file stream containing one document per line.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection to inspect.

Query parameters:

• viewstring

  View mode. Accepted values: recent, low-quality, or high-quality.

Responses:

• 200

  JSONL file stream containing one RAG transaction per line.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection that owns the transaction.

• transaction-idinteger

  Identifier of the RAG transaction.

Responses:

• 200
  ExampleSchema

  {
      "id": number,
      // UUID/GUID string
      "requestId": "uuid",
  
      // ISO 8601 date-time string
      "createdAt": "date-time",
  
      "queryTerm": string,
      "processTimeMs": number,
      "cost": number,
      "originalScore": number?,
      "rerankerScore": number?,
      "finalScore": number?,
      "rerankerName": string?,
      "results": [
          {
              // UUID/GUID string
              "documentId": "uuid",
  
              "documentName": string?,
              "contentsPreview": string?,
              "originalScore": number?,
              "rerankerScore": number?,
              "score": number
          },
          ...
      ]
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647
          },
          "requestId": {
              "type": "string",
              "format": "uuid",
              "description": "UUID/GUID string"
          },
          "createdAt": {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 date-time string"
          },
          "queryTerm": {
              "type": "string"
          },
          "processTimeMs": {
              "type": "integer",
              "minimum": -9223372036854780000,
              "maximum": 9223372036854780000
          },
          "cost": {
              "type": "number"
          },
          "originalScore": {
              "type": [
                  "number",
                  "null"
              ]
          },
          "rerankerScore": {
              "type": [
                  "number",
                  "null"
              ]
          },
          "finalScore": {
              "type": [
                  "number",
                  "null"
              ]
          },
          "rerankerName": {
              "type": [
                  "string",
                  "null"
              ]
          },
          "results": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "documentId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "UUID/GUID string"
                      },
                      "documentName": {
                          "type": [
                              "string",
                              "null"
                          ]
                      },
                      "contentsPreview": {
                          "type": [
                              "string",
                              "null"
                          ]
                      },
                      "originalScore": {
                          "type": [
                              "number",
                              "null"
                          ]
                      },
                      "rerankerScore": {
                          "type": [
                              "number",
                              "null"
                          ]
                      },
                      "score": {
                          "type": "number"
                      }
                  },
                  "description": "Document result returned inside a RAG transaction detail payload."
              }
          }
      },
      "description": "Detail returned for one collection RAG transaction."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection that contains the documents.

Query parameters:

• filterstring

  Plain text search across name, reference, contents and tags, or command syntax such as -t tag -n name -r reference -c content -i id.

• order_bystring

  Sort order: created_at_asce, created_at_desc, updated_at_asce, updated_at_desc, indexed_at_asce or indexed_at_desc.

• statestring

  Indexing state filter. Accepted values: queued or indexed.

Responses:

• 200
  ExampleSchema

  [
      {
          // The unique identifier of the document.
          "id": "uuid",
  
          // The date and time when the document was last updated.
          "updatedAt": "date-time",
  
          // The name of the document.
          "name": string,
  
          // Nullable. The external reference ID of the document.
          "reference": string?,
  
          // The tags associated with the document.
          "tags": [
              string,
              ...
          ],
  
          // Short preview of the document text.
          "contentsPreview": string,
  
          // The current indexing state of the document.
          "indexState": "Queued"
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "The unique identifier of the document."
              },
              "updatedAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The date and time when the document was last updated."
              },
              "name": {
                  "type": "string",
                  "description": "The name of the document."
              },
              "reference": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "The external reference ID of the document."
              },
              "tags": {
                  "type": "array",
                  "items": {
                      "type": "string"
                  },
                  "description": "The tags associated with the document."
              },
              "contentsPreview": {
                  "type": "string",
                  "description": "Short preview of the document text."
              },
              "indexState": {
                  "type": "string",
                  "enum": [
                      "Queued",
                      "Cancelled",
                      "Indexed"
                  ],
                  "description": "The current indexing state of the document."
              }
          },
          "description": "Document summary returned by the browse endpoint."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection that will receive the documents.

Request parameters:

• documentsfile

  JSONL file containing one document object per line.

• insert-modestring

  Set to sync to delete collection documents whose names are not present in the uploaded JSONL file.

Request examples:

• Multipart form data with a documents file. Each JSONL line must contain docId and text, and may contain __ref, __tags and __meta.

Responses:

• 200
  ExampleSchema

  {
      // Number of new or changed documents accepted for indexing.
      "enqueued": number,
  
      // Number of input documents ignored because their stored content and metadata did not change.
      "skipped": number
  }

  {
      "type": "object",
      "properties": {
          "enqueued": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "Number of new or changed documents accepted for indexing."
          },
          "skipped": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "Number of input documents ignored because their stored content and metadata did not change."
          }
      },
      "description": "Counts returned after a document import request is accepted."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection that contains or will receive the document.

Request examples:

• Document data. The schema type documents the available fields. For existing documents, send name and only the fields to change.

  ExampleSchema

  {
      // Document text. Required when creating a new document; optional when updating an existing document.
      "contents": string,
  
      // Document name used as the upsert key within the collection.
      "name": string,
  
      // Nullable. Optional external reference, such as a source URL, file path or application record id.
      "reference": string?,
  
      // Nullable. Optional tags used for filtering and grouping documents.
      "tags": [
          string,
          ...
      ]?,
  
      // Nullable. Optional JSON metadata. For existing documents, supplied objects are shallow-merged with current metadata.
      "metadata": {}?
  }

  {
      "type": "object",
      "additionalProperties": false,
      "required": [ "name" ],
      "properties": {
          "name": { "type": "string" },
          "contents": {
              "type": "string",
              "description": "Required when creating a missing document. Optional for existing documents."
          },
          "reference": { "type": [ "string", "null" ] },
          "tags": {
              "type": [ "array", "null" ],
              "items": { "type": "string" }
          },
          "metadata": {
              "type": [ "object", "null" ],
              "description": "Partial metadata object. When supplied for an existing document, it is shallow-merged with current metadata."
          }
      }
  }

Responses:

• 200
  ExampleSchema

  {
      // The unique identifier of the document.
      "documentId": "uuid",
  
      // Operation result: Created, Modified or NotModified.
      "state": string
  }

  {
      "type": "object",
      "properties": {
          "documentId": {
              "type": "string",
              "format": "uuid",
              "description": "The unique identifier of the document."
          },
          "state": {
              "type": "string",
              "description": "Operation result: Created, Modified or NotModified."
          }
      },
      "description": "Result returned after creating or updating a document."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection that contains the document.

• document-iduuid

  Identifier of the document to retrieve.

Responses:

• 200
  ExampleSchema

  {
      // The unique identifier of the document.
      "id": "uuid",
  
      // The name of the document.
      "name": string,
  
      // The indexing state of the document.
      "state": "Queued",
  
      // The full text content of the document.
      "contents": string,
  
      // Nullable. The external reference ID of the document.
      "reference": string?,
  
      // The tags associated with the document.
      "tags": [
          string,
          ...
      ],
  
      // The date and time when the document was created.
      "createdAt": "date-time",
  
      // The date and time when the document was last updated.
      "updatedAt": "date-time",
  
      // Nullable. The date and time when the document was last indexed.
      "indexedAt": "date-time"?,
  
      // The total number of characters in the content.
      "characterCount": number,
  
      // The total number of words in the content.
      "wordCount": number,
  
      // Estimated token count based on document length.
      "approximateTokenCount": number,
  
      // A JSON object containing additional metadata for the document.
      "metadata": {}
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "string",
              "format": "uuid",
              "description": "The unique identifier of the document."
          },
          "name": {
              "type": "string",
              "description": "The name of the document."
          },
          "state": {
              "type": "string",
              "enum": [
                  "Queued",
                  "Cancelled",
                  "Indexed"
              ],
              "description": "The indexing state of the document."
          },
          "contents": {
              "type": "string",
              "description": "The full text content of the document."
          },
          "reference": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "The external reference ID of the document."
          },
          "tags": {
              "type": "array",
              "items": {
                  "type": "string"
              },
              "description": "The tags associated with the document."
          },
          "createdAt": {
              "type": "string",
              "format": "date-time",
              "description": "The date and time when the document was created."
          },
          "updatedAt": {
              "type": "string",
              "format": "date-time",
              "description": "The date and time when the document was last updated."
          },
          "indexedAt": {
              "format": "date-time",
              "description": "The date and time when the document was last indexed.",
              "type": [
                  "string",
                  "null"
              ]
          },
          "characterCount": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "The total number of characters in the content."
          },
          "wordCount": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "The total number of words in the content."
          },
          "approximateTokenCount": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "Estimated token count based on document length."
          },
          "metadata": {
              "type": "object",
              "description": "A JSON object containing additional metadata for the document."
          }
      },
      "description": "Full document record returned by the document detail endpoint."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• collection-iduuid

  Identifier of the collection that contains the document.

• document-iduuid

  Identifier of the document to delete.

Responses:

• 200

  The document was removed.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• filterstring

  Optional search over job id or title.

Responses:

• 200
  ExampleSchema

  [
      {
          // Job identifier.
          "id": "uuid",
  
          // Workflow identifier that owns this job.
          "parentBatchWorkflowId": "uuid",
  
          // Nullable. Title of the parent workflow, when available.
          "workflowTitle": string?,
  
          // Nullable. Job title, when set.
          "title": string?,
  
          // Date and time when the job was created.
          "createdAt": "date-time",
  
          // Current job processing state.
          "state": "Active",
  
          // Nullable. Date and time when the job was last restarted or resumed.
          "restartedAt": "date-time"?,
  
          // Number of items waiting to be processed.
          "pending": number,
  
          // Number of items processed successfully.
          "finished": number,
  
          // Number of items refused by validation or policy.
          "refused": number,
  
          // Number of items that failed during execution.
          "executionErrors": number,
  
          // Number of items whose output failed validation.
          "validationErrors": number,
  
          // Number of cancelled items.
          "cancelled": number,
  
          // Number of items currently marked as running.
          "running": number,
  
          // Total recorded cost for processed items.
          "totalCost": number,
  
          // Nullable. Average confidence for items with a confidence score.
          "averageConfidence": number?,
  
          // Finished-item share among completed items.
          "successRate": number,
  
          // Refused-item share among completed items.
          "refusalRate": number,
  
          // Number of job timeline events.
          "eventCount": number,
  
          // Number of items that ended in refusal, execution error or validation error states.
          "failed": number,
  
          // Number of items no longer pending or running.
          "completed": number,
  
          // Total number of items represented by this summary.
          "total": number
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Job identifier."
              },
              "parentBatchWorkflowId": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Workflow identifier that owns this job."
              },
              "workflowTitle": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "Title of the parent workflow, when available."
              },
              "title": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "Job title, when set."
              },
              "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Date and time when the job was created."
              },
              "state": {
                  "type": "string",
                  "enum": [
                      "Active",
                      "Paused",
                      "Finished"
                  ],
                  "description": "Current job processing state."
              },
              "restartedAt": {
                  "format": "date-time",
                  "description": "Date and time when the job was last restarted or resumed.",
                  "type": [
                      "string",
                      "null"
                  ]
              },
              "pending": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items waiting to be processed."
              },
              "finished": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items processed successfully."
              },
              "refused": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items refused by validation or policy."
              },
              "executionErrors": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items that failed during execution."
              },
              "validationErrors": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items whose output failed validation."
              },
              "cancelled": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of cancelled items."
              },
              "running": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items currently marked as running."
              },
              "totalCost": {
                  "type": "number",
                  "description": "Total recorded cost for processed items."
              },
              "averageConfidence": {
                  "type": [
                      "number",
                      "null"
                  ],
                  "description": "Average confidence for items with a confidence score."
              },
              "successRate": {
                  "type": "number",
                  "description": "Finished-item share among completed items."
              },
              "refusalRate": {
                  "type": "number",
                  "description": "Refused-item share among completed items."
              },
              "eventCount": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of job timeline events."
              },
              "failed": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items that ended in refusal, execution error or validation error states."
              },
              "completed": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items no longer pending or running."
              },
              "total": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Total number of items represented by this summary."
              }
          },
          "description": "Summarizes a batch job with item counts, cost, confidence and completion metrics."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• filterstring

  Optional search over workflow id, title, model name or instruction text.

Responses:

• 200
  ExampleSchema

  [
      {
          // Unique workflow identifier.
          "id": "uuid",
  
          // Timestamp when the workflow was created.
          "createdAt": "date-time",
  
          // Timestamp when the workflow was last changed.
          "updatedAt": "date-time",
  
          // Nullable. Optional workflow title.
          "title": string?,
  
          // Model or gateway slug used to process workflow items.
          "modelName": string,
  
          // Whether the workflow validates item outputs after generation.
          "validationEnabled": boolean,
  
          // Number of jobs created under this workflow.
          "jobCount": number
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Unique workflow identifier."
              },
              "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Timestamp when the workflow was created."
              },
              "updatedAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Timestamp when the workflow was last changed."
              },
              "title": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "Optional workflow title."
              },
              "modelName": {
                  "type": "string",
                  "description": "Model or gateway slug used to process workflow items."
              },
              "validationEnabled": {
                  "type": "boolean",
                  "description": "Whether the workflow validates item outputs after generation."
              },
              "jobCount": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of jobs created under this workflow."
              }
          },
          "description": "Batch workflow summary returned by the listing endpoint."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Workflow creation JSON object. Required fields are instruction, resultSchema and modelName; title and validation settings are optional.

Responses:

• 200
  ExampleSchema

  {
      // Unique identifier of the created workflow.
      "id": "uuid"
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier of the created workflow."
          }
      },
      "description": "Result returned after creating a batch workflow."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the workflow to retrieve.

Responses:

• 200
  ExampleSchema

  {
      // Unique workflow identifier.
      "id": "uuid",
  
      // Timestamp when the workflow was created.
      "createdAt": "date-time",
  
      // Timestamp when the workflow was last changed.
      "updatedAt": "date-time",
  
      // Nullable. Optional workflow title.
      "title": string?,
  
      // Generation, validation, model and retry settings used by jobs in this workflow.
      "options": {
          // Required. System instruction applied to every item processed by the workflow.
          "instruction": string,
  
          // Required. JSON schema that every successful item output must satisfy.
          "resultSchema": any,
  
          // Nullable. Optional instruction used to validate or judge each generated output.
          "validationInstruction": string?,
  
          // Built-in tool configuration available while processing workflow items.
          "enabledTools": {
              // Built-in function flags enabled during item processing.
              "enabledFunctions": [
                  "WebSearch",
                  ...
              ],
  
              // Runtime options for enabled built-in functions.
              "options": {
                  // Level of detail returned by built-in web search tools.
                  "webSearchMode": "Full",
  
                  // Maximum number of search results returned by built-in web search tools.
                  "webSearchMaxResults": number,
  
                  // Maximum number of images the built-in image generation tool may create in one call.
                  "imageGenerationMaxResults": number,
  
                  // Quality level used by the built-in image generation tool.
                  "imageGenerationQuality": "Low",
  
                  // Allows the built-in image generation tool to produce mature content when the selected model and policy allow it.
                  "imageGenerationAllowMatureContent": boolean,
  
                  // Allows the built-in image generation tool to use reference images from web results or user uploads.
                  "imageGenerationAllowReferenceUsage": boolean,
  
                  // Nullable. Optional image-generation model name. When omitted, AIVAX uses its default image model.
                  "imageGenerationModelName": string?,
  
                  // Includes all available memory context in system instructions instead of only memory selected by the runtime.
                  "includeAllMemoryContext": boolean,
  
                  // Allows this gateway to consume memories created by other gateways.
                  "allowSharedMemory": boolean
              }
          },
  
          // Required. Model or gateway name used to process workflow items.
          "modelName": string,
  
          // Nullable. Optional reasoning-effort value passed to compatible reasoning models.
          "reasoningEffort": string?,
  
          // Number of item errors that can stop job processing.
          "errorStopThreshold": number,
  
          // Maximum retry attempts for an item that fails processing or validation.
          "maxRetries": number
      }
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "string",
              "format": "uuid",
              "description": "Unique workflow identifier."
          },
          "createdAt": {
              "type": "string",
              "format": "date-time",
              "description": "Timestamp when the workflow was created."
          },
          "updatedAt": {
              "type": "string",
              "format": "date-time",
              "description": "Timestamp when the workflow was last changed."
          },
          "title": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Optional workflow title."
          },
          "options": {
              "type": "object",
              "properties": {
                  "instruction": {
                      "type": "string",
                      "description": "System instruction applied to every item processed by the workflow."
                  },
                  "resultSchema": {
                      "description": "JSON schema that every successful item output must satisfy."
                  },
                  "validationInstruction": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional instruction used to validate or judge each generated output."
                  },
                  "enabledTools": {
                      "type": "object",
                      "properties": {
                          "enabledFunctions": {
                              "type": "array",
                              "items": {
                                  "type": "string",
                                  "enum": [
                                      "WebSearch",
                                      "Code",
                                      "OpenUrl",
                                      "Remember",
                                      "ImageGeneration",
                                      "XPostsSearch",
                                      "GenerateDocument",
                                      "GenerateWebPage",
                                      "AdvancedWebUsage",
                                      "Request",
                                      "Calendar"
                                  ]
                              },
                              "description": "Built-in function flags enabled during item processing."
                          },
                          "options": {
                              "type": "object",
                              "properties": {
                                  "webSearchMode": {
                                      "type": "string",
                                      "enum": [
                                          "Full",
                                          "Summarized"
                                      ],
                                      "description": "Level of detail returned by built-in web search tools."
                                  },
                                  "webSearchMaxResults": {
                                      "type": "integer",
                                      "minimum": -2147483648,
                                      "maximum": 2147483647,
                                      "description": "Maximum number of search results returned by built-in web search tools."
                                  },
                                  "imageGenerationMaxResults": {
                                      "type": "integer",
                                      "minimum": -2147483648,
                                      "maximum": 2147483647,
                                      "description": "Maximum number of images the built-in image generation tool may create in one call."
                                  },
                                  "imageGenerationQuality": {
                                      "type": "string",
                                      "enum": [
                                          "Low",
                                          "Medium",
                                          "High",
                                          "Highest"
                                      ],
                                      "description": "Quality level used by the built-in image generation tool."
                                  },
                                  "imageGenerationAllowMatureContent": {
                                      "type": "boolean",
                                      "description": "Allows the built-in image generation tool to produce mature content when the selected model and policy allow it."
                                  },
                                  "imageGenerationAllowReferenceUsage": {
                                      "type": "boolean",
                                      "description": "Allows the built-in image generation tool to use reference images from web results or user uploads."
                                  },
                                  "imageGenerationModelName": {
                                      "type": [
                                          "string",
                                          "null"
                                      ],
                                      "description": "Optional image-generation model name. When omitted, AIVAX uses its default image model."
                                  },
                                  "includeAllMemoryContext": {
                                      "type": "boolean",
                                      "description": "Includes all available memory context in system instructions instead of only memory selected by the runtime."
                                  },
                                  "allowSharedMemory": {
                                      "type": "boolean",
                                      "description": "Allows this gateway to consume memories created by other gateways."
                                  }
                              },
                              "description": "Runtime options for enabled built-in functions."
                          }
                      },
                      "description": "Built-in tool configuration available while processing workflow items."
                  },
                  "modelName": {
                      "type": "string",
                      "description": "Model or gateway name used to process workflow items."
                  },
                  "reasoningEffort": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional reasoning-effort value passed to compatible reasoning models."
                  },
                  "errorStopThreshold": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of item errors that can stop job processing."
                  },
                  "maxRetries": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Maximum retry attempts for an item that fails processing or validation."
                  }
              },
              "required": [
                  "instruction",
                  "resultSchema",
                  "modelName"
              ],
              "description": "Generation, validation, model and retry settings used by jobs in this workflow."
          }
      },
      "description": "Full batch workflow configuration."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the workflow to update.

Request examples:

• Partial workflow JSON object. Send title, instruction, resultSchema, validationInstruction, enabledTools, modelName, reasoningEffort, errorStopThreshold and/or maxRetries.

  {
      "type": "object",
      "additionalProperties": false,
      "properties": {
          "title": { "type": [ "string", "null" ] },
          "instruction": { "type": "string" },
          "resultSchema": {
              "type": "object",
              "description": "JSON schema object for workflow results."
          },
          "validationInstruction": { "type": [ "string", "null" ] },
          "enabledTools": {
              "type": "object",
              "description": "Partial enabled tools object. This is shallow-merged with current enabled tools."
          },
          "modelName": { "type": "string" },
          "reasoningEffort": { "type": [ "string", "null" ] },
          "errorStopThreshold": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
          },
          "maxRetries": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10
          }
      }
  }

Responses:

• 200
  ExampleSchema

  {
      // Unique workflow identifier.
      "id": "uuid",
  
      // Timestamp when the workflow was created.
      "createdAt": "date-time",
  
      // Timestamp when the workflow was last changed.
      "updatedAt": "date-time",
  
      // Nullable. Optional workflow title.
      "title": string?,
  
      // Generation, validation, model and retry settings used by jobs in this workflow.
      "options": {
          // Required. System instruction applied to every item processed by the workflow.
          "instruction": string,
  
          // Required. JSON schema that every successful item output must satisfy.
          "resultSchema": any,
  
          // Nullable. Optional instruction used to validate or judge each generated output.
          "validationInstruction": string?,
  
          // Built-in tool configuration available while processing workflow items.
          "enabledTools": {
              // Built-in function flags enabled during item processing.
              "enabledFunctions": [
                  "WebSearch",
                  ...
              ],
  
              // Runtime options for enabled built-in functions.
              "options": {
                  // Level of detail returned by built-in web search tools.
                  "webSearchMode": "Full",
  
                  // Maximum number of search results returned by built-in web search tools.
                  "webSearchMaxResults": number,
  
                  // Maximum number of images the built-in image generation tool may create in one call.
                  "imageGenerationMaxResults": number,
  
                  // Quality level used by the built-in image generation tool.
                  "imageGenerationQuality": "Low",
  
                  // Allows the built-in image generation tool to produce mature content when the selected model and policy allow it.
                  "imageGenerationAllowMatureContent": boolean,
  
                  // Allows the built-in image generation tool to use reference images from web results or user uploads.
                  "imageGenerationAllowReferenceUsage": boolean,
  
                  // Nullable. Optional image-generation model name. When omitted, AIVAX uses its default image model.
                  "imageGenerationModelName": string?,
  
                  // Includes all available memory context in system instructions instead of only memory selected by the runtime.
                  "includeAllMemoryContext": boolean,
  
                  // Allows this gateway to consume memories created by other gateways.
                  "allowSharedMemory": boolean
              }
          },
  
          // Required. Model or gateway name used to process workflow items.
          "modelName": string,
  
          // Nullable. Optional reasoning-effort value passed to compatible reasoning models.
          "reasoningEffort": string?,
  
          // Number of item errors that can stop job processing.
          "errorStopThreshold": number,
  
          // Maximum retry attempts for an item that fails processing or validation.
          "maxRetries": number
      }
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "string",
              "format": "uuid",
              "description": "Unique workflow identifier."
          },
          "createdAt": {
              "type": "string",
              "format": "date-time",
              "description": "Timestamp when the workflow was created."
          },
          "updatedAt": {
              "type": "string",
              "format": "date-time",
              "description": "Timestamp when the workflow was last changed."
          },
          "title": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Optional workflow title."
          },
          "options": {
              "type": "object",
              "properties": {
                  "instruction": {
                      "type": "string",
                      "description": "System instruction applied to every item processed by the workflow."
                  },
                  "resultSchema": {
                      "description": "JSON schema that every successful item output must satisfy."
                  },
                  "validationInstruction": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional instruction used to validate or judge each generated output."
                  },
                  "enabledTools": {
                      "type": "object",
                      "properties": {
                          "enabledFunctions": {
                              "type": "array",
                              "items": {
                                  "type": "string",
                                  "enum": [
                                      "WebSearch",
                                      "Code",
                                      "OpenUrl",
                                      "Remember",
                                      "ImageGeneration",
                                      "XPostsSearch",
                                      "GenerateDocument",
                                      "GenerateWebPage",
                                      "AdvancedWebUsage",
                                      "Request",
                                      "Calendar"
                                  ]
                              },
                              "description": "Built-in function flags enabled during item processing."
                          },
                          "options": {
                              "type": "object",
                              "properties": {
                                  "webSearchMode": {
                                      "type": "string",
                                      "enum": [
                                          "Full",
                                          "Summarized"
                                      ],
                                      "description": "Level of detail returned by built-in web search tools."
                                  },
                                  "webSearchMaxResults": {
                                      "type": "integer",
                                      "minimum": -2147483648,
                                      "maximum": 2147483647,
                                      "description": "Maximum number of search results returned by built-in web search tools."
                                  },
                                  "imageGenerationMaxResults": {
                                      "type": "integer",
                                      "minimum": -2147483648,
                                      "maximum": 2147483647,
                                      "description": "Maximum number of images the built-in image generation tool may create in one call."
                                  },
                                  "imageGenerationQuality": {
                                      "type": "string",
                                      "enum": [
                                          "Low",
                                          "Medium",
                                          "High",
                                          "Highest"
                                      ],
                                      "description": "Quality level used by the built-in image generation tool."
                                  },
                                  "imageGenerationAllowMatureContent": {
                                      "type": "boolean",
                                      "description": "Allows the built-in image generation tool to produce mature content when the selected model and policy allow it."
                                  },
                                  "imageGenerationAllowReferenceUsage": {
                                      "type": "boolean",
                                      "description": "Allows the built-in image generation tool to use reference images from web results or user uploads."
                                  },
                                  "imageGenerationModelName": {
                                      "type": [
                                          "string",
                                          "null"
                                      ],
                                      "description": "Optional image-generation model name. When omitted, AIVAX uses its default image model."
                                  },
                                  "includeAllMemoryContext": {
                                      "type": "boolean",
                                      "description": "Includes all available memory context in system instructions instead of only memory selected by the runtime."
                                  },
                                  "allowSharedMemory": {
                                      "type": "boolean",
                                      "description": "Allows this gateway to consume memories created by other gateways."
                                  }
                              },
                              "description": "Runtime options for enabled built-in functions."
                          }
                      },
                      "description": "Built-in tool configuration available while processing workflow items."
                  },
                  "modelName": {
                      "type": "string",
                      "description": "Model or gateway name used to process workflow items."
                  },
                  "reasoningEffort": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional reasoning-effort value passed to compatible reasoning models."
                  },
                  "errorStopThreshold": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of item errors that can stop job processing."
                  },
                  "maxRetries": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Maximum retry attempts for an item that fails processing or validation."
                  }
              },
              "required": [
                  "instruction",
                  "resultSchema",
                  "modelName"
              ],
              "description": "Generation, validation, model and retry settings used by jobs in this workflow."
          }
      },
      "description": "Full batch workflow configuration."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the workflow to delete.

Responses:

• 200

  The batch workflow and its jobs were deleted.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

Query parameters:

• filterstring

  Optional search over job id or title.

Responses:

• 200
  ExampleSchema

  [
      {
          // Job identifier.
          "id": "uuid",
  
          // Workflow identifier that owns this job.
          "parentBatchWorkflowId": "uuid",
  
          // Nullable. Title of the parent workflow, when available.
          "workflowTitle": string?,
  
          // Nullable. Job title, when set.
          "title": string?,
  
          // Date and time when the job was created.
          "createdAt": "date-time",
  
          // Current job processing state.
          "state": "Active",
  
          // Nullable. Date and time when the job was last restarted or resumed.
          "restartedAt": "date-time"?,
  
          // Number of items waiting to be processed.
          "pending": number,
  
          // Number of items processed successfully.
          "finished": number,
  
          // Number of items refused by validation or policy.
          "refused": number,
  
          // Number of items that failed during execution.
          "executionErrors": number,
  
          // Number of items whose output failed validation.
          "validationErrors": number,
  
          // Number of cancelled items.
          "cancelled": number,
  
          // Number of items currently marked as running.
          "running": number,
  
          // Total recorded cost for processed items.
          "totalCost": number,
  
          // Nullable. Average confidence for items with a confidence score.
          "averageConfidence": number?,
  
          // Finished-item share among completed items.
          "successRate": number,
  
          // Refused-item share among completed items.
          "refusalRate": number,
  
          // Number of job timeline events.
          "eventCount": number,
  
          // Number of items that ended in refusal, execution error or validation error states.
          "failed": number,
  
          // Number of items no longer pending or running.
          "completed": number,
  
          // Total number of items represented by this summary.
          "total": number
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Job identifier."
              },
              "parentBatchWorkflowId": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Workflow identifier that owns this job."
              },
              "workflowTitle": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "Title of the parent workflow, when available."
              },
              "title": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "Job title, when set."
              },
              "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Date and time when the job was created."
              },
              "state": {
                  "type": "string",
                  "enum": [
                      "Active",
                      "Paused",
                      "Finished"
                  ],
                  "description": "Current job processing state."
              },
              "restartedAt": {
                  "format": "date-time",
                  "description": "Date and time when the job was last restarted or resumed.",
                  "type": [
                      "string",
                      "null"
                  ]
              },
              "pending": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items waiting to be processed."
              },
              "finished": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items processed successfully."
              },
              "refused": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items refused by validation or policy."
              },
              "executionErrors": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items that failed during execution."
              },
              "validationErrors": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items whose output failed validation."
              },
              "cancelled": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of cancelled items."
              },
              "running": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items currently marked as running."
              },
              "totalCost": {
                  "type": "number",
                  "description": "Total recorded cost for processed items."
              },
              "averageConfidence": {
                  "type": [
                      "number",
                      "null"
                  ],
                  "description": "Average confidence for items with a confidence score."
              },
              "successRate": {
                  "type": "number",
                  "description": "Finished-item share among completed items."
              },
              "refusalRate": {
                  "type": "number",
                  "description": "Refused-item share among completed items."
              },
              "eventCount": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of job timeline events."
              },
              "failed": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items that ended in refusal, execution error or validation error states."
              },
              "completed": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Number of items no longer pending or running."
              },
              "total": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Total number of items represented by this summary."
              }
          },
          "description": "Summarizes a batch job with item counts, cost, confidence and completion metrics."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

Request examples:

• Optional JSON object with a title field.

Responses:

• 200
  ExampleSchema

  {
      // Unique identifier of the created job.
      "id": "uuid"
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier of the created job."
          }
      },
      "description": "Result returned after creating a batch job."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the batch job to retrieve.

Responses:

• 200
  ExampleSchema

  {
      // Stored batch job record.
      "job": {
          // Job identifier used by batch job and item endpoints.
          "id": "uuid",
  
          // Date and time when the job was created.
          "createdAt": "date-time",
  
          // Current processing state for this job.
          "state": "Active",
  
          // Nullable. Date and time when the job was last restarted or resumed.
          "restartedAt": "date-time"?,
  
          // Nullable. Optional caller-facing job title.
          "title": string?,
  
          // Required. Workflow identifier whose options are used by this job.
          "parentBatchWorkflowId": "uuid",
  
          // Timeline of job-level events, such as creation, pause, resume or completion.
          "updates": [
              {
                  // Date and time when the event was recorded.
                  "moment": "date-time",
  
                  // Required. Short machine-readable event type.
                  "eventType": string,
  
                  // Required. Human-readable event description.
                  "description": string
              },
              ...
          ]
      },
  
      // Aggregated item counts and job status.
      "summary": {
          // Job identifier.
          "id": "uuid",
  
          // Workflow identifier that owns this job.
          "parentBatchWorkflowId": "uuid",
  
          // Nullable. Title of the parent workflow, when available.
          "workflowTitle": string?,
  
          // Nullable. Job title, when set.
          "title": string?,
  
          // Date and time when the job was created.
          "createdAt": "date-time",
  
          // Current job processing state.
          "state": "Active",
  
          // Nullable. Date and time when the job was last restarted or resumed.
          "restartedAt": "date-time"?,
  
          // Number of items waiting to be processed.
          "pending": number,
  
          // Number of items processed successfully.
          "finished": number,
  
          // Number of items refused by validation or policy.
          "refused": number,
  
          // Number of items that failed during execution.
          "executionErrors": number,
  
          // Number of items whose output failed validation.
          "validationErrors": number,
  
          // Number of cancelled items.
          "cancelled": number,
  
          // Number of items currently marked as running.
          "running": number,
  
          // Total recorded cost for processed items.
          "totalCost": number,
  
          // Nullable. Average confidence for items with a confidence score.
          "averageConfidence": number?,
  
          // Finished-item share among completed items.
          "successRate": number,
  
          // Refused-item share among completed items.
          "refusalRate": number,
  
          // Number of job timeline events.
          "eventCount": number,
  
          // Number of items that ended in refusal, execution error or validation error states.
          "failed": number,
  
          // Number of items no longer pending or running.
          "completed": number,
  
          // Total number of items represented by this summary.
          "total": number
      },
  
      // Timeline points describing job progress.
      "progression": [
          {
              // Time bucket represented by this point.
              "moment": "date-time",
  
              // Number of items finished by this point.
              "finished": number,
  
              // Number of items failed by this point.
              "failed": number,
  
              // Nullable. Average confidence recorded by this point.
              "averageConfidence": number?,
  
              // Refusal rate recorded by this point.
              "refusalRate": number
          },
          ...
      ],
  
      // Most recent processed items for quick inspection.
      "latestItems": [
          {
              // Item identifier used by batch item endpoints.
              "id": "uuid",
  
              // Required. Job identifier that owns and processes this item.
              "parentBatchWorkflowJobId": "uuid",
  
              // Date and time when the item was inserted.
              "insertedAt": "date-time",
  
              // Nullable. Date and time when processing finished, failed or was refused.
              "processedAt": "date-time"?,
  
              // Current processing state for this item.
              "state": "Pending",
  
              // Processing priority; lower values are processed before higher values.
              "priority": number,
  
              // Required. Raw item input sent to the workflow model.
              "input": string,
  
              // Nullable. Raw item output produced by the workflow model.
              "output": string?,
  
              // Nullable. Validation result for the item output, when validation was configured or performed.
              "validationResult": {
                  // Whether the output passed validation.
                  "passed": boolean,
  
                  // Nullable. Explanation for the validation result.
                  "reason": string?
              }?,
  
              // Nullable. Optional confidence score assigned to the item output.
              "confidence": number?,
  
              // Nullable. Total estimated or recorded cost for processing this item.
              "totalCost": number?
          },
          ...
      ]
  }

  {
      "type": "object",
      "properties": {
          "job": {
              "type": "object",
              "properties": {
                  "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Job identifier used by batch job and item endpoints."
                  },
                  "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Date and time when the job was created."
                  },
                  "state": {
                      "type": "string",
                      "enum": [
                          "Active",
                          "Paused",
                          "Finished"
                      ],
                      "description": "Current processing state for this job."
                  },
                  "restartedAt": {
                      "format": "date-time",
                      "description": "Date and time when the job was last restarted or resumed.",
                      "type": [
                          "string",
                          "null"
                      ]
                  },
                  "title": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional caller-facing job title."
                  },
                  "parentBatchWorkflowId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Workflow identifier whose options are used by this job."
                  },
                  "updates": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "moment": {
                                  "type": "string",
                                  "format": "date-time",
                                  "description": "Date and time when the event was recorded."
                              },
                              "eventType": {
                                  "type": "string",
                                  "description": "Short machine-readable event type."
                              },
                              "description": {
                                  "type": "string",
                                  "description": "Human-readable event description."
                              }
                          },
                          "required": [
                              "eventType",
                              "description"
                          ],
                          "description": "Represents one event in a batch job timeline."
                      },
                      "description": "Timeline of job-level events, such as creation, pause, resume or completion."
                  }
              },
              "required": [
                  "parentBatchWorkflowId"
              ],
              "description": "Stored batch job record."
          },
          "summary": {
              "type": "object",
              "properties": {
                  "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Job identifier."
                  },
                  "parentBatchWorkflowId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Workflow identifier that owns this job."
                  },
                  "workflowTitle": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Title of the parent workflow, when available."
                  },
                  "title": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Job title, when set."
                  },
                  "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Date and time when the job was created."
                  },
                  "state": {
                      "type": "string",
                      "enum": [
                          "Active",
                          "Paused",
                          "Finished"
                      ],
                      "description": "Current job processing state."
                  },
                  "restartedAt": {
                      "format": "date-time",
                      "description": "Date and time when the job was last restarted or resumed.",
                      "type": [
                          "string",
                          "null"
                      ]
                  },
                  "pending": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items waiting to be processed."
                  },
                  "finished": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items processed successfully."
                  },
                  "refused": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items refused by validation or policy."
                  },
                  "executionErrors": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items that failed during execution."
                  },
                  "validationErrors": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items whose output failed validation."
                  },
                  "cancelled": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of cancelled items."
                  },
                  "running": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items currently marked as running."
                  },
                  "totalCost": {
                      "type": "number",
                      "description": "Total recorded cost for processed items."
                  },
                  "averageConfidence": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Average confidence for items with a confidence score."
                  },
                  "successRate": {
                      "type": "number",
                      "description": "Finished-item share among completed items."
                  },
                  "refusalRate": {
                      "type": "number",
                      "description": "Refused-item share among completed items."
                  },
                  "eventCount": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of job timeline events."
                  },
                  "failed": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items that ended in refusal, execution error or validation error states."
                  },
                  "completed": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items no longer pending or running."
                  },
                  "total": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Total number of items represented by this summary."
                  }
              },
              "description": "Aggregated item counts and job status."
          },
          "progression": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "moment": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Time bucket represented by this point."
                      },
                      "finished": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Number of items finished by this point."
                      },
                      "failed": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Number of items failed by this point."
                      },
                      "averageConfidence": {
                          "type": [
                              "number",
                              "null"
                          ],
                          "description": "Average confidence recorded by this point."
                      },
                      "refusalRate": {
                          "type": "number",
                          "description": "Refusal rate recorded by this point."
                      }
                  },
                  "description": "Represents one point in a batch job progress chart."
              },
              "description": "Timeline points describing job progress."
          },
          "latestItems": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Item identifier used by batch item endpoints."
                      },
                      "parentBatchWorkflowJobId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Job identifier that owns and processes this item."
                      },
                      "insertedAt": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Date and time when the item was inserted."
                      },
                      "processedAt": {
                          "format": "date-time",
                          "description": "Date and time when processing finished, failed or was refused.",
                          "type": [
                              "string",
                              "null"
                          ]
                      },
                      "state": {
                          "type": "string",
                          "enum": [
                              "Pending",
                              "Finished",
                              "Refused",
                              "ExecutionError",
                              "ValidationError",
                              "Cancelled"
                          ],
                          "description": "Current processing state for this item."
                      },
                      "priority": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Processing priority; lower values are processed before higher values."
                      },
                      "input": {
                          "type": "string",
                          "description": "Raw item input sent to the workflow model."
                      },
                      "output": {
                          "type": [
                              "string",
                              "null"
                          ],
                          "description": "Raw item output produced by the workflow model."
                      },
                      "validationResult": {
                          "properties": {
                              "passed": {
                                  "type": "boolean",
                                  "description": "Whether the output passed validation."
                              },
                              "reason": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Explanation for the validation result."
                              }
                          },
                          "description": "Validation result for the item output, when validation was configured or performed.",
                          "type": [
                              "object",
                              "null"
                          ]
                      },
                      "confidence": {
                          "type": [
                              "number",
                              "null"
                          ],
                          "description": "Optional confidence score assigned to the item output."
                      },
                      "totalCost": {
                          "type": [
                              "number",
                              "null"
                          ],
                          "description": "Total estimated or recorded cost for processing this item."
                      }
                  },
                  "required": [
                      "parentBatchWorkflowJobId",
                      "input"
                  ],
                  "description": "Represents one input item queued for a batch workflow job."
              },
              "description": "Most recent processed items for quick inspection."
          }
      },
      "description": "Full batch job view with status, progression and recent processed items."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the batch job to update.

Request examples:

• Partial job update JSON object. Send title and/or state.

Responses:

• 200
  ExampleSchema

  {
      // Stored batch job record.
      "job": {
          // Job identifier used by batch job and item endpoints.
          "id": "uuid",
  
          // Date and time when the job was created.
          "createdAt": "date-time",
  
          // Current processing state for this job.
          "state": "Active",
  
          // Nullable. Date and time when the job was last restarted or resumed.
          "restartedAt": "date-time"?,
  
          // Nullable. Optional caller-facing job title.
          "title": string?,
  
          // Required. Workflow identifier whose options are used by this job.
          "parentBatchWorkflowId": "uuid",
  
          // Timeline of job-level events, such as creation, pause, resume or completion.
          "updates": [
              {
                  // Date and time when the event was recorded.
                  "moment": "date-time",
  
                  // Required. Short machine-readable event type.
                  "eventType": string,
  
                  // Required. Human-readable event description.
                  "description": string
              },
              ...
          ]
      },
  
      // Aggregated item counts and job status.
      "summary": {
          // Job identifier.
          "id": "uuid",
  
          // Workflow identifier that owns this job.
          "parentBatchWorkflowId": "uuid",
  
          // Nullable. Title of the parent workflow, when available.
          "workflowTitle": string?,
  
          // Nullable. Job title, when set.
          "title": string?,
  
          // Date and time when the job was created.
          "createdAt": "date-time",
  
          // Current job processing state.
          "state": "Active",
  
          // Nullable. Date and time when the job was last restarted or resumed.
          "restartedAt": "date-time"?,
  
          // Number of items waiting to be processed.
          "pending": number,
  
          // Number of items processed successfully.
          "finished": number,
  
          // Number of items refused by validation or policy.
          "refused": number,
  
          // Number of items that failed during execution.
          "executionErrors": number,
  
          // Number of items whose output failed validation.
          "validationErrors": number,
  
          // Number of cancelled items.
          "cancelled": number,
  
          // Number of items currently marked as running.
          "running": number,
  
          // Total recorded cost for processed items.
          "totalCost": number,
  
          // Nullable. Average confidence for items with a confidence score.
          "averageConfidence": number?,
  
          // Finished-item share among completed items.
          "successRate": number,
  
          // Refused-item share among completed items.
          "refusalRate": number,
  
          // Number of job timeline events.
          "eventCount": number,
  
          // Number of items that ended in refusal, execution error or validation error states.
          "failed": number,
  
          // Number of items no longer pending or running.
          "completed": number,
  
          // Total number of items represented by this summary.
          "total": number
      },
  
      // Timeline points describing job progress.
      "progression": [
          {
              // Time bucket represented by this point.
              "moment": "date-time",
  
              // Number of items finished by this point.
              "finished": number,
  
              // Number of items failed by this point.
              "failed": number,
  
              // Nullable. Average confidence recorded by this point.
              "averageConfidence": number?,
  
              // Refusal rate recorded by this point.
              "refusalRate": number
          },
          ...
      ],
  
      // Most recent processed items for quick inspection.
      "latestItems": [
          {
              // Item identifier used by batch item endpoints.
              "id": "uuid",
  
              // Required. Job identifier that owns and processes this item.
              "parentBatchWorkflowJobId": "uuid",
  
              // Date and time when the item was inserted.
              "insertedAt": "date-time",
  
              // Nullable. Date and time when processing finished, failed or was refused.
              "processedAt": "date-time"?,
  
              // Current processing state for this item.
              "state": "Pending",
  
              // Processing priority; lower values are processed before higher values.
              "priority": number,
  
              // Required. Raw item input sent to the workflow model.
              "input": string,
  
              // Nullable. Raw item output produced by the workflow model.
              "output": string?,
  
              // Nullable. Validation result for the item output, when validation was configured or performed.
              "validationResult": {
                  // Whether the output passed validation.
                  "passed": boolean,
  
                  // Nullable. Explanation for the validation result.
                  "reason": string?
              }?,
  
              // Nullable. Optional confidence score assigned to the item output.
              "confidence": number?,
  
              // Nullable. Total estimated or recorded cost for processing this item.
              "totalCost": number?
          },
          ...
      ]
  }

  {
      "type": "object",
      "properties": {
          "job": {
              "type": "object",
              "properties": {
                  "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Job identifier used by batch job and item endpoints."
                  },
                  "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Date and time when the job was created."
                  },
                  "state": {
                      "type": "string",
                      "enum": [
                          "Active",
                          "Paused",
                          "Finished"
                      ],
                      "description": "Current processing state for this job."
                  },
                  "restartedAt": {
                      "format": "date-time",
                      "description": "Date and time when the job was last restarted or resumed.",
                      "type": [
                          "string",
                          "null"
                      ]
                  },
                  "title": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional caller-facing job title."
                  },
                  "parentBatchWorkflowId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Workflow identifier whose options are used by this job."
                  },
                  "updates": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "moment": {
                                  "type": "string",
                                  "format": "date-time",
                                  "description": "Date and time when the event was recorded."
                              },
                              "eventType": {
                                  "type": "string",
                                  "description": "Short machine-readable event type."
                              },
                              "description": {
                                  "type": "string",
                                  "description": "Human-readable event description."
                              }
                          },
                          "required": [
                              "eventType",
                              "description"
                          ],
                          "description": "Represents one event in a batch job timeline."
                      },
                      "description": "Timeline of job-level events, such as creation, pause, resume or completion."
                  }
              },
              "required": [
                  "parentBatchWorkflowId"
              ],
              "description": "Stored batch job record."
          },
          "summary": {
              "type": "object",
              "properties": {
                  "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Job identifier."
                  },
                  "parentBatchWorkflowId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Workflow identifier that owns this job."
                  },
                  "workflowTitle": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Title of the parent workflow, when available."
                  },
                  "title": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Job title, when set."
                  },
                  "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Date and time when the job was created."
                  },
                  "state": {
                      "type": "string",
                      "enum": [
                          "Active",
                          "Paused",
                          "Finished"
                      ],
                      "description": "Current job processing state."
                  },
                  "restartedAt": {
                      "format": "date-time",
                      "description": "Date and time when the job was last restarted or resumed.",
                      "type": [
                          "string",
                          "null"
                      ]
                  },
                  "pending": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items waiting to be processed."
                  },
                  "finished": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items processed successfully."
                  },
                  "refused": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items refused by validation or policy."
                  },
                  "executionErrors": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items that failed during execution."
                  },
                  "validationErrors": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items whose output failed validation."
                  },
                  "cancelled": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of cancelled items."
                  },
                  "running": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items currently marked as running."
                  },
                  "totalCost": {
                      "type": "number",
                      "description": "Total recorded cost for processed items."
                  },
                  "averageConfidence": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Average confidence for items with a confidence score."
                  },
                  "successRate": {
                      "type": "number",
                      "description": "Finished-item share among completed items."
                  },
                  "refusalRate": {
                      "type": "number",
                      "description": "Refused-item share among completed items."
                  },
                  "eventCount": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of job timeline events."
                  },
                  "failed": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items that ended in refusal, execution error or validation error states."
                  },
                  "completed": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items no longer pending or running."
                  },
                  "total": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Total number of items represented by this summary."
                  }
              },
              "description": "Aggregated item counts and job status."
          },
          "progression": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "moment": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Time bucket represented by this point."
                      },
                      "finished": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Number of items finished by this point."
                      },
                      "failed": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Number of items failed by this point."
                      },
                      "averageConfidence": {
                          "type": [
                              "number",
                              "null"
                          ],
                          "description": "Average confidence recorded by this point."
                      },
                      "refusalRate": {
                          "type": "number",
                          "description": "Refusal rate recorded by this point."
                      }
                  },
                  "description": "Represents one point in a batch job progress chart."
              },
              "description": "Timeline points describing job progress."
          },
          "latestItems": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Item identifier used by batch item endpoints."
                      },
                      "parentBatchWorkflowJobId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Job identifier that owns and processes this item."
                      },
                      "insertedAt": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Date and time when the item was inserted."
                      },
                      "processedAt": {
                          "format": "date-time",
                          "description": "Date and time when processing finished, failed or was refused.",
                          "type": [
                              "string",
                              "null"
                          ]
                      },
                      "state": {
                          "type": "string",
                          "enum": [
                              "Pending",
                              "Finished",
                              "Refused",
                              "ExecutionError",
                              "ValidationError",
                              "Cancelled"
                          ],
                          "description": "Current processing state for this item."
                      },
                      "priority": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Processing priority; lower values are processed before higher values."
                      },
                      "input": {
                          "type": "string",
                          "description": "Raw item input sent to the workflow model."
                      },
                      "output": {
                          "type": [
                              "string",
                              "null"
                          ],
                          "description": "Raw item output produced by the workflow model."
                      },
                      "validationResult": {
                          "properties": {
                              "passed": {
                                  "type": "boolean",
                                  "description": "Whether the output passed validation."
                              },
                              "reason": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Explanation for the validation result."
                              }
                          },
                          "description": "Validation result for the item output, when validation was configured or performed.",
                          "type": [
                              "object",
                              "null"
                          ]
                      },
                      "confidence": {
                          "type": [
                              "number",
                              "null"
                          ],
                          "description": "Optional confidence score assigned to the item output."
                      },
                      "totalCost": {
                          "type": [
                              "number",
                              "null"
                          ],
                          "description": "Total estimated or recorded cost for processing this item."
                      }
                  },
                  "required": [
                      "parentBatchWorkflowJobId",
                      "input"
                  ],
                  "description": "Represents one input item queued for a batch workflow job."
              },
              "description": "Most recent processed items for quick inspection."
          }
      },
      "description": "Full batch job view with status, progression and recent processed items."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the batch job to delete.

Responses:

• 200

  The batch job and its items were deleted.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the batch job that will receive items.

Request parameters:

• modestring

  Import mode: lines, files, zip, or text. Defaults to lines when omitted.

• itemsfile

  The uploaded file or files. In lines mode, each non-empty line is imported. In files mode, each file is imported as one item. In zip mode, each text entry is imported as one item.

• documentsfile

  Accepted alias for the items file field.

• textstring

  Manual item input for text mode.

Request examples:

• Multipart form data with a mode field: lines, files, zip, or text. The 'items' field contains uploaded files, 'documents' is accepted as a file alias, and 'text' contains manual item text for text mode.

  {"name":"Customer A","email":"[email protected]"}
  {"name":"Customer B","email":"[email protected]"}

Responses:

• 200
  ExampleSchema

  {
      // Number of items inserted into the job.
      "inserted": number,
  
      // Number of empty or invalid inputs skipped.
      "skipped": number
  }

  {
      "type": "object",
      "properties": {
          "inserted": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "Number of items inserted into the job."
          },
          "skipped": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "Number of empty or invalid inputs skipped."
          }
      },
      "description": "Counts returned after importing batch items."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the batch job whose items will be listed.

Query parameters:

• statestring

  Optional item state filter, such as Pending, Finished, ExecutionError or ValidationError.

• confidencestring

  Optional confidence filter. Accepted values: high, high-confidence, low or low-confidence.

• filterstring

  Optional text search over item input.

• sortstring

  Item ordering. Accepted values: inserted-desc, inserted-asc, processed-desc or processed-asc. Defaults to inserted-desc.

• limitinteger

  Maximum number of items to return. The endpoint enforces an upper bound.

Responses:

• 200
  ExampleSchema

  [
      {
          // Unique item identifier.
          "id": "uuid",
  
          // Timestamp when the item was inserted.
          "insertedAt": "date-time",
  
          // Current processing state.
          "state": "Pending",
  
          // Whether a worker is currently processing this item.
          "isRunning": boolean,
  
          // Processing priority. Higher values are processed first.
          "priority": number,
  
          // Shortened input payload.
          "input": string,
  
          // Nullable. Optional validation confidence score.
          "confidence": number?,
  
          // Nullable. Total billed cost for this item when available.
          "totalCost": number?
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Unique item identifier."
              },
              "insertedAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Timestamp when the item was inserted."
              },
              "state": {
                  "type": "string",
                  "enum": [
                      "Pending",
                      "Finished",
                      "Refused",
                      "ExecutionError",
                      "ValidationError",
                      "Cancelled"
                  ],
                  "description": "Current processing state."
              },
              "isRunning": {
                  "type": "boolean",
                  "description": "Whether a worker is currently processing this item."
              },
              "priority": {
                  "type": "integer",
                  "minimum": -2147483648,
                  "maximum": 2147483647,
                  "description": "Processing priority. Higher values are processed first."
              },
              "input": {
                  "type": "string",
                  "description": "Shortened input payload."
              },
              "confidence": {
                  "type": [
                      "number",
                      "null"
                  ],
                  "description": "Optional validation confidence score."
              },
              "totalCost": {
                  "type": [
                      "number",
                      "null"
                  ],
                  "description": "Total billed cost for this item when available."
              }
          },
          "description": "Batch item summary returned by the item listing endpoint."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the batch job whose items will be removed.

Query parameters:

• modestring

  Deletion mode. Accepted values: pending, finished, errors or all.

Responses:

• 200

  Matching items were removed.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the batch job whose items will be retried.

Query parameters:

• modestring

  Retry mode. Accepted values: errors, execution-error, validation-error or low-confidence.

Responses:

• 200
  ExampleSchema

  {
      // Stored batch job record.
      "job": {
          // Job identifier used by batch job and item endpoints.
          "id": "uuid",
  
          // Date and time when the job was created.
          "createdAt": "date-time",
  
          // Current processing state for this job.
          "state": "Active",
  
          // Nullable. Date and time when the job was last restarted or resumed.
          "restartedAt": "date-time"?,
  
          // Nullable. Optional caller-facing job title.
          "title": string?,
  
          // Required. Workflow identifier whose options are used by this job.
          "parentBatchWorkflowId": "uuid",
  
          // Timeline of job-level events, such as creation, pause, resume or completion.
          "updates": [
              {
                  // Date and time when the event was recorded.
                  "moment": "date-time",
  
                  // Required. Short machine-readable event type.
                  "eventType": string,
  
                  // Required. Human-readable event description.
                  "description": string
              },
              ...
          ]
      },
  
      // Aggregated item counts and job status.
      "summary": {
          // Job identifier.
          "id": "uuid",
  
          // Workflow identifier that owns this job.
          "parentBatchWorkflowId": "uuid",
  
          // Nullable. Title of the parent workflow, when available.
          "workflowTitle": string?,
  
          // Nullable. Job title, when set.
          "title": string?,
  
          // Date and time when the job was created.
          "createdAt": "date-time",
  
          // Current job processing state.
          "state": "Active",
  
          // Nullable. Date and time when the job was last restarted or resumed.
          "restartedAt": "date-time"?,
  
          // Number of items waiting to be processed.
          "pending": number,
  
          // Number of items processed successfully.
          "finished": number,
  
          // Number of items refused by validation or policy.
          "refused": number,
  
          // Number of items that failed during execution.
          "executionErrors": number,
  
          // Number of items whose output failed validation.
          "validationErrors": number,
  
          // Number of cancelled items.
          "cancelled": number,
  
          // Number of items currently marked as running.
          "running": number,
  
          // Total recorded cost for processed items.
          "totalCost": number,
  
          // Nullable. Average confidence for items with a confidence score.
          "averageConfidence": number?,
  
          // Finished-item share among completed items.
          "successRate": number,
  
          // Refused-item share among completed items.
          "refusalRate": number,
  
          // Number of job timeline events.
          "eventCount": number,
  
          // Number of items that ended in refusal, execution error or validation error states.
          "failed": number,
  
          // Number of items no longer pending or running.
          "completed": number,
  
          // Total number of items represented by this summary.
          "total": number
      },
  
      // Timeline points describing job progress.
      "progression": [
          {
              // Time bucket represented by this point.
              "moment": "date-time",
  
              // Number of items finished by this point.
              "finished": number,
  
              // Number of items failed by this point.
              "failed": number,
  
              // Nullable. Average confidence recorded by this point.
              "averageConfidence": number?,
  
              // Refusal rate recorded by this point.
              "refusalRate": number
          },
          ...
      ],
  
      // Most recent processed items for quick inspection.
      "latestItems": [
          {
              // Item identifier used by batch item endpoints.
              "id": "uuid",
  
              // Required. Job identifier that owns and processes this item.
              "parentBatchWorkflowJobId": "uuid",
  
              // Date and time when the item was inserted.
              "insertedAt": "date-time",
  
              // Nullable. Date and time when processing finished, failed or was refused.
              "processedAt": "date-time"?,
  
              // Current processing state for this item.
              "state": "Pending",
  
              // Processing priority; lower values are processed before higher values.
              "priority": number,
  
              // Required. Raw item input sent to the workflow model.
              "input": string,
  
              // Nullable. Raw item output produced by the workflow model.
              "output": string?,
  
              // Nullable. Validation result for the item output, when validation was configured or performed.
              "validationResult": {
                  // Whether the output passed validation.
                  "passed": boolean,
  
                  // Nullable. Explanation for the validation result.
                  "reason": string?
              }?,
  
              // Nullable. Optional confidence score assigned to the item output.
              "confidence": number?,
  
              // Nullable. Total estimated or recorded cost for processing this item.
              "totalCost": number?
          },
          ...
      ]
  }

  {
      "type": "object",
      "properties": {
          "job": {
              "type": "object",
              "properties": {
                  "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Job identifier used by batch job and item endpoints."
                  },
                  "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Date and time when the job was created."
                  },
                  "state": {
                      "type": "string",
                      "enum": [
                          "Active",
                          "Paused",
                          "Finished"
                      ],
                      "description": "Current processing state for this job."
                  },
                  "restartedAt": {
                      "format": "date-time",
                      "description": "Date and time when the job was last restarted or resumed.",
                      "type": [
                          "string",
                          "null"
                      ]
                  },
                  "title": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional caller-facing job title."
                  },
                  "parentBatchWorkflowId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Workflow identifier whose options are used by this job."
                  },
                  "updates": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "moment": {
                                  "type": "string",
                                  "format": "date-time",
                                  "description": "Date and time when the event was recorded."
                              },
                              "eventType": {
                                  "type": "string",
                                  "description": "Short machine-readable event type."
                              },
                              "description": {
                                  "type": "string",
                                  "description": "Human-readable event description."
                              }
                          },
                          "required": [
                              "eventType",
                              "description"
                          ],
                          "description": "Represents one event in a batch job timeline."
                      },
                      "description": "Timeline of job-level events, such as creation, pause, resume or completion."
                  }
              },
              "required": [
                  "parentBatchWorkflowId"
              ],
              "description": "Stored batch job record."
          },
          "summary": {
              "type": "object",
              "properties": {
                  "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Job identifier."
                  },
                  "parentBatchWorkflowId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Workflow identifier that owns this job."
                  },
                  "workflowTitle": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Title of the parent workflow, when available."
                  },
                  "title": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Job title, when set."
                  },
                  "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Date and time when the job was created."
                  },
                  "state": {
                      "type": "string",
                      "enum": [
                          "Active",
                          "Paused",
                          "Finished"
                      ],
                      "description": "Current job processing state."
                  },
                  "restartedAt": {
                      "format": "date-time",
                      "description": "Date and time when the job was last restarted or resumed.",
                      "type": [
                          "string",
                          "null"
                      ]
                  },
                  "pending": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items waiting to be processed."
                  },
                  "finished": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items processed successfully."
                  },
                  "refused": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items refused by validation or policy."
                  },
                  "executionErrors": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items that failed during execution."
                  },
                  "validationErrors": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items whose output failed validation."
                  },
                  "cancelled": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of cancelled items."
                  },
                  "running": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items currently marked as running."
                  },
                  "totalCost": {
                      "type": "number",
                      "description": "Total recorded cost for processed items."
                  },
                  "averageConfidence": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Average confidence for items with a confidence score."
                  },
                  "successRate": {
                      "type": "number",
                      "description": "Finished-item share among completed items."
                  },
                  "refusalRate": {
                      "type": "number",
                      "description": "Refused-item share among completed items."
                  },
                  "eventCount": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of job timeline events."
                  },
                  "failed": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items that ended in refusal, execution error or validation error states."
                  },
                  "completed": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Number of items no longer pending or running."
                  },
                  "total": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Total number of items represented by this summary."
                  }
              },
              "description": "Aggregated item counts and job status."
          },
          "progression": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "moment": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Time bucket represented by this point."
                      },
                      "finished": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Number of items finished by this point."
                      },
                      "failed": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Number of items failed by this point."
                      },
                      "averageConfidence": {
                          "type": [
                              "number",
                              "null"
                          ],
                          "description": "Average confidence recorded by this point."
                      },
                      "refusalRate": {
                          "type": "number",
                          "description": "Refusal rate recorded by this point."
                      }
                  },
                  "description": "Represents one point in a batch job progress chart."
              },
              "description": "Timeline points describing job progress."
          },
          "latestItems": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Item identifier used by batch item endpoints."
                      },
                      "parentBatchWorkflowJobId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Job identifier that owns and processes this item."
                      },
                      "insertedAt": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Date and time when the item was inserted."
                      },
                      "processedAt": {
                          "format": "date-time",
                          "description": "Date and time when processing finished, failed or was refused.",
                          "type": [
                              "string",
                              "null"
                          ]
                      },
                      "state": {
                          "type": "string",
                          "enum": [
                              "Pending",
                              "Finished",
                              "Refused",
                              "ExecutionError",
                              "ValidationError",
                              "Cancelled"
                          ],
                          "description": "Current processing state for this item."
                      },
                      "priority": {
                          "type": "integer",
                          "minimum": -2147483648,
                          "maximum": 2147483647,
                          "description": "Processing priority; lower values are processed before higher values."
                      },
                      "input": {
                          "type": "string",
                          "description": "Raw item input sent to the workflow model."
                      },
                      "output": {
                          "type": [
                              "string",
                              "null"
                          ],
                          "description": "Raw item output produced by the workflow model."
                      },
                      "validationResult": {
                          "properties": {
                              "passed": {
                                  "type": "boolean",
                                  "description": "Whether the output passed validation."
                              },
                              "reason": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Explanation for the validation result."
                              }
                          },
                          "description": "Validation result for the item output, when validation was configured or performed.",
                          "type": [
                              "object",
                              "null"
                          ]
                      },
                      "confidence": {
                          "type": [
                              "number",
                              "null"
                          ],
                          "description": "Optional confidence score assigned to the item output."
                      },
                      "totalCost": {
                          "type": [
                              "number",
                              "null"
                          ],
                          "description": "Total estimated or recorded cost for processing this item."
                      }
                  },
                  "required": [
                      "parentBatchWorkflowJobId",
                      "input"
                  ],
                  "description": "Represents one input item queued for a batch workflow job."
              },
              "description": "Most recent processed items for quick inspection."
          }
      },
      "description": "Full batch job view with status, progression and recent processed items."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the batch job to export.

Query parameters:

• statestring

  Export state filter. Use all, finished, failed, errors, success or an item state name.

• confidencestring

  Optional confidence filter. Accepted values: high, high-confidence, low or low-confidence.

Responses:

• 200

  JSONL file stream containing one processed item per line.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the parent batch job.

• item-iduuid

  Identifier of the batch item to retrieve.

Responses:

• 200
  ExampleSchema

  {
      // Unique item identifier.
      "id": "uuid",
  
      // Timestamp when the item was inserted.
      "insertedAt": "date-time",
  
      // Nullable. Timestamp when processing finished, if finished.
      "processedAt": "date-time"?,
  
      // Current processing state.
      "state": "Pending",
  
      // Whether a worker is currently processing this item.
      "isRunning": boolean,
  
      // Processing priority. Higher values are processed first.
      "priority": number,
  
      // Input payload, truncated to the endpoint limit when very large.
      "input": string,
  
      // Nullable. Generated output, truncated to the endpoint limit when very large.
      "output": string?,
  
      // Nullable. Validation details when validation is enabled for the workflow.
      "validationResult": {
          // Whether the output passed validation.
          "passed": boolean,
  
          // Nullable. Explanation for the validation result.
          "reason": string?
      }?,
  
      // Nullable. Optional validation confidence score.
      "confidence": number?,
  
      // Nullable. Total billed cost for this item when available.
      "totalCost": number?
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "string",
              "format": "uuid",
              "description": "Unique item identifier."
          },
          "insertedAt": {
              "type": "string",
              "format": "date-time",
              "description": "Timestamp when the item was inserted."
          },
          "processedAt": {
              "format": "date-time",
              "description": "Timestamp when processing finished, if finished.",
              "type": [
                  "string",
                  "null"
              ]
          },
          "state": {
              "type": "string",
              "enum": [
                  "Pending",
                  "Finished",
                  "Refused",
                  "ExecutionError",
                  "ValidationError",
                  "Cancelled"
              ],
              "description": "Current processing state."
          },
          "isRunning": {
              "type": "boolean",
              "description": "Whether a worker is currently processing this item."
          },
          "priority": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "Processing priority. Higher values are processed first."
          },
          "input": {
              "type": "string",
              "description": "Input payload, truncated to the endpoint limit when very large."
          },
          "output": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Generated output, truncated to the endpoint limit when very large."
          },
          "validationResult": {
              "properties": {
                  "passed": {
                      "type": "boolean",
                      "description": "Whether the output passed validation."
                  },
                  "reason": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Explanation for the validation result."
                  }
              },
              "description": "Validation details when validation is enabled for the workflow.",
              "type": [
                  "object",
                  "null"
              ]
          },
          "confidence": {
              "type": [
                  "number",
                  "null"
              ],
              "description": "Optional validation confidence score."
          },
          "totalCost": {
              "type": [
                  "number",
                  "null"
              ],
              "description": "Total billed cost for this item when available."
          }
      },
      "description": "Full batch item details returned by the item detail endpoint."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the parent batch job.

• item-iduuid

  Identifier of the batch item to update.

Request examples:

• Partial item update JSON object. Send priority to reprioritize, or action: cancel to remove the item.

Responses:

• 200
  ExampleSchema

  {
      // Item identifier used by batch item endpoints.
      "id": "uuid",
  
      // Required. Job identifier that owns and processes this item.
      "parentBatchWorkflowJobId": "uuid",
  
      // Date and time when the item was inserted.
      "insertedAt": "date-time",
  
      // Nullable. Date and time when processing finished, failed or was refused.
      "processedAt": "date-time"?,
  
      // Current processing state for this item.
      "state": "Pending",
  
      // Processing priority; lower values are processed before higher values.
      "priority": number,
  
      // Required. Raw item input sent to the workflow model.
      "input": string,
  
      // Nullable. Raw item output produced by the workflow model.
      "output": string?,
  
      // Nullable. Validation result for the item output, when validation was configured or performed.
      "validationResult": {
          // Whether the output passed validation.
          "passed": boolean,
  
          // Nullable. Explanation for the validation result.
          "reason": string?
      }?,
  
      // Nullable. Optional confidence score assigned to the item output.
      "confidence": number?,
  
      // Nullable. Total estimated or recorded cost for processing this item.
      "totalCost": number?
  }

  {
      "type": "object",
      "properties": {
          "id": {
              "type": "string",
              "format": "uuid",
              "description": "Item identifier used by batch item endpoints."
          },
          "parentBatchWorkflowJobId": {
              "type": "string",
              "format": "uuid",
              "description": "Job identifier that owns and processes this item."
          },
          "insertedAt": {
              "type": "string",
              "format": "date-time",
              "description": "Date and time when the item was inserted."
          },
          "processedAt": {
              "format": "date-time",
              "description": "Date and time when processing finished, failed or was refused.",
              "type": [
                  "string",
                  "null"
              ]
          },
          "state": {
              "type": "string",
              "enum": [
                  "Pending",
                  "Finished",
                  "Refused",
                  "ExecutionError",
                  "ValidationError",
                  "Cancelled"
              ],
              "description": "Current processing state for this item."
          },
          "priority": {
              "type": "integer",
              "minimum": -2147483648,
              "maximum": 2147483647,
              "description": "Processing priority; lower values are processed before higher values."
          },
          "input": {
              "type": "string",
              "description": "Raw item input sent to the workflow model."
          },
          "output": {
              "type": [
                  "string",
                  "null"
              ],
              "description": "Raw item output produced by the workflow model."
          },
          "validationResult": {
              "properties": {
                  "passed": {
                      "type": "boolean",
                      "description": "Whether the output passed validation."
                  },
                  "reason": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Explanation for the validation result."
                  }
              },
              "description": "Validation result for the item output, when validation was configured or performed.",
              "type": [
                  "object",
                  "null"
              ]
          },
          "confidence": {
              "type": [
                  "number",
                  "null"
              ],
              "description": "Optional confidence score assigned to the item output."
          },
          "totalCost": {
              "type": [
                  "number",
                  "null"
              ],
              "description": "Total estimated or recorded cost for processing this item."
          }
      },
      "required": [
          "parentBatchWorkflowJobId",
          "input"
      ],
      "description": "Represents one input item queued for a batch workflow job."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• workflow-iduuid

  Identifier of the parent workflow.

• job-iduuid

  Identifier of the parent batch job.

• item-iduuid

  Identifier of the batch item to delete.

Responses:

• 200

  The item was removed.

Request examples:

• Login payload containing the account login key delivered by email.

  ExampleSchema

  {
      // The login key delivered to the account holder by email at registration time.
      "loginKey": string
  }

  {
      "type": "object",
      "properties": {
          "loginKey": {
              "type": "string",
              "description": "The login key delivered to the account holder by email at registration time."
          }
      },
      "description": "Payload sent to authenticate using a login key."
  }

Responses:

• 200

  Login succeeded and returned a 180-day account-management access token.

  ExampleSchema

  {
      // Account-management API key valid for 180 days.
      "accessToken": string,
  
      // Basic data of the authenticated account.
      "account": {
          // The unique identifier of the account.
          "id": "uuid",
  
          // The account holder's display name.
          "name": string,
  
          // The account holder's email address.
          "email": string,
  
          // Lowercase SHA-256 hash of the email (useful for Gravatar).
          "emailSha256": string,
  
          // The current plan associated with the account.
          "plan": "Free",
  
          // Indicates whether the account has administrator level.
          "isAdmin": boolean,
  
          // The account configuration parameters.
          "parameters": {
              // Enables storage of conversation records for observability, export and troubleshooting.
              "allowConversationsLogging": boolean,
  
              // Enables automatic repair attempts when a model response is expected to be JSON but is malformed.
              "automaticJsonHealing": boolean,
  
              // Allows account-deidentified RAG and Reflex search data to be collected for model training in exchange for eligible search discounts.
              "allowSemanticDataCollection": boolean,
  
              // Notification preferences for account-level events.
              "notifications": {
                  // Additional notification destination e-mails.
                  "emails": [
                      string,
                      ...
                  ],
  
                  // Low-balance notification settings.
                  "lowBalance": {
                      // Enables e-mail notification when the account balance reaches the configured threshold.
                      "enabled": boolean,
  
                      // Balance threshold that triggers low-balance notifications.
                      "threshold": number
                  },
  
                  // Deprecated-model notification settings.
                  "deprecatedModels": {
                      // Enables e-mail notification when configured models are deprecated.
                      "enabled": boolean
                  }
              }
          }
      }
  }

  {
      "type": "object",
      "properties": {
          "accessToken": {
              "type": "string",
              "description": "Account-management API key valid for 180 days."
          },
          "account": {
              "type": "object",
              "properties": {
                  "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The unique identifier of the account."
                  },
                  "name": {
                      "type": "string",
                      "description": "The account holder\u0027s display name."
                  },
                  "email": {
                      "type": "string",
                      "description": "The account holder\u0027s email address."
                  },
                  "emailSha256": {
                      "type": "string",
                      "description": "Lowercase SHA-256 hash of the email (useful for Gravatar)."
                  },
                  "plan": {
                      "type": "string",
                      "enum": [
                          "Free",
                          "Pro",
                          "Max"
                      ],
                      "description": "The current plan associated with the account."
                  },
                  "isAdmin": {
                      "type": "boolean",
                      "description": "Indicates whether the account has administrator level."
                  },
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "allowConversationsLogging": {
                              "type": "boolean",
                              "description": "Enables storage of conversation records for observability, export and troubleshooting."
                          },
                          "automaticJsonHealing": {
                              "type": "boolean",
                              "description": "Enables automatic repair attempts when a model response is expected to be JSON but is malformed."
                          },
                          "allowSemanticDataCollection": {
                              "type": "boolean",
                              "description": "Allows account-deidentified RAG and Reflex search data to be collected for model training in exchange for eligible search discounts."
                          },
                          "notifications": {
                              "type": "object",
                              "properties": {
                                  "emails": {
                                      "type": "array",
                                      "items": {
                                          "type": "string"
                                      },
                                      "description": "Additional notification destination e-mails."
                                  },
                                  "lowBalance": {
                                      "type": "object",
                                      "properties": {
                                          "enabled": {
                                              "type": "boolean",
                                              "description": "Enables e-mail notification when the account balance reaches the configured threshold."
                                          },
                                          "threshold": {
                                              "type": "number",
                                              "description": "Balance threshold that triggers low-balance notifications."
                                          }
                                      },
                                      "description": "Low-balance notification settings."
                                  },
                                  "deprecatedModels": {
                                      "type": "object",
                                      "properties": {
                                          "enabled": {
                                              "type": "boolean",
                                              "description": "Enables e-mail notification when configured models are deprecated."
                                          }
                                      },
                                      "description": "Deprecated-model notification settings."
                                  }
                              },
                              "description": "Notification preferences for account-level events."
                          }
                      },
                      "description": "The account configuration parameters."
                  }
              },
              "description": "Basic data of the authenticated account."
          }
      },
      "description": "Response returned after a successful login."
  }

• 400

  Invalid or missing request body, invalid login key, or forbidden account.

• 429

  Login rate limit exceeded for the current remote address.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• AI Gateway creation payload. Use parameters to configure model access, retrieval, tools, moderation and runtime behavior.

  ExampleSchema

  {
      // The human-readable name of the gateway.
      "name": string,
  
      // Runtime configuration for model selection, instructions, retrieval, tools and moderation.
      "parameters": {
          // Required. Inference endpoint URL used by the gateway. Use @integrated to route through AIVAX managed models.
          "baseAddress": string,
  
          // Skill identifiers enabled for this gateway. Skills add instructions and may expose a subset of gateway tools.
          "skills": [
              "uuid",
              ...
          ],
  
          // When enabled, hides tools that are not associated with one of the enabled skills, except names listed in .
          "hideToolsWithoutSkill": boolean,
  
          // Tool names that remain available even when is enabled.
          "alwaysVisibleTools": [
              string,
              ...
          ],
  
          // Enables the built-in virtual Bash tool so the model can run shell commands in a controlled environment.
          "enableBash": boolean,
  
          // When enabled, automatically includes root AGENTS.md and MEMORY.md workspace files as system instructions. Each file is limited to 16K characters.
          "includeWorkspaceInstructions": boolean,
  
          // Nullable. Optional persistence and command-filter settings for the virtual Bash tool.
          "bashOptions": {
              // Allows files created by the Bash tool to persist between tool executions for the same environment.
              "allowDataPersistence": boolean,
  
              // Bash tool command names affected by .
              "toolList": [
                  string,
                  ...
              ],
  
              // Determines whether is an allow-list or block-list.
              "toolExclusionMode": "WhiteList"
          }?,
  
          // Collection identifiers queried for retrieval-augmented generation before the model is called.
          "knowledgeCollections": [
              "uuid",
              ...
          ],
  
          // Nullable. Reranker algorithm name used to reorder retrieved knowledge results.
          "rerankerName": string?,
  
          // Maximum number of knowledge documents injected into the prompt.
          "knowledgeBaseMaximumResults": number,
  
          // Minimum similarity score, from 0 to 1, required for a knowledge result to be included.
          "knowledgeBaseMinimumScore": number,
  
          // Includes referenced parent documents when a matched knowledge document points to another stored document.
          "knowledgeUseReferences": boolean,
  
          // Includes document metadata descriptions in the retrieved knowledge context when available.
          "knowledgeUseMetaDescriptions": boolean,
  
          // Strategy used to transform the user request before searching knowledge collections.
          "queryStrategy": "Plain",
  
          // Numeric limits used by query strategies that read recent conversation messages.
          "queryStrategyParameters": {
              // Number of recent messages used by the full-rewrite and user-rewrite query strategies.
              "rewriteContextSize": number,
  
              // Number of recent user messages joined by the concatenate query strategy.
              "concatenateContextSize": number
          },
  
          // Nullable. Provider API key used when points to an external OpenAI-compatible endpoint.
          "apiKey": string?,
  
          // Required. Model name sent to the inference provider, or the AIVAX integrated model identifier when is @integrated.
          "modelName": string,
  
          // Nullable. Sampling temperature forwarded to the model provider when the selected model supports it.
          "temperature": number?,
  
          // Nullable. Nucleus sampling value forwarded as top_p when the selected model supports it.
          "topP": number?,
  
          // Nullable. Presence penalty forwarded to the model provider when supported.
          "presencePenalty": number?,
  
          // Nullable. Frequency penalty forwarded to the model provider when supported.
          "frequencyPenalty": number?,
  
          // Nullable. Stop sequence used to end generation early when the selected model supports stop parameters.
          "stop": string?,
  
          // Nullable. Maximum number of output tokens the model may generate.
          "maxCompletionTokens": number?,
  
          // Nullable. Optional context-window limit used before sending messages to the model provider.
          "contextMaximumSize": number?,
  
          // Action taken when the prepared prompt exceeds .
          "contextOverflowAction": "Throw",
  
          // Nullable. Main system instruction prepended to conversations handled by this gateway.
          "systemInstruction": string?,
  
          // Nullable. Optional worker script URL called during gateway events to allow external policy or orchestration decisions.
          "workerScriptSource": "url"?,
  
          // Nullable. Optional template applied to user messages before they are sent to the model.
          "userPromptTemplate": string?,
  
          // Nullable. Optional assistant text inserted before generation for models that support assistant prefilling.
          "assistantPrefill": string?,
  
          // When enabled, stores the assistant prefill as part of the conversation messages instead of using only provider-specific prefill support.
          "includePrefillingInMessages": boolean,
  
          // Nullable. Provider-specific reasoning-effort value, such as low, medium or high, when the selected model supports it.
          "reasoningEffort": string?,
  
          // Nullable. Provider-specific verbosity value that controls response detail when the selected model supports it.
          "verbosity": string?,
  
          // Model behavior flags that change how AIVAX prepares provider requests, for example disabling unsupported parameters, preserving reasoning tokens or enforcing strict turn order.
          "flags": [
              "NoSystemInstruct",
              ...
          ],
  
          // Nullable. Raw provider-native tool definitions sent directly to the model request. Use protocol functions or MCP sources for tools that AIVAX should execute and return to the model.
          "tools": [
              ...
          ]?,
  
          // Remote HTTP callback tools executed by AIVAX when the model calls them. Use these for simple externally hosted functions; use for Model Context Protocol servers.
          "protocolFunctions": [
              {
                  // Required. Unique tool name shown to the model. It must be a valid JavaScript identifier because providers use it as the function-call name.
                  "name": string,
  
                  // Required. Description shown to the model so it can decide when to call this function and what result to expect.
                  "description": string,
  
                  // Optional HTTP headers added to the callback request when AIVAX executes this function.
                  "headers": {},
  
                  // Required. Absolute HTTP, HTTPS or AIVAX URL called with a POST request when the model invokes this function.
                  "callbackUrl": string,
  
                  // Required. JSON schema for the arguments the model must provide when calling this function.
                  "contentFormat": any
              },
              ...
          ],
  
          // URLs that return protocol function definitions. AIVAX fetches these definitions and exposes them as executable callback tools.
          "protocolFunctionSources": [
              string,
              ...
          ],
  
          // External Model Context Protocol servers whose listed tools are exposed to the gateway and executed through MCP tool calls.
          "mcpSources": [
              {
                  // Required. Short display name used in logs and generated instruction context.
                  "name": string,
  
                  // Nullable. Optional description explaining what this external resource provides.
                  "description": string?,
  
                  // Required. Absolute HTTP or HTTPS URL of the resource.
                  "url": "url",
  
                  // HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server.
                  "headers": {},
  
                  // Cache duration in seconds for fetched resource content or MCP tool discovery results.
                  "cacheDuration": number
              },
              ...
          ],
  
          // External text resources fetched and appended to the gateway system instructions.
          "systemInstructionsSources": [
              {
                  // Required. Short display name used in logs and generated instruction context.
                  "name": string,
  
                  // Nullable. Optional description explaining what this external resource provides.
                  "description": string?,
  
                  // Required. Absolute HTTP or HTTPS URL of the resource.
                  "url": "url",
  
                  // HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server.
                  "headers": {},
  
                  // Cache duration in seconds for fetched resource content or MCP tool discovery results.
                  "cacheDuration": number
              },
              ...
          ],
  
          // Input media types that AIVAX may resolve and forward to the model, such as images, audio, video or files.
          "enabledMultimodalFeatures": [
              "Image",
              ...
          ],
  
          // Nullable. Number of previous tool response messages kept in conversation context before older tool results are removed.
          "toolContextCount": number?,
  
          // Nullable. Built-in tool set exposed through the Sentinel reasoning layer.
          "sentinelOptions": {
              // Built-in functions exposed to the Sentinel reasoning layer.
              "enabledFunctions": [
                  "WebSearch",
                  ...
              ]
          }?,
  
          // Nullable. Configuration for AIVAX built-in tools such as web search, image generation and memory.
          "builtinFunctionsOptions": {
              // Level of detail returned by built-in web search tools.
              "webSearchMode": "Full",
  
              // Maximum number of search results returned by built-in web search tools.
              "webSearchMaxResults": number,
  
              // Maximum number of images the built-in image generation tool may create in one call.
              "imageGenerationMaxResults": number,
  
              // Quality level used by the built-in image generation tool.
              "imageGenerationQuality": "Low",
  
              // Allows the built-in image generation tool to produce mature content when the selected model and policy allow it.
              "imageGenerationAllowMatureContent": boolean,
  
              // Allows the built-in image generation tool to use reference images from web results or user uploads.
              "imageGenerationAllowReferenceUsage": boolean,
  
              // Nullable. Optional image-generation model name. When omitted, AIVAX uses its default image model.
              "imageGenerationModelName": string?,
  
              // Includes all available memory context in system instructions instead of only memory selected by the runtime.
              "includeAllMemoryContext": boolean,
  
              // Allows this gateway to consume memories created by other gateways.
              "allowSharedMemory": boolean
          }?,
  
          // Nullable. Moderation thresholds used to block unsafe or disallowed chat content before inference.
          "moderationParameters": {
              // Gets the threshold for violence-related content (0-100).
              "violenceThreshold": number,
  
              // Gets the threshold for sexually explicit content (0-100).
              "sexualExplicitThreshold": number,
  
              // Gets the threshold for political content (0-100).
              "politicalThreshold": number,
  
              // Gets the threshold for dangerous content (0-100).
              "dangerousContentThreshold": number,
  
              // Gets the threshold for jailbreak attempts (0-100).
              "jailbreakThreshold": number
          }?,
  
          // Nullable. Tool-calling handler name. Use native or null for provider-native tool calling; other values select an AIVAX compatibility handler.
          "knownToolHandlerName": string?,
  
          // Adds visible explanations of tool invocations to the model response when supported by the selected tool-calling path.
          "toolInvocationExplanations": boolean,
  
          // Nullable. Model names used by the complexity router when selects the AIVAX model-routing gateway.
          "modelRoutingParameters": {
              // Required. Integrated model name used when the router classifies a request as low complexity.
              "lowComplexityModelName": string,
  
              // Nullable. Optional reasoning-effort value applied to low-complexity routed requests.
              "lowComplexityModelReasoningEffort": string?,
  
              // Required. Integrated model name used when the router classifies a request as medium complexity.
              "mediumComplexityModelName": string,
  
              // Nullable. Optional reasoning-effort value applied to medium-complexity routed requests.
              "mediumComplexityModelReasoningEffort": string?,
  
              // Required. Integrated model name used when the router classifies a request as high complexity.
              "highComplexityModelName": string,
  
              // Nullable. Optional reasoning-effort value applied to high-complexity routed requests.
              "highComplexityModelReasoningEffort": string?
          }?,
  
          // Nullable. Provider- or integration-specific JSON settings that are not represented by first-class gateway parameters.
          "additionalSettings": {}?
      }
  }

  {
      "type": "object",
      "properties": {
          "name": {
              "type": "string",
              "description": "The human-readable name of the gateway."
          },
          "parameters": {
              "type": "object",
              "properties": {
                  "baseAddress": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Inference endpoint URL used by the gateway. Use @integrated to route through AIVAX managed models."
                  },
                  "skills": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "format": "uuid",
                          "description": "UUID/GUID string"
                      },
                      "description": "Skill identifiers enabled for this gateway. Skills add instructions and may expose a subset of gateway tools."
                  },
                  "hideToolsWithoutSkill": {
                      "type": "boolean",
                      "description": "When enabled, hides tools that are not associated with one of the enabled skills, except names listed in ."
                  },
                  "alwaysVisibleTools": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      },
                      "description": "Tool names that remain available even when is enabled."
                  },
                  "enableBash": {
                      "type": "boolean",
                      "description": "Enables the built-in virtual Bash tool so the model can run shell commands in a controlled environment."
                  },
                  "includeWorkspaceInstructions": {
                      "type": "boolean",
                      "description": "When enabled, automatically includes root AGENTS.md and MEMORY.md workspace files as system instructions. Each file is limited to 16K characters."
                  },
                  "bashOptions": {
                      "properties": {
                          "allowDataPersistence": {
                              "type": "boolean",
                              "description": "Allows files created by the Bash tool to persist between tool executions for the same environment."
                          },
                          "toolList": {
                              "type": "array",
                              "items": {
                                  "type": "string"
                              },
                              "description": "Bash tool command names affected by ."
                          },
                          "toolExclusionMode": {
                              "type": "string",
                              "enum": [
                                  "WhiteList",
                                  "BlackList"
                              ],
                              "description": "Determines whether is an allow-list or block-list."
                          }
                      },
                      "description": "Optional persistence and command-filter settings for the virtual Bash tool.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "knowledgeCollections": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "format": "uuid",
                          "description": "UUID/GUID string"
                      },
                      "description": "Collection identifiers queried for retrieval-augmented generation before the model is called."
                  },
                  "rerankerName": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Reranker algorithm name used to reorder retrieved knowledge results."
                  },
                  "knowledgeBaseMaximumResults": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Maximum number of knowledge documents injected into the prompt."
                  },
                  "knowledgeBaseMinimumScore": {
                      "type": "number",
                      "description": "Minimum similarity score, from 0 to 1, required for a knowledge result to be included."
                  },
                  "knowledgeUseReferences": {
                      "type": "boolean",
                      "description": "Includes referenced parent documents when a matched knowledge document points to another stored document."
                  },
                  "knowledgeUseMetaDescriptions": {
                      "type": "boolean",
                      "description": "Includes document metadata descriptions in the retrieved knowledge context when available."
                  },
                  "queryStrategy": {
                      "type": "string",
                      "enum": [
                          "Plain",
                          "Concatenate",
                          "FullRewrite",
                          "UserRewrite",
                          "QueryFunction"
                      ],
                      "description": "Strategy used to transform the user request before searching knowledge collections."
                  },
                  "queryStrategyParameters": {
                      "type": "object",
                      "properties": {
                          "rewriteContextSize": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Number of recent messages used by the full-rewrite and user-rewrite query strategies."
                          },
                          "concatenateContextSize": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Number of recent user messages joined by the concatenate query strategy."
                          }
                      },
                      "description": "Numeric limits used by query strategies that read recent conversation messages."
                  },
                  "apiKey": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider API key used when points to an external OpenAI-compatible endpoint."
                  },
                  "modelName": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Model name sent to the inference provider, or the AIVAX integrated model identifier when is @integrated."
                  },
                  "temperature": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Sampling temperature forwarded to the model provider when the selected model supports it."
                  },
                  "topP": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Nucleus sampling value forwarded as top_p when the selected model supports it."
                  },
                  "presencePenalty": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Presence penalty forwarded to the model provider when supported."
                  },
                  "frequencyPenalty": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Frequency penalty forwarded to the model provider when supported."
                  },
                  "stop": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Stop sequence used to end generation early when the selected model supports stop parameters."
                  },
                  "maxCompletionTokens": {
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "type": [
                          "integer",
                          "null"
                      ],
                      "description": "Maximum number of output tokens the model may generate."
                  },
                  "contextMaximumSize": {
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "type": [
                          "integer",
                          "null"
                      ],
                      "description": "Optional context-window limit used before sending messages to the model provider."
                  },
                  "contextOverflowAction": {
                      "type": "string",
                      "enum": [
                          "Throw",
                          "Truncate",
                          "TruncateHard",
                          "Compact"
                      ],
                      "description": "Action taken when the prepared prompt exceeds ."
                  },
                  "systemInstruction": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Main system instruction prepended to conversations handled by this gateway."
                  },
                  "workerScriptSource": {
                      "format": "url",
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional worker script URL called during gateway events to allow external policy or orchestration decisions."
                  },
                  "userPromptTemplate": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional template applied to user messages before they are sent to the model."
                  },
                  "assistantPrefill": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional assistant text inserted before generation for models that support assistant prefilling."
                  },
                  "includePrefillingInMessages": {
                      "type": "boolean",
                      "description": "When enabled, stores the assistant prefill as part of the conversation messages instead of using only provider-specific prefill support."
                  },
                  "reasoningEffort": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific reasoning-effort value, such as low, medium or high, when the selected model supports it."
                  },
                  "verbosity": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific verbosity value that controls response detail when the selected model supports it."
                  },
                  "flags": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "enum": [
                              "NoSystemInstruct",
                              "NoTemperature",
                              "ThinkingProcess",
                              "NoAssistantPrefilling",
                              "ReturnReasoningTokens",
                              "DisableMultiModalInput",
                              "DiffusingStream",
                              "OpenAiStrictJson",
                              "StructuredOutputSupport",
                              "PreserveThinkingTokens",
                              "NoStopParameter",
                              "NoReasoningEffort",
                              "RewriteToolCallsAsUserMessages",
                              "DisableReasoningSummary",
                              "DisableReasoningDetails",
                              "IncludeStoredReasoning",
                              "StrictUserAssistantTurns"
                          ]
                      },
                      "description": "Model behavior flags that change how AIVAX prepares provider requests, for example disabling unsupported parameters, preserving reasoning tokens or enforcing strict turn order."
                  },
                  "tools": {
                      "description": "Raw provider-native tool definitions sent directly to the model request. Use protocol functions or MCP sources for tools that AIVAX should execute and return to the model.",
                      "type": [
                          "array",
                          "null"
                      ]
                  },
                  "protocolFunctions": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "pattern": "[a-zA-Z][a-zA-Z0-9_$]\u002B",
                                  "description": "Unique tool name shown to the model. It must be a valid JavaScript identifier because providers use it as the function-call name."
                              },
                              "description": {
                                  "type": "string",
                                  "minLength": 10,
                                  "description": "Description shown to the model so it can decide when to call this function and what result to expect."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "Optional HTTP headers added to the callback request when AIVAX executes this function."
                              },
                              "callbackUrl": {
                                  "type": "string",
                                  "minLength": 1,
                                  "pattern": "(https?|aivax):\\/\\/.*",
                                  "description": "Absolute HTTP, HTTPS or AIVAX URL called with a POST request when the model invokes this function."
                              },
                              "contentFormat": {
                                  "description": "JSON schema for the arguments the model must provide when calling this function."
                              }
                          },
                          "required": [
                              "name",
                              "description",
                              "callbackUrl",
                              "contentFormat"
                          ],
                          "description": "Defines a remote HTTP callback tool that AIVAX can expose to a model and execute when the model requests a tool call."
                      },
                      "description": "Remote HTTP callback tools executed by AIVAX when the model calls them. Use these for simple externally hosted functions; use for Model Context Protocol servers."
                  },
                  "protocolFunctionSources": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      },
                      "description": "URLs that return protocol function definitions. AIVAX fetches these definitions and exposes them as executable callback tools."
                  },
                  "mcpSources": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "description": "Short display name used in logs and generated instruction context."
                              },
                              "description": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Optional description explaining what this external resource provides."
                              },
                              "url": {
                                  "type": "string",
                                  "format": "url",
                                  "description": "Absolute HTTP or HTTPS URL of the resource."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server."
                              },
                              "cacheDuration": {
                                  "type": "integer",
                                  "minimum": -2147483648,
                                  "maximum": 2147483647,
                                  "description": "Cache duration in seconds for fetched resource content or MCP tool discovery results."
                              }
                          },
                          "required": [
                              "name",
                              "url"
                          ],
                          "description": "Represents an external Model Context Protocol server whose tools can be exposed to an AI gateway."
                      },
                      "description": "External Model Context Protocol servers whose listed tools are exposed to the gateway and executed through MCP tool calls."
                  },
                  "systemInstructionsSources": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "description": "Short display name used in logs and generated instruction context."
                              },
                              "description": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Optional description explaining what this external resource provides."
                              },
                              "url": {
                                  "type": "string",
                                  "format": "url",
                                  "description": "Absolute HTTP or HTTPS URL of the resource."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server."
                              },
                              "cacheDuration": {
                                  "type": "integer",
                                  "minimum": -2147483648,
                                  "maximum": 2147483647,
                                  "description": "Cache duration in seconds for fetched resource content or MCP tool discovery results."
                              }
                          },
                          "required": [
                              "name",
                              "url"
                          ],
                          "description": "Represents an external text resource appended to gateway system instructions."
                      },
                      "description": "External text resources fetched and appended to the gateway system instructions."
                  },
                  "enabledMultimodalFeatures": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "enum": [
                              "Image",
                              "Audio",
                              "Video",
                              "File",
                              "OtherFiles",
                              "All"
                          ]
                      },
                      "description": "Input media types that AIVAX may resolve and forward to the model, such as images, audio, video or files."
                  },
                  "toolContextCount": {
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "type": [
                          "integer",
                          "null"
                      ],
                      "description": "Number of previous tool response messages kept in conversation context before older tool results are removed."
                  },
                  "sentinelOptions": {
                      "properties": {
                          "enabledFunctions": {
                              "type": "array",
                              "items": {
                                  "type": "string",
                                  "enum": [
                                      "WebSearch",
                                      "Code",
                                      "OpenUrl",
                                      "Remember",
                                      "ImageGeneration",
                                      "XPostsSearch",
                                      "GenerateDocument",
                                      "GenerateWebPage",
                                      "AdvancedWebUsage",
                                      "Request",
                                      "Calendar"
                                  ]
                              },
                              "description": "Built-in functions exposed to the Sentinel reasoning layer."
                          }
                      },
                      "description": "Built-in tool set exposed through the Sentinel reasoning layer.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "builtinFunctionsOptions": {
                      "properties": {
                          "webSearchMode": {
                              "type": "string",
                              "enum": [
                                  "Full",
                                  "Summarized"
                              ],
                              "description": "Level of detail returned by built-in web search tools."
                          },
                          "webSearchMaxResults": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Maximum number of search results returned by built-in web search tools."
                          },
                          "imageGenerationMaxResults": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Maximum number of images the built-in image generation tool may create in one call."
                          },
                          "imageGenerationQuality": {
                              "type": "string",
                              "enum": [
                                  "Low",
                                  "Medium",
                                  "High",
                                  "Highest"
                              ],
                              "description": "Quality level used by the built-in image generation tool."
                          },
                          "imageGenerationAllowMatureContent": {
                              "type": "boolean",
                              "description": "Allows the built-in image generation tool to produce mature content when the selected model and policy allow it."
                          },
                          "imageGenerationAllowReferenceUsage": {
                              "type": "boolean",
                              "description": "Allows the built-in image generation tool to use reference images from web results or user uploads."
                          },
                          "imageGenerationModelName": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional image-generation model name. When omitted, AIVAX uses its default image model."
                          },
                          "includeAllMemoryContext": {
                              "type": "boolean",
                              "description": "Includes all available memory context in system instructions instead of only memory selected by the runtime."
                          },
                          "allowSharedMemory": {
                              "type": "boolean",
                              "description": "Allows this gateway to consume memories created by other gateways."
                          }
                      },
                      "description": "Configuration for AIVAX built-in tools such as web search, image generation and memory.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "moderationParameters": {
                      "properties": {
                          "violenceThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for violence-related content (0-100)."
                          },
                          "sexualExplicitThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for sexually explicit content (0-100)."
                          },
                          "politicalThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for political content (0-100)."
                          },
                          "dangerousContentThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for dangerous content (0-100)."
                          },
                          "jailbreakThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for jailbreak attempts (0-100)."
                          }
                      },
                      "description": "Moderation thresholds used to block unsafe or disallowed chat content before inference.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "knownToolHandlerName": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Tool-calling handler name. Use native or null for provider-native tool calling; other values select an AIVAX compatibility handler."
                  },
                  "toolInvocationExplanations": {
                      "type": "boolean",
                      "description": "Adds visible explanations of tool invocations to the model response when supported by the selected tool-calling path."
                  },
                  "modelRoutingParameters": {
                      "properties": {
                          "lowComplexityModelName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Integrated model name used when the router classifies a request as low complexity."
                          },
                          "lowComplexityModelReasoningEffort": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional reasoning-effort value applied to low-complexity routed requests."
                          },
                          "mediumComplexityModelName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Integrated model name used when the router classifies a request as medium complexity."
                          },
                          "mediumComplexityModelReasoningEffort": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional reasoning-effort value applied to medium-complexity routed requests."
                          },
                          "highComplexityModelName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Integrated model name used when the router classifies a request as high complexity."
                          },
                          "highComplexityModelReasoningEffort": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional reasoning-effort value applied to high-complexity routed requests."
                          }
                      },
                      "required": [
                          "lowComplexityModelName",
                          "mediumComplexityModelName",
                          "highComplexityModelName"
                      ],
                      "description": "Model names used by the complexity router when selects the AIVAX model-routing gateway.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "additionalSettings": {
                      "description": "Provider- or integration-specific JSON settings that are not represented by first-class gateway parameters.",
                      "type": [
                          "object",
                          "null"
                      ]
                  }
              },
              "required": [
                  "baseAddress",
                  "modelName"
              ],
              "description": "Runtime configuration for model selection, instructions, retrieval, tools and moderation."
          }
      },
      "description": "Request payload for creating a new AI gateway."
  }

Responses:

• 200

  The gateway was created and the response contains its identifier.

  ExampleSchema

  {
      // The unique identifier assigned to the created gateway.
      "aiGatewayId": "uuid"
  }

  {
      "type": "object",
      "properties": {
          "aiGatewayId": {
              "type": "string",
              "format": "uuid",
              "description": "The unique identifier assigned to the created gateway."
          }
      },
      "description": "Result returned after successfully creating an AI gateway."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Query parameters:

• filter

  An optional filter string to search gateways by name, model name, slug, or ID.

Responses:

• 200

  Gateway summaries for the authenticated account.

  ExampleSchema

  [
      {
          // The unique identifier of the gateway.
          "id": "uuid",
  
          // The human-readable name of the gateway.
          "name": string,
  
          // Nullable. Provider host or Integrated inference when the gateway uses AIVAX managed models. Null when using integrated inference.
          "inferenceEndpoint": string?,
  
          // The name of the model associated with the gateway.
          "modelName": string,
  
          // The URL-friendly identifier for the gateway.
          "slug": string
      },
      ...
  ]

  {
      "type": "array",
      "items": {
          "type": "object",
          "properties": {
              "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "The unique identifier of the gateway."
              },
              "name": {
                  "type": "string",
                  "description": "The human-readable name of the gateway."
              },
              "inferenceEndpoint": {
                  "type": [
                      "string",
                      "null"
                  ],
                  "description": "Provider host or Integrated inference when the gateway uses AIVAX managed models. Null when using integrated inference."
              },
              "modelName": {
                  "type": "string",
                  "description": "The name of the model associated with the gateway."
              },
              "slug": {
                  "type": "string",
                  "description": "The URL-friendly identifier for the gateway."
              }
          },
          "description": "Summary information for a single AI gateway entry in a listing."
      }
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• id

  Identifier of the AI Gateway to edit.

Request examples:

• Partial or complete AI gateway modification payload. The schema type documents the available fields, but update payloads may send only name and/or a top-level subset of parameters.

  ExampleSchema

  {
      // The human-readable name of the gateway.
      "name": string,
  
      // Runtime configuration for model selection, instructions, retrieval, tools and moderation.
      "parameters": {
          // Required. Inference endpoint URL used by the gateway. Use @integrated to route through AIVAX managed models.
          "baseAddress": string,
  
          // Skill identifiers enabled for this gateway. Skills add instructions and may expose a subset of gateway tools.
          "skills": [
              "uuid",
              ...
          ],
  
          // When enabled, hides tools that are not associated with one of the enabled skills, except names listed in .
          "hideToolsWithoutSkill": boolean,
  
          // Tool names that remain available even when is enabled.
          "alwaysVisibleTools": [
              string,
              ...
          ],
  
          // Enables the built-in virtual Bash tool so the model can run shell commands in a controlled environment.
          "enableBash": boolean,
  
          // When enabled, automatically includes root AGENTS.md and MEMORY.md workspace files as system instructions. Each file is limited to 16K characters.
          "includeWorkspaceInstructions": boolean,
  
          // Nullable. Optional persistence and command-filter settings for the virtual Bash tool.
          "bashOptions": {
              // Allows files created by the Bash tool to persist between tool executions for the same environment.
              "allowDataPersistence": boolean,
  
              // Bash tool command names affected by .
              "toolList": [
                  string,
                  ...
              ],
  
              // Determines whether is an allow-list or block-list.
              "toolExclusionMode": "WhiteList"
          }?,
  
          // Collection identifiers queried for retrieval-augmented generation before the model is called.
          "knowledgeCollections": [
              "uuid",
              ...
          ],
  
          // Nullable. Reranker algorithm name used to reorder retrieved knowledge results.
          "rerankerName": string?,
  
          // Maximum number of knowledge documents injected into the prompt.
          "knowledgeBaseMaximumResults": number,
  
          // Minimum similarity score, from 0 to 1, required for a knowledge result to be included.
          "knowledgeBaseMinimumScore": number,
  
          // Includes referenced parent documents when a matched knowledge document points to another stored document.
          "knowledgeUseReferences": boolean,
  
          // Includes document metadata descriptions in the retrieved knowledge context when available.
          "knowledgeUseMetaDescriptions": boolean,
  
          // Strategy used to transform the user request before searching knowledge collections.
          "queryStrategy": "Plain",
  
          // Numeric limits used by query strategies that read recent conversation messages.
          "queryStrategyParameters": {
              // Number of recent messages used by the full-rewrite and user-rewrite query strategies.
              "rewriteContextSize": number,
  
              // Number of recent user messages joined by the concatenate query strategy.
              "concatenateContextSize": number
          },
  
          // Nullable. Provider API key used when points to an external OpenAI-compatible endpoint.
          "apiKey": string?,
  
          // Required. Model name sent to the inference provider, or the AIVAX integrated model identifier when is @integrated.
          "modelName": string,
  
          // Nullable. Sampling temperature forwarded to the model provider when the selected model supports it.
          "temperature": number?,
  
          // Nullable. Nucleus sampling value forwarded as top_p when the selected model supports it.
          "topP": number?,
  
          // Nullable. Presence penalty forwarded to the model provider when supported.
          "presencePenalty": number?,
  
          // Nullable. Frequency penalty forwarded to the model provider when supported.
          "frequencyPenalty": number?,
  
          // Nullable. Stop sequence used to end generation early when the selected model supports stop parameters.
          "stop": string?,
  
          // Nullable. Maximum number of output tokens the model may generate.
          "maxCompletionTokens": number?,
  
          // Nullable. Optional context-window limit used before sending messages to the model provider.
          "contextMaximumSize": number?,
  
          // Action taken when the prepared prompt exceeds .
          "contextOverflowAction": "Throw",
  
          // Nullable. Main system instruction prepended to conversations handled by this gateway.
          "systemInstruction": string?,
  
          // Nullable. Optional worker script URL called during gateway events to allow external policy or orchestration decisions.
          "workerScriptSource": "url"?,
  
          // Nullable. Optional template applied to user messages before they are sent to the model.
          "userPromptTemplate": string?,
  
          // Nullable. Optional assistant text inserted before generation for models that support assistant prefilling.
          "assistantPrefill": string?,
  
          // When enabled, stores the assistant prefill as part of the conversation messages instead of using only provider-specific prefill support.
          "includePrefillingInMessages": boolean,
  
          // Nullable. Provider-specific reasoning-effort value, such as low, medium or high, when the selected model supports it.
          "reasoningEffort": string?,
  
          // Nullable. Provider-specific verbosity value that controls response detail when the selected model supports it.
          "verbosity": string?,
  
          // Model behavior flags that change how AIVAX prepares provider requests, for example disabling unsupported parameters, preserving reasoning tokens or enforcing strict turn order.
          "flags": [
              "NoSystemInstruct",
              ...
          ],
  
          // Nullable. Raw provider-native tool definitions sent directly to the model request. Use protocol functions or MCP sources for tools that AIVAX should execute and return to the model.
          "tools": [
              ...
          ]?,
  
          // Remote HTTP callback tools executed by AIVAX when the model calls them. Use these for simple externally hosted functions; use for Model Context Protocol servers.
          "protocolFunctions": [
              {
                  // Required. Unique tool name shown to the model. It must be a valid JavaScript identifier because providers use it as the function-call name.
                  "name": string,
  
                  // Required. Description shown to the model so it can decide when to call this function and what result to expect.
                  "description": string,
  
                  // Optional HTTP headers added to the callback request when AIVAX executes this function.
                  "headers": {},
  
                  // Required. Absolute HTTP, HTTPS or AIVAX URL called with a POST request when the model invokes this function.
                  "callbackUrl": string,
  
                  // Required. JSON schema for the arguments the model must provide when calling this function.
                  "contentFormat": any
              },
              ...
          ],
  
          // URLs that return protocol function definitions. AIVAX fetches these definitions and exposes them as executable callback tools.
          "protocolFunctionSources": [
              string,
              ...
          ],
  
          // External Model Context Protocol servers whose listed tools are exposed to the gateway and executed through MCP tool calls.
          "mcpSources": [
              {
                  // Required. Short display name used in logs and generated instruction context.
                  "name": string,
  
                  // Nullable. Optional description explaining what this external resource provides.
                  "description": string?,
  
                  // Required. Absolute HTTP or HTTPS URL of the resource.
                  "url": "url",
  
                  // HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server.
                  "headers": {},
  
                  // Cache duration in seconds for fetched resource content or MCP tool discovery results.
                  "cacheDuration": number
              },
              ...
          ],
  
          // External text resources fetched and appended to the gateway system instructions.
          "systemInstructionsSources": [
              {
                  // Required. Short display name used in logs and generated instruction context.
                  "name": string,
  
                  // Nullable. Optional description explaining what this external resource provides.
                  "description": string?,
  
                  // Required. Absolute HTTP or HTTPS URL of the resource.
                  "url": "url",
  
                  // HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server.
                  "headers": {},
  
                  // Cache duration in seconds for fetched resource content or MCP tool discovery results.
                  "cacheDuration": number
              },
              ...
          ],
  
          // Input media types that AIVAX may resolve and forward to the model, such as images, audio, video or files.
          "enabledMultimodalFeatures": [
              "Image",
              ...
          ],
  
          // Nullable. Number of previous tool response messages kept in conversation context before older tool results are removed.
          "toolContextCount": number?,
  
          // Nullable. Built-in tool set exposed through the Sentinel reasoning layer.
          "sentinelOptions": {
              // Built-in functions exposed to the Sentinel reasoning layer.
              "enabledFunctions": [
                  "WebSearch",
                  ...
              ]
          }?,
  
          // Nullable. Configuration for AIVAX built-in tools such as web search, image generation and memory.
          "builtinFunctionsOptions": {
              // Level of detail returned by built-in web search tools.
              "webSearchMode": "Full",
  
              // Maximum number of search results returned by built-in web search tools.
              "webSearchMaxResults": number,
  
              // Maximum number of images the built-in image generation tool may create in one call.
              "imageGenerationMaxResults": number,
  
              // Quality level used by the built-in image generation tool.
              "imageGenerationQuality": "Low",
  
              // Allows the built-in image generation tool to produce mature content when the selected model and policy allow it.
              "imageGenerationAllowMatureContent": boolean,
  
              // Allows the built-in image generation tool to use reference images from web results or user uploads.
              "imageGenerationAllowReferenceUsage": boolean,
  
              // Nullable. Optional image-generation model name. When omitted, AIVAX uses its default image model.
              "imageGenerationModelName": string?,
  
              // Includes all available memory context in system instructions instead of only memory selected by the runtime.
              "includeAllMemoryContext": boolean,
  
              // Allows this gateway to consume memories created by other gateways.
              "allowSharedMemory": boolean
          }?,
  
          // Nullable. Moderation thresholds used to block unsafe or disallowed chat content before inference.
          "moderationParameters": {
              // Gets the threshold for violence-related content (0-100).
              "violenceThreshold": number,
  
              // Gets the threshold for sexually explicit content (0-100).
              "sexualExplicitThreshold": number,
  
              // Gets the threshold for political content (0-100).
              "politicalThreshold": number,
  
              // Gets the threshold for dangerous content (0-100).
              "dangerousContentThreshold": number,
  
              // Gets the threshold for jailbreak attempts (0-100).
              "jailbreakThreshold": number
          }?,
  
          // Nullable. Tool-calling handler name. Use native or null for provider-native tool calling; other values select an AIVAX compatibility handler.
          "knownToolHandlerName": string?,
  
          // Adds visible explanations of tool invocations to the model response when supported by the selected tool-calling path.
          "toolInvocationExplanations": boolean,
  
          // Nullable. Model names used by the complexity router when selects the AIVAX model-routing gateway.
          "modelRoutingParameters": {
              // Required. Integrated model name used when the router classifies a request as low complexity.
              "lowComplexityModelName": string,
  
              // Nullable. Optional reasoning-effort value applied to low-complexity routed requests.
              "lowComplexityModelReasoningEffort": string?,
  
              // Required. Integrated model name used when the router classifies a request as medium complexity.
              "mediumComplexityModelName": string,
  
              // Nullable. Optional reasoning-effort value applied to medium-complexity routed requests.
              "mediumComplexityModelReasoningEffort": string?,
  
              // Required. Integrated model name used when the router classifies a request as high complexity.
              "highComplexityModelName": string,
  
              // Nullable. Optional reasoning-effort value applied to high-complexity routed requests.
              "highComplexityModelReasoningEffort": string?
          }?,
  
          // Nullable. Provider- or integration-specific JSON settings that are not represented by first-class gateway parameters.
          "additionalSettings": {}?
      }
  }

  {
      "type": "object",
      "properties": {
          "name": {
              "type": "string",
              "description": "The human-readable name of the gateway."
          },
          "parameters": {
              "type": "object",
              "properties": {
                  "baseAddress": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Inference endpoint URL used by the gateway. Use @integrated to route through AIVAX managed models."
                  },
                  "skills": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "format": "uuid",
                          "description": "UUID/GUID string"
                      },
                      "description": "Skill identifiers enabled for this gateway. Skills add instructions and may expose a subset of gateway tools."
                  },
                  "hideToolsWithoutSkill": {
                      "type": "boolean",
                      "description": "When enabled, hides tools that are not associated with one of the enabled skills, except names listed in ."
                  },
                  "alwaysVisibleTools": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      },
                      "description": "Tool names that remain available even when is enabled."
                  },
                  "enableBash": {
                      "type": "boolean",
                      "description": "Enables the built-in virtual Bash tool so the model can run shell commands in a controlled environment."
                  },
                  "includeWorkspaceInstructions": {
                      "type": "boolean",
                      "description": "When enabled, automatically includes root AGENTS.md and MEMORY.md workspace files as system instructions. Each file is limited to 16K characters."
                  },
                  "bashOptions": {
                      "properties": {
                          "allowDataPersistence": {
                              "type": "boolean",
                              "description": "Allows files created by the Bash tool to persist between tool executions for the same environment."
                          },
                          "toolList": {
                              "type": "array",
                              "items": {
                                  "type": "string"
                              },
                              "description": "Bash tool command names affected by ."
                          },
                          "toolExclusionMode": {
                              "type": "string",
                              "enum": [
                                  "WhiteList",
                                  "BlackList"
                              ],
                              "description": "Determines whether is an allow-list or block-list."
                          }
                      },
                      "description": "Optional persistence and command-filter settings for the virtual Bash tool.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "knowledgeCollections": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "format": "uuid",
                          "description": "UUID/GUID string"
                      },
                      "description": "Collection identifiers queried for retrieval-augmented generation before the model is called."
                  },
                  "rerankerName": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Reranker algorithm name used to reorder retrieved knowledge results."
                  },
                  "knowledgeBaseMaximumResults": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Maximum number of knowledge documents injected into the prompt."
                  },
                  "knowledgeBaseMinimumScore": {
                      "type": "number",
                      "description": "Minimum similarity score, from 0 to 1, required for a knowledge result to be included."
                  },
                  "knowledgeUseReferences": {
                      "type": "boolean",
                      "description": "Includes referenced parent documents when a matched knowledge document points to another stored document."
                  },
                  "knowledgeUseMetaDescriptions": {
                      "type": "boolean",
                      "description": "Includes document metadata descriptions in the retrieved knowledge context when available."
                  },
                  "queryStrategy": {
                      "type": "string",
                      "enum": [
                          "Plain",
                          "Concatenate",
                          "FullRewrite",
                          "UserRewrite",
                          "QueryFunction"
                      ],
                      "description": "Strategy used to transform the user request before searching knowledge collections."
                  },
                  "queryStrategyParameters": {
                      "type": "object",
                      "properties": {
                          "rewriteContextSize": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Number of recent messages used by the full-rewrite and user-rewrite query strategies."
                          },
                          "concatenateContextSize": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Number of recent user messages joined by the concatenate query strategy."
                          }
                      },
                      "description": "Numeric limits used by query strategies that read recent conversation messages."
                  },
                  "apiKey": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider API key used when points to an external OpenAI-compatible endpoint."
                  },
                  "modelName": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Model name sent to the inference provider, or the AIVAX integrated model identifier when is @integrated."
                  },
                  "temperature": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Sampling temperature forwarded to the model provider when the selected model supports it."
                  },
                  "topP": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Nucleus sampling value forwarded as top_p when the selected model supports it."
                  },
                  "presencePenalty": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Presence penalty forwarded to the model provider when supported."
                  },
                  "frequencyPenalty": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Frequency penalty forwarded to the model provider when supported."
                  },
                  "stop": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Stop sequence used to end generation early when the selected model supports stop parameters."
                  },
                  "maxCompletionTokens": {
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "type": [
                          "integer",
                          "null"
                      ],
                      "description": "Maximum number of output tokens the model may generate."
                  },
                  "contextMaximumSize": {
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "type": [
                          "integer",
                          "null"
                      ],
                      "description": "Optional context-window limit used before sending messages to the model provider."
                  },
                  "contextOverflowAction": {
                      "type": "string",
                      "enum": [
                          "Throw",
                          "Truncate",
                          "TruncateHard",
                          "Compact"
                      ],
                      "description": "Action taken when the prepared prompt exceeds ."
                  },
                  "systemInstruction": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Main system instruction prepended to conversations handled by this gateway."
                  },
                  "workerScriptSource": {
                      "format": "url",
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional worker script URL called during gateway events to allow external policy or orchestration decisions."
                  },
                  "userPromptTemplate": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional template applied to user messages before they are sent to the model."
                  },
                  "assistantPrefill": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional assistant text inserted before generation for models that support assistant prefilling."
                  },
                  "includePrefillingInMessages": {
                      "type": "boolean",
                      "description": "When enabled, stores the assistant prefill as part of the conversation messages instead of using only provider-specific prefill support."
                  },
                  "reasoningEffort": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific reasoning-effort value, such as low, medium or high, when the selected model supports it."
                  },
                  "verbosity": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific verbosity value that controls response detail when the selected model supports it."
                  },
                  "flags": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "enum": [
                              "NoSystemInstruct",
                              "NoTemperature",
                              "ThinkingProcess",
                              "NoAssistantPrefilling",
                              "ReturnReasoningTokens",
                              "DisableMultiModalInput",
                              "DiffusingStream",
                              "OpenAiStrictJson",
                              "StructuredOutputSupport",
                              "PreserveThinkingTokens",
                              "NoStopParameter",
                              "NoReasoningEffort",
                              "RewriteToolCallsAsUserMessages",
                              "DisableReasoningSummary",
                              "DisableReasoningDetails",
                              "IncludeStoredReasoning",
                              "StrictUserAssistantTurns"
                          ]
                      },
                      "description": "Model behavior flags that change how AIVAX prepares provider requests, for example disabling unsupported parameters, preserving reasoning tokens or enforcing strict turn order."
                  },
                  "tools": {
                      "description": "Raw provider-native tool definitions sent directly to the model request. Use protocol functions or MCP sources for tools that AIVAX should execute and return to the model.",
                      "type": [
                          "array",
                          "null"
                      ]
                  },
                  "protocolFunctions": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "pattern": "[a-zA-Z][a-zA-Z0-9_$]\u002B",
                                  "description": "Unique tool name shown to the model. It must be a valid JavaScript identifier because providers use it as the function-call name."
                              },
                              "description": {
                                  "type": "string",
                                  "minLength": 10,
                                  "description": "Description shown to the model so it can decide when to call this function and what result to expect."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "Optional HTTP headers added to the callback request when AIVAX executes this function."
                              },
                              "callbackUrl": {
                                  "type": "string",
                                  "minLength": 1,
                                  "pattern": "(https?|aivax):\\/\\/.*",
                                  "description": "Absolute HTTP, HTTPS or AIVAX URL called with a POST request when the model invokes this function."
                              },
                              "contentFormat": {
                                  "description": "JSON schema for the arguments the model must provide when calling this function."
                              }
                          },
                          "required": [
                              "name",
                              "description",
                              "callbackUrl",
                              "contentFormat"
                          ],
                          "description": "Defines a remote HTTP callback tool that AIVAX can expose to a model and execute when the model requests a tool call."
                      },
                      "description": "Remote HTTP callback tools executed by AIVAX when the model calls them. Use these for simple externally hosted functions; use for Model Context Protocol servers."
                  },
                  "protocolFunctionSources": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      },
                      "description": "URLs that return protocol function definitions. AIVAX fetches these definitions and exposes them as executable callback tools."
                  },
                  "mcpSources": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "description": "Short display name used in logs and generated instruction context."
                              },
                              "description": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Optional description explaining what this external resource provides."
                              },
                              "url": {
                                  "type": "string",
                                  "format": "url",
                                  "description": "Absolute HTTP or HTTPS URL of the resource."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server."
                              },
                              "cacheDuration": {
                                  "type": "integer",
                                  "minimum": -2147483648,
                                  "maximum": 2147483647,
                                  "description": "Cache duration in seconds for fetched resource content or MCP tool discovery results."
                              }
                          },
                          "required": [
                              "name",
                              "url"
                          ],
                          "description": "Represents an external Model Context Protocol server whose tools can be exposed to an AI gateway."
                      },
                      "description": "External Model Context Protocol servers whose listed tools are exposed to the gateway and executed through MCP tool calls."
                  },
                  "systemInstructionsSources": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "description": "Short display name used in logs and generated instruction context."
                              },
                              "description": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Optional description explaining what this external resource provides."
                              },
                              "url": {
                                  "type": "string",
                                  "format": "url",
                                  "description": "Absolute HTTP or HTTPS URL of the resource."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server."
                              },
                              "cacheDuration": {
                                  "type": "integer",
                                  "minimum": -2147483648,
                                  "maximum": 2147483647,
                                  "description": "Cache duration in seconds for fetched resource content or MCP tool discovery results."
                              }
                          },
                          "required": [
                              "name",
                              "url"
                          ],
                          "description": "Represents an external text resource appended to gateway system instructions."
                      },
                      "description": "External text resources fetched and appended to the gateway system instructions."
                  },
                  "enabledMultimodalFeatures": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "enum": [
                              "Image",
                              "Audio",
                              "Video",
                              "File",
                              "OtherFiles",
                              "All"
                          ]
                      },
                      "description": "Input media types that AIVAX may resolve and forward to the model, such as images, audio, video or files."
                  },
                  "toolContextCount": {
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "type": [
                          "integer",
                          "null"
                      ],
                      "description": "Number of previous tool response messages kept in conversation context before older tool results are removed."
                  },
                  "sentinelOptions": {
                      "properties": {
                          "enabledFunctions": {
                              "type": "array",
                              "items": {
                                  "type": "string",
                                  "enum": [
                                      "WebSearch",
                                      "Code",
                                      "OpenUrl",
                                      "Remember",
                                      "ImageGeneration",
                                      "XPostsSearch",
                                      "GenerateDocument",
                                      "GenerateWebPage",
                                      "AdvancedWebUsage",
                                      "Request",
                                      "Calendar"
                                  ]
                              },
                              "description": "Built-in functions exposed to the Sentinel reasoning layer."
                          }
                      },
                      "description": "Built-in tool set exposed through the Sentinel reasoning layer.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "builtinFunctionsOptions": {
                      "properties": {
                          "webSearchMode": {
                              "type": "string",
                              "enum": [
                                  "Full",
                                  "Summarized"
                              ],
                              "description": "Level of detail returned by built-in web search tools."
                          },
                          "webSearchMaxResults": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Maximum number of search results returned by built-in web search tools."
                          },
                          "imageGenerationMaxResults": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Maximum number of images the built-in image generation tool may create in one call."
                          },
                          "imageGenerationQuality": {
                              "type": "string",
                              "enum": [
                                  "Low",
                                  "Medium",
                                  "High",
                                  "Highest"
                              ],
                              "description": "Quality level used by the built-in image generation tool."
                          },
                          "imageGenerationAllowMatureContent": {
                              "type": "boolean",
                              "description": "Allows the built-in image generation tool to produce mature content when the selected model and policy allow it."
                          },
                          "imageGenerationAllowReferenceUsage": {
                              "type": "boolean",
                              "description": "Allows the built-in image generation tool to use reference images from web results or user uploads."
                          },
                          "imageGenerationModelName": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional image-generation model name. When omitted, AIVAX uses its default image model."
                          },
                          "includeAllMemoryContext": {
                              "type": "boolean",
                              "description": "Includes all available memory context in system instructions instead of only memory selected by the runtime."
                          },
                          "allowSharedMemory": {
                              "type": "boolean",
                              "description": "Allows this gateway to consume memories created by other gateways."
                          }
                      },
                      "description": "Configuration for AIVAX built-in tools such as web search, image generation and memory.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "moderationParameters": {
                      "properties": {
                          "violenceThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for violence-related content (0-100)."
                          },
                          "sexualExplicitThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for sexually explicit content (0-100)."
                          },
                          "politicalThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for political content (0-100)."
                          },
                          "dangerousContentThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for dangerous content (0-100)."
                          },
                          "jailbreakThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for jailbreak attempts (0-100)."
                          }
                      },
                      "description": "Moderation thresholds used to block unsafe or disallowed chat content before inference.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "knownToolHandlerName": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Tool-calling handler name. Use native or null for provider-native tool calling; other values select an AIVAX compatibility handler."
                  },
                  "toolInvocationExplanations": {
                      "type": "boolean",
                      "description": "Adds visible explanations of tool invocations to the model response when supported by the selected tool-calling path."
                  },
                  "modelRoutingParameters": {
                      "properties": {
                          "lowComplexityModelName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Integrated model name used when the router classifies a request as low complexity."
                          },
                          "lowComplexityModelReasoningEffort": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional reasoning-effort value applied to low-complexity routed requests."
                          },
                          "mediumComplexityModelName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Integrated model name used when the router classifies a request as medium complexity."
                          },
                          "mediumComplexityModelReasoningEffort": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional reasoning-effort value applied to medium-complexity routed requests."
                          },
                          "highComplexityModelName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Integrated model name used when the router classifies a request as high complexity."
                          },
                          "highComplexityModelReasoningEffort": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional reasoning-effort value applied to high-complexity routed requests."
                          }
                      },
                      "required": [
                          "lowComplexityModelName",
                          "mediumComplexityModelName",
                          "highComplexityModelName"
                      ],
                      "description": "Model names used by the complexity router when selects the AIVAX model-routing gateway.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "additionalSettings": {
                      "description": "Provider- or integration-specific JSON settings that are not represented by first-class gateway parameters.",
                      "type": [
                          "object",
                          "null"
                      ]
                  }
              },
              "required": [
                  "baseAddress",
                  "modelName"
              ],
              "description": "Runtime configuration for model selection, instructions, retrieval, tools and moderation."
          }
      },
      "description": "Request payload for creating a new AI gateway."
  }

Responses:

• 200

  The gateway configuration was saved.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• id

  Identifier of the AI Gateway to retrieve.

Responses:

• 200

  Full AI Gateway configuration.

  ExampleSchema

  {
      // The human-readable name of the gateway.
      "name": string,
  
      // The URL-friendly identifier for the gateway.
      "slug": string,
  
      // Runtime configuration for model selection, instructions, retrieval, tools and moderation.
      "parameters": {
          // Required. Inference endpoint URL used by the gateway. Use @integrated to route through AIVAX managed models.
          "baseAddress": string,
  
          // Skill identifiers enabled for this gateway. Skills add instructions and may expose a subset of gateway tools.
          "skills": [
              "uuid",
              ...
          ],
  
          // When enabled, hides tools that are not associated with one of the enabled skills, except names listed in .
          "hideToolsWithoutSkill": boolean,
  
          // Tool names that remain available even when is enabled.
          "alwaysVisibleTools": [
              string,
              ...
          ],
  
          // Enables the built-in virtual Bash tool so the model can run shell commands in a controlled environment.
          "enableBash": boolean,
  
          // When enabled, automatically includes root AGENTS.md and MEMORY.md workspace files as system instructions. Each file is limited to 16K characters.
          "includeWorkspaceInstructions": boolean,
  
          // Nullable. Optional persistence and command-filter settings for the virtual Bash tool.
          "bashOptions": {
              // Allows files created by the Bash tool to persist between tool executions for the same environment.
              "allowDataPersistence": boolean,
  
              // Bash tool command names affected by .
              "toolList": [
                  string,
                  ...
              ],
  
              // Determines whether is an allow-list or block-list.
              "toolExclusionMode": "WhiteList"
          }?,
  
          // Collection identifiers queried for retrieval-augmented generation before the model is called.
          "knowledgeCollections": [
              "uuid",
              ...
          ],
  
          // Nullable. Reranker algorithm name used to reorder retrieved knowledge results.
          "rerankerName": string?,
  
          // Maximum number of knowledge documents injected into the prompt.
          "knowledgeBaseMaximumResults": number,
  
          // Minimum similarity score, from 0 to 1, required for a knowledge result to be included.
          "knowledgeBaseMinimumScore": number,
  
          // Includes referenced parent documents when a matched knowledge document points to another stored document.
          "knowledgeUseReferences": boolean,
  
          // Includes document metadata descriptions in the retrieved knowledge context when available.
          "knowledgeUseMetaDescriptions": boolean,
  
          // Strategy used to transform the user request before searching knowledge collections.
          "queryStrategy": "Plain",
  
          // Numeric limits used by query strategies that read recent conversation messages.
          "queryStrategyParameters": {
              // Number of recent messages used by the full-rewrite and user-rewrite query strategies.
              "rewriteContextSize": number,
  
              // Number of recent user messages joined by the concatenate query strategy.
              "concatenateContextSize": number
          },
  
          // Nullable. Provider API key used when points to an external OpenAI-compatible endpoint.
          "apiKey": string?,
  
          // Required. Model name sent to the inference provider, or the AIVAX integrated model identifier when is @integrated.
          "modelName": string,
  
          // Nullable. Sampling temperature forwarded to the model provider when the selected model supports it.
          "temperature": number?,
  
          // Nullable. Nucleus sampling value forwarded as top_p when the selected model supports it.
          "topP": number?,
  
          // Nullable. Presence penalty forwarded to the model provider when supported.
          "presencePenalty": number?,
  
          // Nullable. Frequency penalty forwarded to the model provider when supported.
          "frequencyPenalty": number?,
  
          // Nullable. Stop sequence used to end generation early when the selected model supports stop parameters.
          "stop": string?,
  
          // Nullable. Maximum number of output tokens the model may generate.
          "maxCompletionTokens": number?,
  
          // Nullable. Optional context-window limit used before sending messages to the model provider.
          "contextMaximumSize": number?,
  
          // Action taken when the prepared prompt exceeds .
          "contextOverflowAction": "Throw",
  
          // Nullable. Main system instruction prepended to conversations handled by this gateway.
          "systemInstruction": string?,
  
          // Nullable. Optional worker script URL called during gateway events to allow external policy or orchestration decisions.
          "workerScriptSource": "url"?,
  
          // Nullable. Optional template applied to user messages before they are sent to the model.
          "userPromptTemplate": string?,
  
          // Nullable. Optional assistant text inserted before generation for models that support assistant prefilling.
          "assistantPrefill": string?,
  
          // When enabled, stores the assistant prefill as part of the conversation messages instead of using only provider-specific prefill support.
          "includePrefillingInMessages": boolean,
  
          // Nullable. Provider-specific reasoning-effort value, such as low, medium or high, when the selected model supports it.
          "reasoningEffort": string?,
  
          // Nullable. Provider-specific verbosity value that controls response detail when the selected model supports it.
          "verbosity": string?,
  
          // Model behavior flags that change how AIVAX prepares provider requests, for example disabling unsupported parameters, preserving reasoning tokens or enforcing strict turn order.
          "flags": [
              "NoSystemInstruct",
              ...
          ],
  
          // Nullable. Raw provider-native tool definitions sent directly to the model request. Use protocol functions or MCP sources for tools that AIVAX should execute and return to the model.
          "tools": [
              ...
          ]?,
  
          // Remote HTTP callback tools executed by AIVAX when the model calls them. Use these for simple externally hosted functions; use for Model Context Protocol servers.
          "protocolFunctions": [
              {
                  // Required. Unique tool name shown to the model. It must be a valid JavaScript identifier because providers use it as the function-call name.
                  "name": string,
  
                  // Required. Description shown to the model so it can decide when to call this function and what result to expect.
                  "description": string,
  
                  // Optional HTTP headers added to the callback request when AIVAX executes this function.
                  "headers": {},
  
                  // Required. Absolute HTTP, HTTPS or AIVAX URL called with a POST request when the model invokes this function.
                  "callbackUrl": string,
  
                  // Required. JSON schema for the arguments the model must provide when calling this function.
                  "contentFormat": any
              },
              ...
          ],
  
          // URLs that return protocol function definitions. AIVAX fetches these definitions and exposes them as executable callback tools.
          "protocolFunctionSources": [
              string,
              ...
          ],
  
          // External Model Context Protocol servers whose listed tools are exposed to the gateway and executed through MCP tool calls.
          "mcpSources": [
              {
                  // Required. Short display name used in logs and generated instruction context.
                  "name": string,
  
                  // Nullable. Optional description explaining what this external resource provides.
                  "description": string?,
  
                  // Required. Absolute HTTP or HTTPS URL of the resource.
                  "url": "url",
  
                  // HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server.
                  "headers": {},
  
                  // Cache duration in seconds for fetched resource content or MCP tool discovery results.
                  "cacheDuration": number
              },
              ...
          ],
  
          // External text resources fetched and appended to the gateway system instructions.
          "systemInstructionsSources": [
              {
                  // Required. Short display name used in logs and generated instruction context.
                  "name": string,
  
                  // Nullable. Optional description explaining what this external resource provides.
                  "description": string?,
  
                  // Required. Absolute HTTP or HTTPS URL of the resource.
                  "url": "url",
  
                  // HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server.
                  "headers": {},
  
                  // Cache duration in seconds for fetched resource content or MCP tool discovery results.
                  "cacheDuration": number
              },
              ...
          ],
  
          // Input media types that AIVAX may resolve and forward to the model, such as images, audio, video or files.
          "enabledMultimodalFeatures": [
              "Image",
              ...
          ],
  
          // Nullable. Number of previous tool response messages kept in conversation context before older tool results are removed.
          "toolContextCount": number?,
  
          // Nullable. Built-in tool set exposed through the Sentinel reasoning layer.
          "sentinelOptions": {
              // Built-in functions exposed to the Sentinel reasoning layer.
              "enabledFunctions": [
                  "WebSearch",
                  ...
              ]
          }?,
  
          // Nullable. Configuration for AIVAX built-in tools such as web search, image generation and memory.
          "builtinFunctionsOptions": {
              // Level of detail returned by built-in web search tools.
              "webSearchMode": "Full",
  
              // Maximum number of search results returned by built-in web search tools.
              "webSearchMaxResults": number,
  
              // Maximum number of images the built-in image generation tool may create in one call.
              "imageGenerationMaxResults": number,
  
              // Quality level used by the built-in image generation tool.
              "imageGenerationQuality": "Low",
  
              // Allows the built-in image generation tool to produce mature content when the selected model and policy allow it.
              "imageGenerationAllowMatureContent": boolean,
  
              // Allows the built-in image generation tool to use reference images from web results or user uploads.
              "imageGenerationAllowReferenceUsage": boolean,
  
              // Nullable. Optional image-generation model name. When omitted, AIVAX uses its default image model.
              "imageGenerationModelName": string?,
  
              // Includes all available memory context in system instructions instead of only memory selected by the runtime.
              "includeAllMemoryContext": boolean,
  
              // Allows this gateway to consume memories created by other gateways.
              "allowSharedMemory": boolean
          }?,
  
          // Nullable. Moderation thresholds used to block unsafe or disallowed chat content before inference.
          "moderationParameters": {
              // Gets the threshold for violence-related content (0-100).
              "violenceThreshold": number,
  
              // Gets the threshold for sexually explicit content (0-100).
              "sexualExplicitThreshold": number,
  
              // Gets the threshold for political content (0-100).
              "politicalThreshold": number,
  
              // Gets the threshold for dangerous content (0-100).
              "dangerousContentThreshold": number,
  
              // Gets the threshold for jailbreak attempts (0-100).
              "jailbreakThreshold": number
          }?,
  
          // Nullable. Tool-calling handler name. Use native or null for provider-native tool calling; other values select an AIVAX compatibility handler.
          "knownToolHandlerName": string?,
  
          // Adds visible explanations of tool invocations to the model response when supported by the selected tool-calling path.
          "toolInvocationExplanations": boolean,
  
          // Nullable. Model names used by the complexity router when selects the AIVAX model-routing gateway.
          "modelRoutingParameters": {
              // Required. Integrated model name used when the router classifies a request as low complexity.
              "lowComplexityModelName": string,
  
              // Nullable. Optional reasoning-effort value applied to low-complexity routed requests.
              "lowComplexityModelReasoningEffort": string?,
  
              // Required. Integrated model name used when the router classifies a request as medium complexity.
              "mediumComplexityModelName": string,
  
              // Nullable. Optional reasoning-effort value applied to medium-complexity routed requests.
              "mediumComplexityModelReasoningEffort": string?,
  
              // Required. Integrated model name used when the router classifies a request as high complexity.
              "highComplexityModelName": string,
  
              // Nullable. Optional reasoning-effort value applied to high-complexity routed requests.
              "highComplexityModelReasoningEffort": string?
          }?,
  
          // Nullable. Provider- or integration-specific JSON settings that are not represented by first-class gateway parameters.
          "additionalSettings": {}?
      }
  }

  {
      "type": "object",
      "properties": {
          "name": {
              "type": "string",
              "description": "The human-readable name of the gateway."
          },
          "slug": {
              "type": "string",
              "description": "The URL-friendly identifier for the gateway."
          },
          "parameters": {
              "type": "object",
              "properties": {
                  "baseAddress": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Inference endpoint URL used by the gateway. Use @integrated to route through AIVAX managed models."
                  },
                  "skills": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "format": "uuid",
                          "description": "UUID/GUID string"
                      },
                      "description": "Skill identifiers enabled for this gateway. Skills add instructions and may expose a subset of gateway tools."
                  },
                  "hideToolsWithoutSkill": {
                      "type": "boolean",
                      "description": "When enabled, hides tools that are not associated with one of the enabled skills, except names listed in ."
                  },
                  "alwaysVisibleTools": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      },
                      "description": "Tool names that remain available even when is enabled."
                  },
                  "enableBash": {
                      "type": "boolean",
                      "description": "Enables the built-in virtual Bash tool so the model can run shell commands in a controlled environment."
                  },
                  "includeWorkspaceInstructions": {
                      "type": "boolean",
                      "description": "When enabled, automatically includes root AGENTS.md and MEMORY.md workspace files as system instructions. Each file is limited to 16K characters."
                  },
                  "bashOptions": {
                      "properties": {
                          "allowDataPersistence": {
                              "type": "boolean",
                              "description": "Allows files created by the Bash tool to persist between tool executions for the same environment."
                          },
                          "toolList": {
                              "type": "array",
                              "items": {
                                  "type": "string"
                              },
                              "description": "Bash tool command names affected by ."
                          },
                          "toolExclusionMode": {
                              "type": "string",
                              "enum": [
                                  "WhiteList",
                                  "BlackList"
                              ],
                              "description": "Determines whether is an allow-list or block-list."
                          }
                      },
                      "description": "Optional persistence and command-filter settings for the virtual Bash tool.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "knowledgeCollections": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "format": "uuid",
                          "description": "UUID/GUID string"
                      },
                      "description": "Collection identifiers queried for retrieval-augmented generation before the model is called."
                  },
                  "rerankerName": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Reranker algorithm name used to reorder retrieved knowledge results."
                  },
                  "knowledgeBaseMaximumResults": {
                      "type": "integer",
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "description": "Maximum number of knowledge documents injected into the prompt."
                  },
                  "knowledgeBaseMinimumScore": {
                      "type": "number",
                      "description": "Minimum similarity score, from 0 to 1, required for a knowledge result to be included."
                  },
                  "knowledgeUseReferences": {
                      "type": "boolean",
                      "description": "Includes referenced parent documents when a matched knowledge document points to another stored document."
                  },
                  "knowledgeUseMetaDescriptions": {
                      "type": "boolean",
                      "description": "Includes document metadata descriptions in the retrieved knowledge context when available."
                  },
                  "queryStrategy": {
                      "type": "string",
                      "enum": [
                          "Plain",
                          "Concatenate",
                          "FullRewrite",
                          "UserRewrite",
                          "QueryFunction"
                      ],
                      "description": "Strategy used to transform the user request before searching knowledge collections."
                  },
                  "queryStrategyParameters": {
                      "type": "object",
                      "properties": {
                          "rewriteContextSize": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Number of recent messages used by the full-rewrite and user-rewrite query strategies."
                          },
                          "concatenateContextSize": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Number of recent user messages joined by the concatenate query strategy."
                          }
                      },
                      "description": "Numeric limits used by query strategies that read recent conversation messages."
                  },
                  "apiKey": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider API key used when points to an external OpenAI-compatible endpoint."
                  },
                  "modelName": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Model name sent to the inference provider, or the AIVAX integrated model identifier when is @integrated."
                  },
                  "temperature": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Sampling temperature forwarded to the model provider when the selected model supports it."
                  },
                  "topP": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Nucleus sampling value forwarded as top_p when the selected model supports it."
                  },
                  "presencePenalty": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Presence penalty forwarded to the model provider when supported."
                  },
                  "frequencyPenalty": {
                      "type": [
                          "number",
                          "null"
                      ],
                      "description": "Frequency penalty forwarded to the model provider when supported."
                  },
                  "stop": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Stop sequence used to end generation early when the selected model supports stop parameters."
                  },
                  "maxCompletionTokens": {
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "type": [
                          "integer",
                          "null"
                      ],
                      "description": "Maximum number of output tokens the model may generate."
                  },
                  "contextMaximumSize": {
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "type": [
                          "integer",
                          "null"
                      ],
                      "description": "Optional context-window limit used before sending messages to the model provider."
                  },
                  "contextOverflowAction": {
                      "type": "string",
                      "enum": [
                          "Throw",
                          "Truncate",
                          "TruncateHard",
                          "Compact"
                      ],
                      "description": "Action taken when the prepared prompt exceeds ."
                  },
                  "systemInstruction": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Main system instruction prepended to conversations handled by this gateway."
                  },
                  "workerScriptSource": {
                      "format": "url",
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional worker script URL called during gateway events to allow external policy or orchestration decisions."
                  },
                  "userPromptTemplate": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional template applied to user messages before they are sent to the model."
                  },
                  "assistantPrefill": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Optional assistant text inserted before generation for models that support assistant prefilling."
                  },
                  "includePrefillingInMessages": {
                      "type": "boolean",
                      "description": "When enabled, stores the assistant prefill as part of the conversation messages instead of using only provider-specific prefill support."
                  },
                  "reasoningEffort": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific reasoning-effort value, such as low, medium or high, when the selected model supports it."
                  },
                  "verbosity": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Provider-specific verbosity value that controls response detail when the selected model supports it."
                  },
                  "flags": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "enum": [
                              "NoSystemInstruct",
                              "NoTemperature",
                              "ThinkingProcess",
                              "NoAssistantPrefilling",
                              "ReturnReasoningTokens",
                              "DisableMultiModalInput",
                              "DiffusingStream",
                              "OpenAiStrictJson",
                              "StructuredOutputSupport",
                              "PreserveThinkingTokens",
                              "NoStopParameter",
                              "NoReasoningEffort",
                              "RewriteToolCallsAsUserMessages",
                              "DisableReasoningSummary",
                              "DisableReasoningDetails",
                              "IncludeStoredReasoning",
                              "StrictUserAssistantTurns"
                          ]
                      },
                      "description": "Model behavior flags that change how AIVAX prepares provider requests, for example disabling unsupported parameters, preserving reasoning tokens or enforcing strict turn order."
                  },
                  "tools": {
                      "description": "Raw provider-native tool definitions sent directly to the model request. Use protocol functions or MCP sources for tools that AIVAX should execute and return to the model.",
                      "type": [
                          "array",
                          "null"
                      ]
                  },
                  "protocolFunctions": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "pattern": "[a-zA-Z][a-zA-Z0-9_$]\u002B",
                                  "description": "Unique tool name shown to the model. It must be a valid JavaScript identifier because providers use it as the function-call name."
                              },
                              "description": {
                                  "type": "string",
                                  "minLength": 10,
                                  "description": "Description shown to the model so it can decide when to call this function and what result to expect."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "Optional HTTP headers added to the callback request when AIVAX executes this function."
                              },
                              "callbackUrl": {
                                  "type": "string",
                                  "minLength": 1,
                                  "pattern": "(https?|aivax):\\/\\/.*",
                                  "description": "Absolute HTTP, HTTPS or AIVAX URL called with a POST request when the model invokes this function."
                              },
                              "contentFormat": {
                                  "description": "JSON schema for the arguments the model must provide when calling this function."
                              }
                          },
                          "required": [
                              "name",
                              "description",
                              "callbackUrl",
                              "contentFormat"
                          ],
                          "description": "Defines a remote HTTP callback tool that AIVAX can expose to a model and execute when the model requests a tool call."
                      },
                      "description": "Remote HTTP callback tools executed by AIVAX when the model calls them. Use these for simple externally hosted functions; use for Model Context Protocol servers."
                  },
                  "protocolFunctionSources": {
                      "type": "array",
                      "items": {
                          "type": "string"
                      },
                      "description": "URLs that return protocol function definitions. AIVAX fetches these definitions and exposes them as executable callback tools."
                  },
                  "mcpSources": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "description": "Short display name used in logs and generated instruction context."
                              },
                              "description": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Optional description explaining what this external resource provides."
                              },
                              "url": {
                                  "type": "string",
                                  "format": "url",
                                  "description": "Absolute HTTP or HTTPS URL of the resource."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server."
                              },
                              "cacheDuration": {
                                  "type": "integer",
                                  "minimum": -2147483648,
                                  "maximum": 2147483647,
                                  "description": "Cache duration in seconds for fetched resource content or MCP tool discovery results."
                              }
                          },
                          "required": [
                              "name",
                              "url"
                          ],
                          "description": "Represents an external Model Context Protocol server whose tools can be exposed to an AI gateway."
                      },
                      "description": "External Model Context Protocol servers whose listed tools are exposed to the gateway and executed through MCP tool calls."
                  },
                  "systemInstructionsSources": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "name": {
                                  "type": "string",
                                  "minLength": 3,
                                  "description": "Short display name used in logs and generated instruction context."
                              },
                              "description": {
                                  "type": [
                                      "string",
                                      "null"
                                  ],
                                  "description": "Optional description explaining what this external resource provides."
                              },
                              "url": {
                                  "type": "string",
                                  "format": "url",
                                  "description": "Absolute HTTP or HTTPS URL of the resource."
                              },
                              "headers": {
                                  "type": "object",
                                  "additionalProperties": {
                                      "type": "string"
                                  },
                                  "description": "HTTP headers sent when AIVAX retrieves the resource or connects to the MCP server."
                              },
                              "cacheDuration": {
                                  "type": "integer",
                                  "minimum": -2147483648,
                                  "maximum": 2147483647,
                                  "description": "Cache duration in seconds for fetched resource content or MCP tool discovery results."
                              }
                          },
                          "required": [
                              "name",
                              "url"
                          ],
                          "description": "Represents an external text resource appended to gateway system instructions."
                      },
                      "description": "External text resources fetched and appended to the gateway system instructions."
                  },
                  "enabledMultimodalFeatures": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "enum": [
                              "Image",
                              "Audio",
                              "Video",
                              "File",
                              "OtherFiles",
                              "All"
                          ]
                      },
                      "description": "Input media types that AIVAX may resolve and forward to the model, such as images, audio, video or files."
                  },
                  "toolContextCount": {
                      "minimum": -2147483648,
                      "maximum": 2147483647,
                      "type": [
                          "integer",
                          "null"
                      ],
                      "description": "Number of previous tool response messages kept in conversation context before older tool results are removed."
                  },
                  "sentinelOptions": {
                      "properties": {
                          "enabledFunctions": {
                              "type": "array",
                              "items": {
                                  "type": "string",
                                  "enum": [
                                      "WebSearch",
                                      "Code",
                                      "OpenUrl",
                                      "Remember",
                                      "ImageGeneration",
                                      "XPostsSearch",
                                      "GenerateDocument",
                                      "GenerateWebPage",
                                      "AdvancedWebUsage",
                                      "Request",
                                      "Calendar"
                                  ]
                              },
                              "description": "Built-in functions exposed to the Sentinel reasoning layer."
                          }
                      },
                      "description": "Built-in tool set exposed through the Sentinel reasoning layer.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "builtinFunctionsOptions": {
                      "properties": {
                          "webSearchMode": {
                              "type": "string",
                              "enum": [
                                  "Full",
                                  "Summarized"
                              ],
                              "description": "Level of detail returned by built-in web search tools."
                          },
                          "webSearchMaxResults": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Maximum number of search results returned by built-in web search tools."
                          },
                          "imageGenerationMaxResults": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Maximum number of images the built-in image generation tool may create in one call."
                          },
                          "imageGenerationQuality": {
                              "type": "string",
                              "enum": [
                                  "Low",
                                  "Medium",
                                  "High",
                                  "Highest"
                              ],
                              "description": "Quality level used by the built-in image generation tool."
                          },
                          "imageGenerationAllowMatureContent": {
                              "type": "boolean",
                              "description": "Allows the built-in image generation tool to produce mature content when the selected model and policy allow it."
                          },
                          "imageGenerationAllowReferenceUsage": {
                              "type": "boolean",
                              "description": "Allows the built-in image generation tool to use reference images from web results or user uploads."
                          },
                          "imageGenerationModelName": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional image-generation model name. When omitted, AIVAX uses its default image model."
                          },
                          "includeAllMemoryContext": {
                              "type": "boolean",
                              "description": "Includes all available memory context in system instructions instead of only memory selected by the runtime."
                          },
                          "allowSharedMemory": {
                              "type": "boolean",
                              "description": "Allows this gateway to consume memories created by other gateways."
                          }
                      },
                      "description": "Configuration for AIVAX built-in tools such as web search, image generation and memory.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "moderationParameters": {
                      "properties": {
                          "violenceThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for violence-related content (0-100)."
                          },
                          "sexualExplicitThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for sexually explicit content (0-100)."
                          },
                          "politicalThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for political content (0-100)."
                          },
                          "dangerousContentThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for dangerous content (0-100)."
                          },
                          "jailbreakThreshold": {
                              "type": "integer",
                              "minimum": -2147483648,
                              "maximum": 2147483647,
                              "description": "Gets the threshold for jailbreak attempts (0-100)."
                          }
                      },
                      "description": "Moderation thresholds used to block unsafe or disallowed chat content before inference.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "knownToolHandlerName": {
                      "type": [
                          "string",
                          "null"
                      ],
                      "description": "Tool-calling handler name. Use native or null for provider-native tool calling; other values select an AIVAX compatibility handler."
                  },
                  "toolInvocationExplanations": {
                      "type": "boolean",
                      "description": "Adds visible explanations of tool invocations to the model response when supported by the selected tool-calling path."
                  },
                  "modelRoutingParameters": {
                      "properties": {
                          "lowComplexityModelName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Integrated model name used when the router classifies a request as low complexity."
                          },
                          "lowComplexityModelReasoningEffort": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional reasoning-effort value applied to low-complexity routed requests."
                          },
                          "mediumComplexityModelName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Integrated model name used when the router classifies a request as medium complexity."
                          },
                          "mediumComplexityModelReasoningEffort": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional reasoning-effort value applied to medium-complexity routed requests."
                          },
                          "highComplexityModelName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "Integrated model name used when the router classifies a request as high complexity."
                          },
                          "highComplexityModelReasoningEffort": {
                              "type": [
                                  "string",
                                  "null"
                              ],
                              "description": "Optional reasoning-effort value applied to high-complexity routed requests."
                          }
                      },
                      "required": [
                          "lowComplexityModelName",
                          "mediumComplexityModelName",
                          "highComplexityModelName"
                      ],
                      "description": "Model names used by the complexity router when selects the AIVAX model-routing gateway.",
                      "type": [
                          "object",
                          "null"
                      ]
                  },
                  "additionalSettings": {
                      "description": "Provider- or integration-specific JSON settings that are not represented by first-class gateway parameters.",
                      "type": [
                          "object",
                          "null"
                      ]
                  }
              },
              "required": [
                  "baseAddress",
                  "modelName"
              ],
              "description": "Runtime configuration for model selection, instructions, retrieval, tools and moderation."
          }
      },
      "description": "Detailed view of an AI gateway\u0027s configuration."
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• id

  Identifier of the AI Gateway to delete.

Responses:

• 200

  The AI Gateway was deleted.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• Full account update payload. The parameters object replaces the current account parameters.

  ExampleSchema

  {
      // New display name for the authenticated account.
      "name": string,
  
      // Full replacement account configuration, including notification and semantic data collection settings.
      "parameters": {
          // Enables storage of conversation records for observability, export and troubleshooting.
          "allowConversationsLogging": boolean,
  
          // Enables automatic repair attempts when a model response is expected to be JSON but is malformed.
          "automaticJsonHealing": boolean,
  
          // Allows account-deidentified RAG and Reflex search data to be collected for model training in exchange for eligible search discounts.
          "allowSemanticDataCollection": boolean,
  
          // Notification preferences for account-level events.
          "notifications": {
              // Additional notification destination e-mails.
              "emails": [
                  string,
                  ...
              ],
  
              // Low-balance notification settings.
              "lowBalance": {
                  // Enables e-mail notification when the account balance reaches the configured threshold.
                  "enabled": boolean,
  
                  // Balance threshold that triggers low-balance notifications.
                  "threshold": number
              },
  
              // Deprecated-model notification settings.
              "deprecatedModels": {
                  // Enables e-mail notification when configured models are deprecated.
                  "enabled": boolean
              }
          }
      }
  }

  {
      "type": "object",
      "properties": {
          "name": {
              "type": "string",
              "description": "New display name for the authenticated account."
          },
          "parameters": {
              "type": "object",
              "properties": {
                  "allowConversationsLogging": {
                      "type": "boolean",
                      "description": "Enables storage of conversation records for observability, export and troubleshooting."
                  },
                  "automaticJsonHealing": {
                      "type": "boolean",
                      "description": "Enables automatic repair attempts when a model response is expected to be JSON but is malformed."
                  },
                  "allowSemanticDataCollection": {
                      "type": "boolean",
                      "description": "Allows account-deidentified RAG and Reflex search data to be collected for model training in exchange for eligible search discounts."
                  },
                  "notifications": {
                      "type": "object",
                      "properties": {
                          "emails": {
                              "type": "array",
                              "items": {
                                  "type": "string"
                              },
                              "description": "Additional notification destination e-mails."
                          },
                          "lowBalance": {
                              "type": "object",
                              "properties": {
                                  "enabled": {
                                      "type": "boolean",
                                      "description": "Enables e-mail notification when the account balance reaches the configured threshold."
                                  },
                                  "threshold": {
                                      "type": "number",
                                      "description": "Balance threshold that triggers low-balance notifications."
                                  }
                              },
                              "description": "Low-balance notification settings."
                          },
                          "deprecatedModels": {
                              "type": "object",
                              "properties": {
                                  "enabled": {
                                      "type": "boolean",
                                      "description": "Enables e-mail notification when configured models are deprecated."
                                  }
                              },
                              "description": "Deprecated-model notification settings."
                          }
                      },
                      "description": "Notification preferences for account-level events."
                  }
              },
              "description": "Full replacement account configuration, including notification and semantic data collection settings."
          }
      },
      "description": "Payload for updating account name and parameters."
  }

Responses:

• 200

  The account name and parameters were saved.

• 400

  Invalid request body.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200

  Salt rolled successfully.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Responses:

• 200

  List of API keys and account salt.

  {
      "apiKeys": [
          {
              "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "expiresAt": "2027-01-01T00:00:00Z",
              "usedAt": "2026-03-01T12:00:00Z",
              "label": "My key",
              "key": "...abc123"
          }
      ],
      "salt": "randomsaltvalue"
  }

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Request examples:

• API key creation payload. The type field accepts private or public.

  ExampleSchema

  {
      // Identifying label for the key.
      "label": string,
  
      // Lifetime in days. Use -1 to create a non-expiring key; decimal values are accepted.
      "duration": number,
  
      // Key scope. Use private for server-side account access or public for client-facing access where supported.
      "type": string
  }

  {
      "type": "object",
      "properties": {
          "label": {
              "type": "string",
              "description": "Identifying label for the key."
          },
          "duration": {
              "type": "number",
              "description": "Lifetime in days. Use -1 to create a non-expiring key; decimal values are accepted."
          },
          "type": {
              "type": "string",
              "description": "Key scope. Use private for server-side account access or public for client-facing access where supported."
          }
      },
      "description": "Payload for creating a new API key."
  }

Responses:

• 200

  API key created successfully.

  {"grantKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

• 400

  Invalid request body.

Headers:

• AuthorizationRequired

  The API key used to authenticate the request. Can be provided as a query parameter (api-key).

Path parameters:

• key-iduuid

  Unique identifier of the API key to delete.

Responses:

• 200

  API key deleted successfully.

• 400

  API key not found or does not belong to the account.