> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Port AI API Interaction

Port AI can be accessed programmatically through Port's API, enabling integration into custom applications and workflows. This provides the most flexible way to incorporate Port AI capabilities into your existing tools and processes.

API Endpoints​

Port AI provides streaming API endpoints for real-time interaction:

  • Port AI Assistant: /v1/ai/invoke - General-purpose AI interactions.
  • AI Agents: /v1/agent/<AGENT_IDENTIFIER>/invoke - Domain-specific agent interactions.

All interactions use streaming responses as Server-Sent Events (SSE) to provide real-time updates during execution. The response will be in text/event-stream format.

Interaction Process​

  1. Invoke Port AI
  2. The API will start sending Server-Sent Events
  3. Your client should process these events as they arrive, with each event providing information about the AI's progress or final response

Basic API Examples​

Port AI Assistant:

curl 'https://api.port.io/v1/ai/invoke' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"prompt":"What services are failing health checks?"}'

AI Agents:

curl 'https://api.port.io/v1/agent/<AGENT_IDENTIFIER>/invoke' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"prompt":"Analyze the health of our production services"}'

With metadata labels:

curl 'https://api.port.io/v1/ai/invoke' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "prompt":"What services are failing health checks?",
    "tools": ["^(list|search|describe)_.*"],
    "labels": {
      "source": "monitoring_system",
      "environment": "production",
      "triggered_by": "automated_check"
    }
  }

Streaming Response Format​

The API responds with Content-Type: text/event-stream; charset=utf-8.

Each event in the stream has the following format:

event: <event_name>
data: <json_payload_or_string>

Note the blank line after data: ... which separates events.

Example Event Sequence​

event: tool_call
data: { "id": "call_0", "name": "list_entities", "arguments": "{\"blueprintIdentifier\":\"service\"}" }

event: tool_result
data: { "id": "call_0", "content": "Found 15 services in your catalog..." }

event: tool_call
data: { "id": "call_1", "name": "run_action", "arguments": "{\"actionIdentifier\":\"create_incident\"}" }

event: tool_result
data: { "id": "call_1", "content": "Action run created successfully with ID: run_12345" }

event: execution
data: I found 15 services in your catalog and created an incident report as requested.

event: done
data: {
  "rateLimitUsage": {
    "maxRequests": 200,
    "remainingRequests": 193,
    "maxTokens": 200000,
    "remainingTokens": 179910,
    "remainingTimeMs": 903
  },
  "monthlyQuotaUsage": {
    "monthlyLimit": 50,
    "remainingQuota": 49,
    "month": "2025-09",
    "remainingTimeMs": 1766899073
  }
}

Event Types​

tool_call (Click to expand)

Indicates that Port AI is about to execute a tool. This event provides details about the tool being called and its arguments. For large arguments, the data may be sent in multiple chunks.

{
  "id": "call_0",
  "name": "list_entities",
  "arguments": "{\"blueprintIdentifier\":\"service\",\"limit\":10}",
  "lastChunk": true
}

Fields:

  • id: Unique identifier for this tool call.
  • name: Name of the tool being executed (only included in the first chunk).
  • arguments: JSON string containing the tool arguments (may be chunked for large payloads).
  • lastChunk: Boolean indicating if this is the final chunk for this tool call (optional, only present on the last chunk).
tool_result (Click to expand)

Contains the result of a tool execution. For large results, the data may be sent in multiple chunks.

{
  "id": "call_0",
  "content": "Found 15 services in your catalog: api-gateway, user-service, payment-service...",
  "lastChunk": true
}

Fields:

  • id: Unique identifier matching the corresponding tool call.
  • content: The result content from the tool execution (may be chunked for large responses).
  • lastChunk: Boolean indicating if this is the final chunk for this tool result (optional, only present on the last chunk).
execution (Click to expand)

The final textual answer or a chunk of the answer from Port AI. For longer responses, multiple execution events might be sent.

done (Click to expand)

Signals that Port AI has finished processing and the response stream is complete. This event also includes quota usage information for managing your API limits.

