AI

General-purpose AI interactions

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.<br/><br/>To learn more about AI agents, check out the documentation.

post/v1/ai/invoke

Request

  • Base URL: https://api.port.io
  • URL: https://api.port.io/v1/ai/invoke
  • Auth: API key in header Authorization

Query parameters

invocation_identifierstring

A unique identifier for the invocation.

conversation_identifierstring

Conversation ID for clients continuing a thread.

Request body

userPromptstring

The user's message or query to be processed by Port AI.

labelsobject

Optional meta-data about the invocation.

provider'openai' | 'azure-openai' | 'anthropic' | 'azure-anthropic' | 'bedrock' | 'port' | 'openai-compatible' | 'vertex-gemini' | 'vertex-anthropic' | 'anthropic-compatible'

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.

systemPromptstring

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.

executionMode'Automatic' | 'Approval Required'

Tool execution mode. Controls how tools are executed.

toolApprovalOverridesobject

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.

toolsstring[]

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.

asyncboolean

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.

chatMode'ask' | 'build' | 'plan' | 'onboarding'

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.

conversationIdstring

Conversation ID for stateless clients continuing a thread without invocation_identifier.

Response

Default Response

okboolean required
invocationIdentifierstring required

The invocation id to use when polling for results.

traceIDstring required

Changes

No recorded changes to this operation across all 1 revision of this API.