General-purpose AI interactions
POST/v1/ai/invoke
This is a general-purpose endpoint that is not tied to any specific agent. Its purpose is to allow you to send requests directly to Port AI, enabling interactions and executions without being bound to a predefined agent context.
To learn more about AI agents, check out the documentation.
Request
Parameters (JSON)
{
"parameters": [
{
"schema": {
"type": "string"
},
"in": "query",
"name": "invocation_identifier",
"required": false,
"description": "A unique identifier for the invocation."
},
{
"schema": {
"type": "string"
},
"in": "query",
"name": "conversation_identifier",
"required": false,
"description": "Conversation ID for clients continuing a thread."
}
]
}Request body schema (JSON)
{
"title": "Body",
"body": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"userPrompt": {
"description": "The user's message or query to be processed by Port AI.",
"type": "string"
},
"toolApprovals": {
"description": "Tool call approvals to continue a paused invocation. Mutually exclusive with userPrompt.",
"type": "array",
"items": {
"type": "object",
"properties": {
"toolCallId": {
"type": "string",
"description": "The ID of the tool call to approve or reject."
},
"action": {
"type": "string",
"enum": [
"approve",
"approve_with_edit",
"reject"
],
"description": "The action to take on the tool call."
},
"editedArguments": {
"description": "Required if action is approve_with_edit. The edited arguments to use.",
"type": "object",
"additionalProperties": {}
},
"rejectionReason": {
"description": "Optional reason if rejecting the tool call. Passed to LLM.",
"type": "string"
}
},
"required": [
"toolCallId",
"action"
]
}
},
"labels": {
"description": "Optional meta-data about the invocation.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"provider": {
"description": "The AI provider to use for this invocation. If not specified, the default provider will be used. For custom catalogs, use `openai-compatible`, `anthropic-compatible`, `vertex-gemini`, or `vertex-anthropic` with a model `name` from your [LLM provider configuration](https://docs.port.io/api-reference/create-or-connect-an-llm-provider).",
"type": "string",
"enum": [
"openai",
"azure-openai",
"anthropic",
"azure-anthropic",
"bedrock",
"port",
"openai-compatible",
"vertex-gemini",
"vertex-anthropic",
"anthropic-compatible"
]
},
"model": {
"anyOf": [
{
"type": "string",
"enum": [
"gpt-5",
"gpt-5.6-luna",
"gpt-5.6-terra",
"claude-sonnet-4-20250514",
"claude-sonnet-4-5-20250929",
"claude-sonnet-4-6",
"claude-sonnet-5",
"claude-sonnet-5-5",
"claude-haiku-4-5-20251001",
"claude-opus-4-5-20251101",
"claude-opus-4-6"
]
},
{
"type": "string",
"minLength": 3,
"description": "Custom model name (for example from an OpenAI-compatible, Anthropic-compatible, Vertex Gemini, or Vertex Anthropic provider you configured)."
}
]
},
"systemPrompt": {
"default": "",
"description": "A set of instructions that guides an AI's behavior and responses by providing its role, persona, and operational rules at the beginning of an interaction.",
"type": "string"
},
"executionMode": {
"description": "Tool execution mode. Controls how tools are executed.",
"type": "string",
"enum": [
"Automatic",
"Approval Required"
]
},
"toolApprovalOverrides": {
"description": "Override the per-tool approval mode for this invocation. Each entry is layered on top of the user's saved approval preferences (entries here win on conflicts). Each key is a tool name; \"approval\" pauses execution to require user approval before the tool runs, \"automatic\" runs the tool without approval. To narrow the set of tools available to the model, use the `tools` field.",
"type": "object",
"additionalProperties": {
"type": "string",
"enum": [
"automatic",
"approval"
]
}
},
"tools": {
"description": "List of Regex values to match against the tools names. When omitted, all tools available to the user are included (subject to the user's tool approval preferences). To learn more about the available tools, refer to the [documentation](https://docs.port.io/port-ai/overview/#tools).",
"type": "array",
"items": {
"type": "string",
"description": "Regular expressions matched against available tool names. See [available tools](https://docs.port.io/port-ai/overview/#tools) in the Port AI overview."
}
},
"mcpServers": {
"description": "Up to five MCP server identifiers to use for this invocation.",
"maxItems": 5,
"type": "array",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string",
"description": "The MCP server identifier in Port."
}
},
"required": [
"identifier"
]
}
},
"memory": {
"description": "Memory configuration options for this invocation.",
"type": "object",
"properties": {
"disabled": {
"default": false,
"description": "If true, disables memory retrieval and storage for this invocation.",
"type": "boolean"
}
}
},
"async": {
"default": false,
"description": "When true, the invocation is accepted and run asynchronously. The response is HTTP 202 with no SSE stream. Poll GET /ai/invoke/:invocation_identifier for results.",
"type": "boolean"
},
"outputSchema": {
"description": "JSON Schema for structured output validation. When provided, the AI response will be validated against this schema.",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"object"
],
"description": "Root JSON Schema type for structured output."
},
"properties": {
"description": "JSON object properties for structured output. Values may be nested JSON Schema fragments.",
"type": "object",
"additionalProperties": {}
},
"required": {
"description": "List of required property names for the top-level object.",
"type": "array",
"items": {
"type": "string",
"description": "A required property name."
}
}
},
"required": [
"type"
],
"additionalProperties": {}
},
"chatMode": {
"description": "Chat mode that controls which tools are available. ask: read-only tools only. plan: read-only + plan tools. build: all tools. When specifying a chat mode the run_action tool is replaced by the trigger_run tool.",
"type": "string",
"enum": [
"ask",
"build",
"plan",
"onboarding"
]
},
"conversationId": {
"description": "Conversation ID for stateless clients continuing a thread without invocation_identifier.",
"type": "string"
}
}
}
}
}
}
}Responses
- 202
- 400
- 403
- 409
- 500
Default Response
Default Response
Default Response
Default Response
Default Response
Responses (JSON)
{
"responses": {
"202": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"invocationIdentifier": {
"type": "string",
"description": "The invocation id to use when polling for results."
},
"traceID": {
"type": "string"
}
},
"required": [
"ok",
"invocationIdentifier",
"traceID"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
}
}
}