{
  "rateLimitUsage": {
    "maxRequests": 200,
    "remainingRequests": 193,
    "maxTokens": 200000,
    "remainingTokens": 179910,
    "remainingTimeMs": 903
  },
  "monthlyQuotaUsage": {
    "monthlyLimit": 50,
    "remainingQuota": 49,
    "month": "2025-09",
    "remainingTimeMs": 1766899073
  }
}

Quota Usage Fields:

  • maxRequests: Maximum number of LLM calls allowed in the current rolling window.
  • remainingRequests: Number of LLM calls remaining in the current window.
  • maxTokens: Maximum number of tokens allowed in the current rolling window.
  • remainingTokens: Number of tokens remaining in the current window.
  • remainingTimeMs: Time in milliseconds until the rolling window resets.

Processing Quota Information​

Managing quota usage

Use the quota information in the done event to implement client-side rate limiting and avoid hitting API limits. When remainingRequests (remaining LLM calls) or remainingTokens are low, consider adding delays between requests or queuing them for later execution.

JavaScript Example: Processing Quota Information (Click to expand)

When processing the streaming response, you'll receive quota usage information in the final done event. Here's a JavaScript example of how to handle this:

const eventSource = new EventSource(apiUrl);

eventSource.addEventListener("done", (event) => {
  const data = JSON.parse(event.data);

  if (data.rateLimitUsage) {
    const { remainingRequests, remainingTokens, remainingTimeMs } =
      data.rateLimitUsage;

    // Check if quota is running low (LLM calls or tokens)
    if (remainingRequests < 10 || remainingTokens < 10000) {
      console.warn("Quota running low, consider rate limiting");
      // Implement rate limiting logic
    }

    // Schedule next request after quota reset if needed
    if (remainingRequests === 0) {
      setTimeout(() => {
        // Safe to make next request
      }, remainingTimeMs);
    }
  }

  eventSource.close();
});

Rate Limits and Quotas​

Port AI operates with specific limits to ensure optimal performance for all users:

LLM Provider Limits

These limits apply when using Port's managed AI infrastructure. When you configure your own LLM provider, these Port-specific limits no longer apply, and usage will be governed by your provider's own limits and pricing.

Port acts as a bridge to leading LLM providers and doesn't host LLM models internally.

Rate Limits (Per Minute)​

  • LLM call limit: 200 LLM calls per minute.
  • Token usage limit: 500,000 tokens per minute.
  • These limits reset every minute.

Monthly Quota​

  • Default quota: 500 AI invocations per month for most plans.
  • Each interaction with Port AI counts as one request against your quota.
  • Quota resets on the first day of each calendar month (UTC).
  • Enterprise plans may have higher quotas or unlimited usage. Contact your account team for details.
Usage limits

Usage limits may change without prior notice. Once a limit is reached, you will need to wait until it resets.
If you attempt to interact with Port AI after reaching a limit, you will receive an error message indicating that the limit has been exceeded. The query limit is estimated and depends on the actual token usage.

What happens when quota is exceeded​

When you exceed your monthly quota, Port AI returns an error and does not process the request. The request is not queued or retried automatically.

Error response:

{
  "error": "Monthly quota exceeded",
  "type": "QUOTA_ERROR",
  "resetDate": "2025-10-01T00:00:00Z"
}

All AI interfaces (Port AI Assistant, AI Chat Widgets, API, and workflow AI nodes) will return this error until:

  • The quota resets at the start of the next month, or
  • Your organization's quota is increased.

Monitor your usage​

You can monitor your current usage in several ways:

Check usage via API​

Use the Get monthly AI invocations quota usage API endpoint:

curl 'https://api.port.io/v1/quota/ai-invocations' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>'

Response:

{
  "ok": true,
  "monthlyQuotaUsage": {
    "monthlyLimit": 500,
    "remainingQuota": 158,
    "month": "2025-11",
    "remainingTimeMs": 1234567890
  }
}

Check rate limits in streaming responses​

  • Check the final done event in streaming responses for remaining LLM calls, tokens, and reset time.
Proactive quota monitoring

Check your monthly quota before making multiple Port AI requests to avoid hitting limits. When remainingQuota is low, consider implementing rate limiting or queuing requests until the monthly quota resets. Note that you may also encounter per-minute rate limits, which are separate from this monthly quota.

Request a quota increase​

