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"
    }
  }'

Request fields

The invoke body supports the fields below. For the full schema, see General-purpose AI interactions and Invoke a specific agent.

Field	Purpose	Details
prompt / userPrompt	The natural language request	Required for a new invocation
tools	Regex patterns that limit which tools may run	Tools and approvals
chatMode	ask, plan, or build	Chat modes
executionMode	Automatic vs approval for run_action	Tool execution modes
toolApprovalOverrides	Per-invocation approval settings	Tool approval
mcpServers	MCP connectors to attach (up to five)	MCP servers in API requests
outputSchema	JSON Schema for a structured response	Structured output
provider / model	Override the LLM for this request	LLM provider management
labels	Metadata for tracking the request	See the With metadata labels example above

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

Sample SSE stream (click to expand)

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.

For rate limits, monthly quota, and how to act on the done event, see Limits and quotas.

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.

Integration patterns

API Integration

Direct API Calls

Integrate Port AI directly into your applications using HTTP requests:

Example: Direct API calls (click to expand)

# 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 (click to expand)

// 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...
}

Actions & Automations

Port Automations

Automatically trigger Port AI based on catalog events using Port's automation system:

Example: Infrastructure Healing Automation (click to expand)

{
  "identifier": "ai_infrastructure_healing",
  "title": "AI Infrastructure Healing",
  "description": "Automatically trigger AI analysis when infrastructure becomes unhealthy",
  "icon": "Cluster",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "ENTITY_UPDATED",
      "blueprintIdentifier": "k8s_workload"
    },
    "condition": {
      "type": "JQ",
      "expressions": [
        ".diff.before.properties.isHealthy == \"Healthy\"",
        ".diff.after.properties.isHealthy == \"Unhealthy\""
      ],
      "combinator": "and"
    }
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.port.io/v1/ai/invoke",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "prompt": "Infrastructure component {{ .event.diff.after.title }} is unhealthy. Analyze the issue and suggest remediation steps based on current state and recent changes.",
      "tools": [
        "^(list|search|describe)_.*",
        "run_.*incident.*",
        "run_.*notification.*"
      ],
      "labels": {
        "source": "automation",
        "entity_type": "{{ .event.diff.after.blueprint }}",
        "entity_id": "{{ .event.diff.after.identifier }}",
        "trigger_type": "health_degradation"
      }
    }
  },
  "publish": true
}

Self-Service Actions

Create actions that invoke Port AI for on-demand analysis:

Example: Service Health Analysis Action (click to expand)

{
  "identifier": "analyze_service_health",
  "title": "Analyze Service Health with AI",
  "description": "Get AI-powered analysis of service health and recommendations",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "blueprintIdentifier": "service"
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.port.io/v1/ai/invoke",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "prompt": "Analyze the health of service {{ .entity.title }}. Check metrics, recent deployments, incidents, and provide actionable recommendations.",
      "tools": ["^(list|search|describe)_.*", "run_.*incident.*"],
      "labels": {
        "source": "self_service",
        "service_name": "{{ .entity.identifier }}",
        "requested_by": "{{ .trigger.by.user.email }}"
      }
    }
  }
}

FAQ

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 data access, permissions, and audit details, see AI security and data controls.

Related topics

• Tools and approvals - Restrict tools, set approval behavior, and attach MCP connectors.
• Limits and quotas - Rate limits, monthly quota, errors, and technical limitations.
• AI invocations - Audit and debug each interaction.