Skip to main content

​
API Reference

Integrate your applications with the Agent Platform API.

​
Overview

The Agent Platform API enables programmatic access to your agentic apps. Use it to:
  • Execute conversations
  • Manage sessions
  • Retrieve analytics
  • Configure apps programmatically

​
Base URL

https://api.platform.kore.ai/v1

​
Authentication

All API requests require authentication via API key.

​
Headers

Authorization: Bearer sk-app-xxxxxxxxxxxxx
Content-Type: application/json

​
Getting API Keys

  1. Navigate to Deploy → API Keys
  2. Click Generate Key
  3. Copy and store securely

​
Endpoints

​
Execute Conversation

Send a message and receive an agent response. 
POST /apps/{app_id}/execute
Request: 
{
  "message": "What's my order status?",
  "session_id": "sess_abc123",
  "metadata": {
    "user_id": "user_456",
    "channel": "web"
  }
}
Response: 
{
  "response": "I found your order #12345. It shipped yesterday and should arrive by Friday.",
  "session_id": "sess_abc123",
  "trace_id": "trace_xyz789",
  "agent": "support_agent",
  "tools_used": ["get_order_status"],
  "usage": {
    "input_tokens": 145,
    "output_tokens": 52
  }
}

​
Create Session

Start a new conversation session. 
POST /apps/{app_id}/sessions
Request: 
{
  "user_id": "user_456",
  "metadata": {
    "channel": "mobile_app",
    "language": "en"
  }
}
Response: 
{
  "session_id": "sess_abc123",
  "created_at": "2024-01-15T14:30:00Z",
  "expires_at": "2024-01-15T15:30:00Z"
}

​
Get Session History

Retrieve conversation history for a session. 
GET /apps/{app_id}/sessions/{session_id}/history
Response: 
{
  "session_id": "sess_abc123",
  "messages": [
    {
      "role": "user",
      "content": "What's my order status?",
      "timestamp": "2024-01-15T14:30:00Z"
    },
    {
      "role": "assistant",
      "content": "I found your order #12345...",
      "timestamp": "2024-01-15T14:30:02Z",
      "agent": "support_agent"
    }
  ]
}

​
End Session

Explicitly close a session. 
DELETE /apps/{app_id}/sessions/{session_id}

​
Streaming

For real-time responses, use Server-Sent Events.

​
Streaming Execute

POST /apps/{app_id}/execute/stream
Request (same as execute): 
{
  "message": "Explain your return policy",
  "session_id": "sess_abc123"
}
Response (SSE stream): 
event: start
data: {"trace_id": "trace_xyz789"}

event: token
data: {"content": "Our"}

event: token
data: {"content": " return"}

event: token
data: {"content": " policy"}

event: tool_call
data: {"tool": "search_knowledge", "status": "started"}

event: tool_call
data: {"tool": "search_knowledge", "status": "completed"}

event: token
data: {"content": " allows..."}

event: done
data: {"usage": {"input_tokens": 45, "output_tokens": 128}}

​
Metadata

Pass contextual information with requests.

​
Session Metadata

Stored in sessionMeta memory: 
{
  "metadata": {
    "userProfile": {
      "name": "John",
      "tier": "premium",
      "preferences": {
        "language": "en",
        "notifications": true
      }
    }
  }
}

​
Accessing in Prompts

Welcome back, {{memory.sessionMeta.metadata.userProfile.name}}!

​
Error Handling

​
Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Session not found",
    "details": {
      "session_id": "sess_invalid"
    }
  }
}

​
Error Codes

CodeHTTP StatusDescription
invalid_request400Malformed request
authentication_error401Invalid API key
not_found404Resource not found
rate_limited429Too many requests
internal_error500Server error

​
Rate Limits

PlanRequests/minuteRequests/day
Free601,000
Pro60050,000
EnterpriseCustomCustom

​
Rate Limit Headers

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1705330260

​
SDKs

​
JavaScript/TypeScript

npm install @kore/agent-platform

import { AgentPlatform } from '@kore/agent-platform';

const client = new AgentPlatform({
  apiKey: 'sk-app-xxxxx'
});

const response = await client.execute({
  appId: 'app_123',
  message: "What's my order status?",
  sessionId: 'sess_abc123'
});

console.log(response.response);

​
Python

pip install kore-agent-platform

from kore_platform import AgentPlatform

client = AgentPlatform(api_key="sk-app-xxxxx")

response = client.execute(
    app_id="app_123",
    message="What's my order status?",
    session_id="sess_abc123"
)

print(response.response)

​
Webhooks

Receive notifications for events.

​
Configure Webhook

{
  "url": "https://your-app.com/webhooks/kore",
  "events": [
    "session.started",
    "session.ended",
    "conversation.escalated"
  ],
  "secret": "whsec_xxxxx"
}

​
Webhook Payload

{
  "event": "conversation.escalated",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "session_id": "sess_abc123",
    "reason": "user_requested",
    "context": {...}
  }
}

​
Verify Signatures

const signature = req.headers['x-kore-signature'];
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(req.body)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid signature');
}