If you need more AI invocations than your current quota allows:

  1. Contact Port support: Submit a request through support.port.io explaining your use case and estimated monthly usage.
  2. Upgrade your plan: Enterprise plans include higher quotas. Contact your account team or sales@port.io to discuss options.
  3. Bring your own LLM: Configure your own LLM provider to bypass Port's managed quotas entirely. Usage will then be governed by your provider's limits.

Structured output​

Port AI supports structured output generation, allowing you to specify a JSON Schema that the AI response must conform to. This is useful when you need to parse the AI response programmatically.

How it works​

Include an outputSchema parameter in your API request with a valid JSON Schema. The AI will generate a structured JSON object matching the schema instead of free-form text.

curl 'https://api.port.io/v1/ai/invoke' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "prompt": "Analyze the health of our production services",
    "tools": ["^(list|search|describe)_.*"],
    "outputSchema": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" },
        "healthyServices": { "type": "number" },
        "unhealthyServices": { "type": "number" },
        "recommendations": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "required": ["summary", "healthyServices", "unhealthyServices"]
    }
  }'

The same parameter works with AI agents:

curl 'https://api.port.io/v1/agent/<AGENT_IDENTIFIER>/invoke' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "prompt": "Analyze service dependencies",
    "outputSchema": {
      "type": "object",
      "properties": {
        "serviceName": { "type": "string" },
        "dependencies": {
          "type": "array",
          "items": { "type": "string" }
        },
        "riskLevel": { "type": "string" }
      },
      "required": ["serviceName", "dependencies"]
    }
  }'

Schema requirements​

The outputSchema must be a valid JSON Schema with type: "object" at the root level. You can define:

  • properties: The fields the AI should generate.
  • required: Fields that must be present in the response.
  • Nested objects and arrays for complex structures.
Structured output behavior

When outputSchema is provided, the AI must generate a valid JSON object matching the schema. If the AI fails to generate valid output conforming to the schema, the request will fail with an error. The response will contain the structured JSON object as the final execution event data.

Selecting Model​

Port AI allows you to specify which LLM provider and model to use for specific API requests, giving you fine-grained control over AI processing on a per-request basis.

How LLM Providers Work​

Port AI supports multiple LLM providers and models. You can either use Port's managed AI infrastructure (default) or configure your own LLM providers for additional control over data privacy, costs, and compliance.

Learn more about LLM Provider Management and see the supported models and providers.

Specifying Provider and Model​

When making API requests, you can include provider and model parameters (if none specified, your organization's default will be used). See the Invoke an agent API reference for detailed example.

Default Behavior​

If no provider is specified in your API request, the system uses your organization's configured defaults, or falls back to Port's system defaults if none are configured.

Chat modes​

Port AI supports chat modes that control which tools are available during an interaction. In the Port AI Assistant side chat, you select a mode from the UI. In API requests, pass the chatMode field in the invoke request body.

ModeTool availabilityTypical use
askRead-only Port tools (get_*, list_*, search_*, and similar) plus run_action and trigger_auto_discovery. Write tools are excluded.Explore data and configuration without edits.
planFull tool set (minus disabled tools), including plan-specific tools for multi-step analysis.Bigger changes that require deeper analysis across multiple components.
buildFull tool set (minus disabled tools).Scoped changes in your environment.

Chat mode controls which tools exist, not whether they pause for approval. In ask mode, write tools never appear regardless of your automate settings. In plan and build modes, your per-tool approval preferences apply. See tool approval below.

For API usage, see the chatMode field in General-purpose AI interactions.

Tool execution modes​

For action execution tools specifically, Port AI supports two execution modes:

When configured for automatic execution, Port AI will:

  1. Determine the appropriate parameters based on your request.
  2. Execute actions immediately.
  3. Provide a link to the action run or results.

This mode streamlines workflows but should be used carefully, especially for actions with significant impact.

Execution modes scope

Execution modes apply at the API and agent level. They mainly control how run_action executes Port self-service actions (automatically vs. as a manual draft). In the Port AI Assistant side chat, executionMode is not sent, so per-tool approval settings drive the pause-and-approve flow instead.

Tool approval​

Port AI has two mechanisms that control how tools run. They are easy to conflate but serve different purposes:

LayerWhat it controlsWhere it lives
Per-tool approval settingsWhether a specific tool pauses for user confirmation before it runsUser preferences via the tool approval preferences API, or the side chat + menu
Execution mode (Automatic / Approval Required)API and agent-level behavior, mainly how run_action runs Port self-service actionsAgent entity or API request body

Per-tool approval options​

Each tool supports one of three states:

  1. approval - the model can use the tool, but execution pauses until the user approves, edits arguments, or rejects the call.
  2. automatic - the tool runs without pausing.
  3. Disabled - the tool is removed from the model's tool list entirely.

Default behavior when no custom preference exists:

  • Port read-only tools (get_*, list_*, and similar, plus run_action): automatic.
  • Port write tools (create, update, delete, and similar): approval.
  • External MCP tools: approval.

Approval resolution priority​

The effective approval mode for a tool is resolved using the following priority (highest to lowest):

  1. Per-invocation override - the toolApprovalOverrides field in the invoke request body. This takes the highest priority and can set any tool to automatic or approval for that single invocation.
  2. Persistent preferences - the user's saved preferences via the tool approval preferences API. These apply to all invocations unless overridden by the request body.
  3. Read-only annotation - if the tool's MCP annotation marks it as read-only (readOnlyHint: true), it defaults to automatic. All other tools default to approval.
Execution mode override

When executionMode is set to Automatic in the request body, per-tool user preferences are skipped for the approval-pause flow and all tools run automatically.

Runtime flow​

When Port AI processes a request:

  1. The backend loads saved preferences and builds the tool list (disabled tools are filtered out).
  2. The model selects tools for the request.
  3. For each tool call, the backend checks whether approval is required based on the resolution priority above.
  4. If any tool needs approval, the stream pauses and the client displays a tool approval prompt.
  5. The user approves, declines, or edits arguments, and the client resumes the invocation via toolApprovals on the next request.

Tools set to automatic in the same batch still run immediately. Only approval-mode tools block the turn.

Continuing a paused invocation​

When a tool call requires approval, the stream pauses. To resume, send a follow-up request with toolApprovals instead of userPrompt. Each entry requires a toolCallId and an action of approve, approve_with_edit, or reject. Use editedArguments when the action is approve_with_edit, and optionally include rejectionReason when rejecting.

See the toolApprovals field in General-purpose AI interactions.

toolApprovals example (Click to expand)
{
  "toolApprovals": [
    {
      "toolCallId": "call_0",
      "action": "approve"
    },
    {
      "toolCallId": "call_1",
      "action": "approve_with_edit",
      "editedArguments": {
        "blueprintIdentifier": "service",
        "identifier": "payment-service"
      }
    },
    {
      "toolCallId": "call_2",
      "action": "reject",
      "rejectionReason": "Not the right service"
    }
  ]
}

Side chat vs. agents and API​

  • Side chat uses per-tool approval preferences from the + menu. executionMode is not sent, so your saved settings drive the pause-and-approve flow. See tool approval settings in the Port AI Assistant.
  • AI agents use execution_mode on the agent entity (Automatic vs. Approval Required), or tool_approval_overrides if configured. Agent chat views show tool settings as read-only.
  • API callers can pass executionMode or toolApprovalOverrides. When executionMode is set, per-tool user preferences are skipped for the approval-pause flow.

Tool selection​

Port AI allows you to control which specific tools from the Port MCP server are available for each API interaction. This provides fine-grained control over what actions Port AI can perform, enabling you to create secure, purpose-specific AI interactions.

For per-tool approval behavior, see tool approval above.

Controlling which tools are available​

You can restrict which tools Port AI is allowed to use. For example, you can limit an interaction to read-only tools for simple Q&A, or allow only specific actions for automated workflows.

  • Per-invocation: Pass the tools array in the invoke request body with regex patterns that match tool names. Only matching tools will be available for that invocation.
  • Persistent preferences: Use the tool approval preferences API to disable specific tools entirely. Disabled tools are excluded from all future invocations unless overridden by a tools array in the request body.

Controlling how tools are approved​

For per-tool approval modes, defaults, and the resolution priority, see tool approval.

Permission-Based Tool Filtering

Selected tools will be available based on your regex patterns but won't include tools that are not within your permission scope. This means:

  • If you request an action to create a Jira ticket but this action is not available to you as a user, it won't be available to Port AI.
  • Members trying to use builder tools like upsert_blueprint will not have access to these tools through Port AI if they lack the necessary permissions.
  • Tool availability is determined by the intersection of your regex selection AND your user permissions.

Port AI respects your individual user permissions and cannot access tools or perform actions that you don't have permission to use.

How Tool Selection Works​

Include a tools parameter in your API request with an array of regex patterns. Port AI will only use tools whose names match at least one of these patterns.

Basic format:

{
  "prompt": "Your question or request",
  "tools": ["regex_pattern_1", "regex_pattern_2"]
}
Port tools vs. MCP connector tools

When you attach MCP connectors, treat patterns in two groups. To enable tools from a connector, an entry in tools must start with that connector's identifier in Port, then an underscore, then the rest of your regex (for example notion_.* for the notion connector). You cannot place ^ or any other characters before that prefix: ^notion_.* does not count as a connector pattern and will not enable connector tools. Every other pattern applies only to Port MCP tools (catalog query, run_* actions, and the rest of the built-in Port tool surface), including very broad regex such as .* or ^run_.*. Those patterns never enable connector tools on their own, even when the regex text could match a connector tool name. Add an explicit pattern that begins with {identifier}_ when you need connector tools.

Common Tool Selection Patterns​

Read-only Operations (Click to expand)

Perfect for monitoring dashboards and reporting systems where no modifications should be made.

["^(list|search|track|describe)_.*"]

What this matches:

  • list_entities, list_blueprints, list_scorecards.
  • list_actions, list_integrations.
  • describe_user_details.
  • search_port_knowledge_sources.
Action Execution Only (Click to expand)

Allows only action execution tools while blocking data query operations.

["^run_.*"]

What this matches:

  • run_action (the underlying tool that executes all self-service actions).
  • run_create_service, run_deploy_to_production.
  • run_github_create_issue, run_jira_create_ticket.
  • run_slack_notify_team.
run_action must be matched

Self-service actions are executed through the internal run_action tool. Your tools regex must match run_action — either explicitly or via a pattern like "^run_.*". If you only list specific action identifiers (e.g. ["run_deploy_to_production"]) without a pattern that also matches run_action, the agent will not be able to execute those actions.

Specific Integration Actions (Click to expand)

Target specific third-party service integrations.

["run_.*github.*", "run_.*jira.*", "run_.*zendesk.*"]

What this matches:

  • run_github_create_issue, run_github_merge_pr.
  • run_jira_create_ticket, run_jira_update_status.
  • run_zendesk_create_ticket.
Safe Entity Operations (Click to expand)

Enables entity operations while preventing accidental deletions.

["(?!delete_)\\w+_entity$", "list_.*"]

What this matches:

  • list_entities, upsert_entity.
  • Excludes: delete_entity.
Documentation and Help Tools (Click to expand)

Focus on documentation search and help functionality.

[".*docs.*", "search_.*", "describe_.*"]

What this matches:

  • search_port_knowledge_sources.
  • describe_user_details.
Blueprint and Scorecard Analysis (Click to expand)

Focus on catalog structure and quality metrics without action execution.

[".*blueprint.*", ".*scorecard.*", "^list_.*"]

What this matches:

  • list_blueprints, upsert_blueprint.
  • list_scorecards, upsert_scorecard.
  • All list operations.
MCP connector tools (Click to expand)

Tools from MCP connectors use names that start with the connector identifier in Port, followed by an underscore. A tools entry only applies to connector tools if the pattern string itself begins with that {identifier}_ text (for example notion_.*). A leading regex anchor breaks that rule, so ^notion_.* does not work for connector tools. Patterns meant for Port tools (list_*, run_*, .*, ^run_.*, and so on) never unlock connector tools by themselves; see Port tools vs. MCP connector tools above.

["notion_.*"]

What this matches:

  • Any published tool for that connector, such as notion_notion-search.

Use the same identifier you pass in mcpServers[].identifier in place of notion.

Interactive Tool Matcher​

Test your regex patterns to see which MCP tools would be available to Port AI. Enter your patterns in JSON array format (e.g., ["^(list|get)_.*", "run_.*github.*"]) and see the matching tools in real-time.

Enter an array of regex patterns in JSON format. Patterns automatically match from the beginning of tool names (^ is added automatically).

Tools (0 of 45 matched)

delete_actiondelete_workflowget_action_permissionsget_workflow_runlist_actionslist_self_service_triggerslist_workflowsrun_actiontrack_action_runtrigger_runupdate_action_permissionsupsert_actionupsert_workflowdelete_blueprintdelete_entitylist_blueprintslist_entitiessimulate_blueprint_permissionstrigger_auto_discoveryupsert_blueprintupsert_entitydescribe_user_detailsload_skillsearch_port_knowledge_sourcesget_integration_event_logsget_integration_kinds_with_examplesget_integration_sync_metricslist_integrationstest_integration_mappingdelete_sidebar_folderdelete_widgetduplicate_pageget_pageget_sidebarload_widget_schemamove_pageupdate_entity_pageupsert_dashboard_pageupsert_sidebar_folderupsert_widgetlist_pluginsupsert_plugindelete_scorecardlist_scorecardsupsert_scorecard
Action Tools Note

Action tools (starting with run_*) depend on your Port configuration. The examples shown represent common action patterns, but your actual available actions may differ based on the self-service actions configured in your Port instance.

Best Practices​

Security and Control
  • Principle of least privilege: Only include tools necessary for the specific use case.
  • Test patterns: Use the interactive matcher above to verify your regex patterns.
  • Automated systems: Use highly restrictive patterns for automated workflows.
  • User-facing interfaces: Consider broader patterns for interactive use cases.

Tool approval in API requests​

For the full approval model, defaults, and runtime flow, see tool approval. For request fields, see the API reference:

Per-invocation overrides take the highest priority and apply only to that single request. Persistent preferences apply to all future invocations unless overridden by toolApprovalOverrides in the request body. You can also disable specific tools through disabledTools in the preferences API. Disabled tools are excluded from all invocations unless the request includes an explicit tools array, which takes full control of tool availability.

toolApprovalOverrides example (Click to expand)
{
  "userPrompt": "Deploy service X to production",
  "tools": [".*"],
  "toolApprovalOverrides": {
    "run_action": "approval",
    "list_.*": "automatic"
  }
}
Update tool approval preferences example (Click to expand)
{
  "toolOverrides": {
    "run_action": "approval",
    "list_entities": "automatic"
  },
  "disabledTools": ["delete_entity"]
}

MCP Servers in API Requests​

When using the /v1/ai/invoke endpoint, you can attach up to five configured MCP connectors per request. This allows Port AI to use tools from those servers in addition to your Port MCP tools, filtered by your tools patterns.

AI agent invocations

The mcpServers parameter is supported on /v1/ai/invoke and on workflow type: "AI" action nodes. It is not part of the invoke an agent request body. Agent entities use MCP connectors configured on the agent and require a connected user, so agent MCP works in chat only. See build an AI agent.

Prerequisites​

  • Your organization has MCP connectors set up (admins add servers under Data sources and publish allowed tools).
  • The API token represents a user who is allowed to use those connectors. For connectors that use per-user OAuth, authenticate that user in Port before you rely on connector tools (for example from MCP Servers in the avatar menu or from the Port AI chat + menu) so OAuth tokens are available for tool calls.

Limitations​

When /v1/ai/invoke runs with an organization automation token (for example, from an automation or a workflow type: "AI" node), per-user OAuth MCP connectors are not supported. Per-user OAuth tokens are keyed to the user, so automation-token callers cannot use them.

For automated contexts, use organization-level OAuth or connectors with shared header authentication.

Request body​

Add an mcpServers array. Each item must include the connector identifier in Port (the _mcp_server entity identifier), for example the value you see on the connector in the catalog or in Data sources.

"mcpServers": [
  { "identifier": "notion" }
]

Port AI resolves which MCP servers to use based on this field:

  • Omit mcpServers: Port AI falls back to all of your usable MCP servers.
  • mcpServers: [] (empty array): Port AI uses no MCP servers.
  • mcpServers with entries: Port AI uses only the listed servers.

Your existing tools array still controls which tool names may run. Port-side patterns (anything that does not begin with {identifier}_ as the first characters of the pattern string, including .* and ^notion_.*) only affect Port MCP tools; use notion_.* (not ^notion_.*) when the identifier is notion. See MCP connector tools pattern and Port tools vs. MCP connector tools. Native Port tools and MCP connector tools are evaluated together against those patterns.

Example​

curl 'https://api.port.io/v1/ai/invoke' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "userPrompt": "Search our Notion space for the onboarding checklist and summarize the steps.",
    "tools": ["notion_notion-search", "^list_.*", "^run_.*"],
    "mcpServers": [
      { "identifier": "notion" }
    ]
  }'

For all request fields (including userPrompt, tools, and optional mcpServers), see the General-purpose AI interactions API reference.

Integration Patterns​

Direct API Calls

Integrate Port AI directly into your applications using HTTP requests:

# Basic Port AI request
curl 'https://api.port.io/v1/ai/invoke' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "prompt": "What services are failing health checks?",
    "tools": ["^(list|search|describe)_.*"],
    "labels": {
      "source": "monitoring_system",
      "check_type": "health_analysis"
    }'

# AI Agent request
curl 'https://api.port.io/v1/agent/<AGENT_IDENTIFIER>/invoke' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "prompt": "Analyze the health of our production services",
    "labels": {
      "source": "monitoring_dashboard",
      "environment": "production"
    }'

Application Integration Example

// Example: Monitoring dashboard integration
async function checkServiceHealth(serviceName) {
  const response = await fetch("/api/port-ai/check-service", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: `Analyze the health of service ${serviceName}`,
      tools: ["^(list|search|describe)_.*"],
      labels: {
        source: "monitoring_dashboard",
        service: serviceName,
        check_type: "health_analysis",
      },
    }),
  });

  // Process streaming response
  const reader = response.body.getReader();
  // Handle SSE parsing...
}

Error Handling​

Common error scenarios and handling strategies:

Rate Limit Exceeded​

{
  "error": "Rate limit exceeded",
  "type": "RATE_LIMIT_ERROR",
  "retryAfter": 3600
}

Quota Exceeded​

{
  "error": "Monthly quota exceeded",
  "type": "QUOTA_ERROR",
  "resetDate": "2025-10-01T00:00:00Z"
}
Implementation Example: Error Handling (Click to expand)
async function handlePortAIRequest(prompt) {
  try {
    const response = await invokePortAI(prompt);
    return response;
  } catch (error) {
    if (error.type === "RATE_LIMIT_ERROR") {
      // Wait and retry
      await new Promise((resolve) =>
        setTimeout(resolve, error.retryAfter * 1000),
      );
      return handlePortAIRequest(prompt);
    } else if (error.type === "QUOTA_ERROR") {
      // Queue for next month or upgrade plan
      console.log("Monthly quota exceeded, queuing request");
      return null;
    }
    throw error;
  }
}

Technical limitations​

MCP tools limitations

Port AI uses the Port MCP tools, which have their own limitations. For detailed information about MCP tool constraints, refer to the Port MCP server documentation.

Port AI operates within several technical constraints to ensure optimal performance and security:

  • Tool calls per interaction: One AI interaction can include up to 15 tool calls.
  • LLM final response: Limited to 10,000 tokens per response.
  • Tool scope: Currently supports only developer tools (querying data and running actions), not administrative tools (creating blueprints, managing scorecards).
  • User-based permissions: All interactions respect your individual user permissions - Port AI cannot access data you don't have permission to view.
  • Sequential automation permissions: Sequential automations run with Admin privileges, which may differ from your user permissions.

AI invocations​

Every interaction with Port AI creates a detailed AI invocation record in Port, providing comprehensive tracking and analysis capabilities. AI invocations act as execution logs that capture the complete lifecycle of each interaction.

What AI invocations track​

Each AI invocation record includes:

  • Who asked: User identity and context for the interaction.
  • What they asked: The original prompt or question submitted.
  • AI response: The complete response provided by Port AI.
  • Tools used: Detailed log of which tools were executed and their results.
  • Execution logs: Step-by-step record of tool calls and results.
  • User feedback (optional): Users can rate assistant replies with thumbs up or down and optionally leave a short comment.

Accessing AI invocations​

AI invocations are stored as entities in your Port catalog using the _ai_invocations blueprint. You can view them in the AI Invocations catalog page, or query them programmatically via the API.

Feedback on AI invocations​

Users can leave thumbs up or thumbs down on an assistant message, and optionally add a short comment after choosing a rating. Feedback is stored per assistant message inside the invocation's execution_logs JSON (not as a single rating on the invocation entity).

FieldDescription
messageIdStable identifier for each message in execution_logs. Required when submitting feedback via API.
feedbackRatingpositive or negative. Cleared when the user removes their vote. Present on assistant messages.
feedbackCommentOptional text; submitted together with the rating when the user sends a comment.
Legacy entity properties

The _ai_invocations blueprint may still include feedback_rating and feedback_comment properties from earlier releases. New feedback is written to individual messages in execution_logs; those entity properties are no longer updated.

Behavior:

  • Choosing a rating saves it immediately; the user can then open Add a comment to attach text.
  • Clicking the same thumb again clears the rating and any stored comment (equivalent to removing feedback).
  • Updates are best-effort from the client: a failed request does not block the chat, but feedback may not be persisted.

Programmatic access: Integrations can update or clear feedback via the submit feedback and delete feedback API endpoints (with appropriate auth), which update the invocation entity in the catalog.

AI invocation details​

Each AI invocation provides detailed information about how Port AI processed your request:

Reasoning plan​

The reasoning plan shows how Port AI decided to tackle your request and the steps it intended to take. This is an execution log entry, not the same as chat plan mode. Chat plan mode controls which tools are available during a conversation. See chat modes.

AI invocation reasoning plan with step-by-step approach

Tools used​

This section displays the actual steps Port AI took and the tools it used to complete your request. This information can be particularly helpful for debugging when answers don't meet expectations.

AI invocation tool calls JSON panel

Execution details​

Each invocation record also includes:

  • Request timestamp: When the interaction was initiated.
  • User context: Who made the request and from what interface.

Frequently asked questions​

Are there usage limits for Port AI? (Click to expand)

Yes, Port AI has usage limits to ensure fair usage across all customers:

Note: These limits apply when using Port's managed AI infrastructure. Bring your own LLM provider to use your provider's limits instead.

Rate limits (per minute):

  • LLM call limit: 200 LLM calls per minute.
  • Token usage limit: 500,000 tokens per minute.
  • These limits reset every minute.

Monthly quota:

  • Default quota: 500 AI invocations per month.
  • Each interaction with Port AI counts as one request.
  • Quota resets monthly.

You can monitor your usage through API response headers and the quota endpoint. See Rate limits and quotas for full details.

What happens when I reach usage limits? (Click to expand)

When you reach a usage limit:

  • You are temporarily blocked from making new Port AI requests.
  • You receive an error message indicating which limit was exceeded.
  • Access resumes automatically when the limit resets.

For rate limits (per minute):

  • Wait for limits to reset (they reset every minute).
  • Monitor the remainingTimeMs field to know when you can make requests again.

For monthly quota:

  • Wait for the monthly quota to reset at the beginning of the next month.
  • Contact support to learn about quota upgrades for your organization.

Recommendations:

  • Implement rate limiting in your applications.
  • Monitor usage proactively using available monitoring methods.
  • Optimize AI interactions for efficiency.
Can I audit and control Port AI usage? (Click to expand)

Yes, Port AI provides comprehensive audit and control capabilities:

  • Each interaction is saved as an AI invocation record.
  • Granular permission controls determine who can access Port AI.
  • Admin dashboard for monitoring usage across your organization.
  • Export capabilities for audit logs.
  • All interactions respect your configured RBAC and data access policies.

For detailed security and governance information, see AI security and data controls.

Are there any technical limitations to Port AI capabilities? (Click to expand)

Yes, Port AI operates within several technical constraints related to search capabilities, data processing, tool usage, and permissions. See Technical limitations for the full list.

Security considerations​

When integrating Port AI via API:

  • Authentication: Always use secure API token storage and rotation.
  • Data privacy: Port AI respects your organization's RBAC and data access policies.
  • Audit trail: All API interactions are logged and trackable.
  • Rate limiting: Implement client-side rate limiting to avoid hitting API limits.

For comprehensive security information, see AI Security and Data Controls.

Detailed Security Information: