Skip to main content
This page covers the knowledge and memory API for runtime data persistence and contact management, the analytics API for event metrics and voice analytics, and the project export/import API for migrating agent projects between environments. For authentication and error handling conventions, see API overview.

​
Knowledge & Memory API

​
Memory API

The memory API enables agent code running in sandboxed environments to read, write, and delete values from named memory stores. Memory stores persist data across turns within a session, allowing agents to maintain context. Base path: /api/v1/memory

​
POST /api/v1/memory

Perform a memory operation (get, set, or delete) on a named memory store. Auth is required (sandbox JWT — issued automatically by the runtime for sandbox execution contexts) **Request body **
FieldTypeRequiredDescription
actionstringYesOperation to perform: get, set, or delete
memoryStoreNamestringYesName of the memory store
payloadobjectNoData payload (required for set action)
**Actions ** Get — Retrieve the current contents of a memory store: 
curl -X POST https://agents.kore.ai/api/v1/memory \
  -H "Authorization: Bearer <sandbox-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "get",
    "memoryStoreName": "user-preferences"
  }'
Response: 
{
  "success": true,
  "data": {
    "language": "en",
    "timezone": "America/New_York"
  }
}
Set — Store or update data in a memory store: 
curl -X POST https://agents.kore.ai/api/v1/memory \
  -H "Authorization: Bearer <sandbox-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set",
    "memoryStoreName": "user-preferences",
    "payload": {
      "content": {
        "language": "en",
        "timezone": "America/New_York"
      }
    }
  }'
Response: 
{
  "success": true
}
Delete — Remove data from a memory store: 
curl -X POST https://agents.kore.ai/api/v1/memory \
  -H "Authorization: Bearer <sandbox-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "delete",
    "memoryStoreName": "user-preferences"
  }'
Response: 
{
  "success": true,
  "data": {
    "deleted": true
  }
}
**Error responses **
StatusErrorCause
400Missing action or memoryStoreNameRequired fields not provided
400Token missing sessionIdSandbox JWT does not contain a session identifier
400Unknown actionAction is not get, set, or delete
401Invalid or expired tokenSandbox JWT verification failed
404Session not foundNo active memory bridge for the session
503Sandbox auth not configuredServer sandbox JWT secret not configured

​
Contacts

The contacts API manages end-user identities that can be linked across multiple sessions. Contacts provide a unified view of interactions with a specific person or entity. Base path: /api/contacts

​
POST /api/contacts

Create a new contact record. Auth is required Permission: Admin or write access **Request body **
FieldTypeRequiredDescription
typestringNoContact type: employee, customer, or anonymous
identitystringNoUnique identity value (email, phone, external ID)
identityTypestringNoIdentity type: email, phone, or external
displayNamestringNoDisplay name (max 200 characters)
departmentstringNoDepartment (for employee contacts)
employeeIdstringNoEmployee ID (max 100 characters)
companystringNoCompany name (max 200 characters)
accountRefstringNoAccount reference ID
channelstringNoPrimary channel
metadataobjectNoCustom metadata key-value pairs
tagsarrayNoTags (max 50, each max 50 characters)
**Response body (201 Created) ** 
{
  "success": true,
  "data": {
    "id": "ct_abc123",
    "tenantId": "tenant_001",
    "type": "customer",
    "identity": "user@example.com",
    "identityType": "email",
    "displayName": "Jane Doe",
    "company": "Acme Corp",
    "metadata": {},
    "tags": ["premium"],
    "firstSeenAt": "2026-03-11T10:00:00.000Z",
    "lastSeenAt": "2026-03-11T10:00:00.000Z"
  }
}
**Example request ** 
curl -X POST https://agents.kore.ai/api/contacts \
  -H "Authorization: Bearer abl_sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customer",
    "identity": "user@example.com",
    "identityType": "email",
    "displayName": "Jane Doe",
    "company": "Acme Corp",
    "tags": ["premium"]
  }'

​
GET /api/contacts

Query contacts with optional filters and pagination. Auth is required **Query parameters **
ParameterTypeDescription
typestringFilter by contact type (employee, customer, anonymous)
channelstringFilter by channel
limitintegerItems per page
offsetintegerItems to skip
**Response body ** 
{
  "success": true,
  "data": [
    {
      "id": "ct_abc123",
      "tenantId": "tenant_001",
      "type": "customer",
      "identity": "user@example.com",
      "identityType": "email",
      "displayName": "Jane Doe",
      "metadata": {},
      "tags": ["premium"],
      "firstSeenAt": "2026-03-11T10:00:00.000Z",
      "lastSeenAt": "2026-03-11T14:30:00.000Z"
    }
  ],
  "total": 1
}

​
GET /api/contacts/lookup

Find a contact by identity value (email, phone, or external ID). Auth is required **Query parameters **
ParameterTypeRequiredDescription
identitystringYesIdentity value to search for
identityTypestringNoIdentity type (email, phone, external)
**Example request ** 
curl "https://agents.kore.ai/api/contacts/lookup?identity=user@example.com&identityType=email" \
  -H "Authorization: Bearer abl_sk-your-api-key"

​
GET /api/contacts/:id

Get a contact by ID. Auth is required **Path parameters **
ParameterTypeDescription
idstringContact ID

​
PUT /api/contacts/:id

Update a contact’s information. Auth is required Permission: Admin or write access **Request body ** Same fields as POST /api/contacts. All fields are optional; only provided fields are updated.

​
DELETE /api/contacts/:id

Soft-delete a contact. Sets a deletedAt timestamp rather than permanently removing the record. Auth is required Permission: Admin or write access

​
POST /api/contacts/:id/link-session

Link a contact to an existing session, associating the conversation with a known identity. Auth is required Permission: Admin or write access **Request body **
FieldTypeRequiredDescription
sessionIdstringYesSession ID to link
**Response body ** 
{
  "success": true
}

​
Analytics API

Query and aggregate platform events across sessions and agents. All analytics endpoints are project-scoped and require authentication.

​
Event analytics

Base path: /api/projects/:projectId/analytics

​
GET /api/projects/:projectId/analytics/metrics

Get aggregated event metrics grouped by specified dimensions. Auth is required Permission: session:read **Query parameters **
ParameterTypeDefaultDescription
fromstring24 hours agoISO 8601 start date
tostringNowISO 8601 end date
groupBystringcategoryComma-separated dimensions: category, event_type, agent_name, channel, hour, day
metricsstringcount,error_rateComma-separated metrics: count, avg_duration, error_rate, p95_duration, sum_tokens, sum_cost
categorystring—Filter by event category
**Available event categories **
CategoryDescription
sessionSession lifecycle events
messageMessage send/receive events
llmLLM call events
toolTool execution events
agentAgent-level events
gatherGather step events
flowFlow transition events
channelChannel events
deploymentDeployment lifecycle events
searchSearch/knowledge events
voiceVoice interaction events
auditAudit log events
evaluationEvaluation run events
feedbackUser feedback events
systemSystem-level events
**Example request ** 
curl "https://agents.kore.ai/api/projects/proj_abc/analytics/metrics?from=2026-03-04T00:00:00Z&to=2026-03-11T00:00:00Z&groupBy=category,day&metrics=count,error_rate,sum_cost" \
  -H "Authorization: Bearer abl_sk-your-api-key"
**Example response ** 
{
  "success": true,
  "data": {
    "buckets": [
      {
        "category": "llm",
        "day": "2026-03-10",
        "count": 450,
        "error_rate": 0.02,
        "sum_cost": 12.5
      },
      {
        "category": "tool",
        "day": "2026-03-10",
        "count": 120,
        "error_rate": 0.05,
        "sum_cost": 0
      }
    ]
  }
}

​
GET /api/projects/:projectId/analytics/events

List raw events with filtering and pagination. Auth is required Permission: session:read **Query parameters **
ParameterTypeDefaultDescription
fromstring24 hours agoISO 8601 start date
tostringNowISO 8601 end date
categorystring—Filter by event category
eventTypesstring—Comma-separated event type filter
sessionIdstring—Filter by session ID
agentNamestring—Filter by agent name
hasErrorstring—Set to true to show only error events
limitinteger100Items per page (max 10,000)
offsetinteger0Items to skip
**Example request ** 
curl "https://agents.kore.ai/api/projects/proj_abc/analytics/events?category=llm&hasError=true&limit=20" \
  -H "Authorization: Bearer abl_sk-your-api-key"
**Example response ** 
{
  "success": true,
  "data": {
    "events": [
      {
        "id": "evt_001",
        "category": "llm",
        "event_type": "llm_call",
        "agent_name": "support-agent",
        "session_id": "sess_abc",
        "timestamp": "2026-03-11T10:05:00.000Z",
        "duration_ms": 2400,
        "error": "Rate limit exceeded",
        "metadata": {
          "model": "claude-sonnet-4-20250514",
          "tokens_in": 500,
          "tokens_out": 0
        }
      }
    ],
    "total": 3,
    "hasMore": false
  }
}

​
GET /api/projects/:projectId/analytics/agents/:name

Get performance metrics for a specific agent. Auth is required Permission: session:read **Path parameters **
ParameterTypeDescription
namestringAgent name
**Query parameters **
ParameterTypeDefaultDescription
fromstring24 hours agoISO 8601 start date
tostringNowISO 8601 end date

​
GET /api/projects/:projectId/analytics/cost-breakdown

Get LLM cost breakdown by model and provider. Auth is required Permission: session:read **Query parameters **
ParameterTypeDefaultDescription
fromstring24 hours agoISO 8601 start date
tostringNowISO 8601 end date

​
GET /api/projects/:projectId/analytics/session-metrics

Get session-level aggregated metrics. Auth is required Permission: session:read

​
POST /api/projects/:projectId/analytics/query

Execute an ad-hoc event query with custom filters. Auth is required Permission: session:read **Request body **
FieldTypeRequiredDescription
timeRangeobjectYes{ from: string, to: string } in ISO 8601
categorystringNoEvent category filter
eventTypesarrayNoEvent type filter
sessionIdstringNoSession ID filter
agentNamestringNoAgent name filter
hasErrorbooleanNoError filter
limitintegerNoResult limit (default: 100, max: 10,000)
offsetintegerNoResult offset

​
POST /api/projects/:projectId/analytics/aggregate

Execute an ad-hoc aggregation query. Auth is required Permission: session:read **Request body **
FieldTypeRequiredDescription
timeRangeobjectYes{ from: string, to: string } in ISO 8601
groupByarrayYesDimensions to group by
metricsarrayYesMetrics to compute
filtersobjectNoAdditional filters (category, event types)

​
Voice analytics

Voice-specific analytics with hourly aggregations and summary KPIs. Base path: /api/projects/:projectId/voice-analytics

​
GET /api/projects/:projectId/voice-analytics/hourly

Get hourly aggregated voice metrics. Auth is required Permission: session:read **Query parameters **
ParameterTypeDefaultDescription
hoursinteger168 (7 days)Number of hours to look back
**Response body ** 
{
  "success": true,
  "data": [
    {
      "hour": "2026-03-11T10:00:00.000Z",
      "session_count": 45,
      "error_count": 2,
      "avg_call_duration_ms": 180000,
      "avg_inbound_mos": 4.2,
      "avg_outbound_mos": 4.1,
      "avg_inbound_jitter_ms": 12.5,
      "avg_outbound_jitter_ms": 15.0,
      "avg_e2e_latency_ms": 340,
      "avg_barge_in_rate": 0.15,
      "avg_dtmf_fallback_rate": 0.03,
      "avg_asr_score": 0.92,
      "avg_tts_proxy_mos": 4.0,
      "avg_silence_percent": 0.12,
      "total_turns": 540,
      "total_barge_in_count": 68,
      "total_dtmf_turn_count": 15
    }
  ]
}
**Metric descriptions **
MetricDescription
session_countNumber of voice sessions in the hour
error_countNumber of sessions with errors
avg_call_duration_msAverage call duration in milliseconds
avg_inbound_mosAverage inbound Mean Opinion Score (1-5)
avg_outbound_mosAverage outbound Mean Opinion Score (1-5)
avg_e2e_latency_msAverage end-to-end latency in milliseconds
avg_barge_in_rateAverage rate of user interruptions
avg_asr_scoreAverage speech recognition accuracy (0-1)
total_turnsTotal conversation turns

​
GET /api/projects/:projectId/voice-analytics/summary

Get summary KPIs for dashboard display. Auth is required Permission: session:read **Query parameters **
ParameterTypeDefaultDescription
hoursinteger168 (7 days)Number of hours to look back
**Response body ** 
{
  "success": true,
  "data": {
    "total_calls": 1250,
    "total_errors": 23,
    "avg_call_duration_ms": 195000,
    "overall_avg_inbound_mos": 4.15,
    "overall_avg_outbound_mos": 4.08,
    "overall_avg_latency_ms": 320,
    "overall_barge_in_rate": 0.12,
    "overall_dtmf_fallback_rate": 0.04,
    "overall_asr_score": 0.91,
    "total_turns": 15600,
    "total_barge_in_count": 1872,
    "total_dtmf_turn_count": 624
  }
}

​
Session traces

Detailed execution traces for individual sessions are available through the sessions API.

​
GET /api/projects/:projectId/sessions/:id/traces

See Conversation API — Session traces for full documentation.

​
GET /api/projects/:projectId/sessions/:id/traces/:spanId/children

Get child events for a specific span within a session trace. Auth is required Permission: session:read

​
GET /api/projects/:projectId/sessions/:id/analysis

Get trace analysis and diagnostics for a session. Auth is required Permission: session:read

​
GET /api/projects/:projectId/sessions/generations

List LLM call events across all sessions in a project. Auth is required Permission: session:read

​
GET /api/projects/:projectId/sessions/export

Export session traces as CSV. Auth is required Permission: session:read

​
Project Export/Import API

The project export/import API enables programmatic migration of agent projects between environments. You can export a project’s agents, tools, and deployment configurations as a file map, then import them into another project or instance. Base path: /api/projects/:projectId/project-io

​
Export

​
GET /api/projects/:projectId/project-io/export/preview

Preview what will be exported without generating files. Returns metadata about agents, tools, and dependency validation. Auth is required Permission: project:export **Response body **
FieldTypeDescription
projectobjectProject metadata (name, slug)
agentsarrayAgents with DSL content availability
toolsarrayTools with type information
dependenciesobjectDependency graph edges and validation results
**Example request ** 
curl https://agents.kore.ai/api/projects/proj_abc/project-io/export/preview \
  -H "Authorization: Bearer abl_sk-your-api-key"
**Example response ** 
{
  "project": {
    "name": "Customer Support",
    "slug": "customer-support"
  },
  "agents": [
    { "name": "support-agent", "hasDslContent": true },
    { "name": "escalation-agent", "hasDslContent": true }
  ],
  "tools": [
    { "name": "crm-lookup", "toolType": "api" },
    { "name": "ticket-create", "toolType": "api" }
  ],
  "dependencies": {
    "edges": [
      {
        "from": "support-agent",
        "to": "escalation-agent",
        "type": "handoff"
      },
      {
        "from": "support-agent",
        "to": "crm-lookup",
        "type": "tool"
      }
    ],
    "validation": {
      "valid": true,
      "errors": []
    }
  }
}

​
GET /api/projects/:projectId/project-io/export

Export the full project as a file map with manifest and lockfile. Auth is required Permission: project:export **Query parameters **
ParameterTypeDefaultDescription
formatstringfolderExport format: folder or zip
include_deploymentsstringfalseSet to true to include deployment records
**Response body **
FieldTypeDescription
successbooleanWhether the export succeeded
manifestobjectProject manifest with metadata and checksums
lockfileobjectLockfile with pinned dependency versions
filesobjectMap of file paths to content strings
warningsarrayExport warnings (e.g., agents without DSL content)
**Example request ** 
curl "https://agents.kore.ai/api/projects/proj_abc/project-io/export?include_deployments=true" \
  -H "Authorization: Bearer abl_sk-your-api-key"
**Example response ** 
{
  "success": true,
  "manifest": {
    "name": "customer-support",
    "version": "1.0.0",
    "entryAgent": "support-agent",
    "agents": {
      "support-agent": {
        "sourceHash": "sha256:abc123...",
        "path": "agents/support-agent.abl"
      }
    },
    "exportedAt": "2026-03-11T10:00:00.000Z",
    "exportedBy": "user_123"
  },
  "lockfile": {
    "agents": {
      "support-agent": {
        "version": "3",
        "hash": "sha256:abc123..."
      }
    }
  },
  "files": {
    "agents/support-agent.abl": "AGENT: support-agent\n...",
    "agents/escalation-agent.abl": "AGENT: escalation-agent\nFLOW:\n...",
    "tools/crm-lookup.tools.abl": "TOOLS:\n  - name: crm-lookup\n    ..."
  },
  "warnings": []
}
**Export limits **
LimitValue
Maximum agents1,000
Maximum tools500
Maximum response size100 MB

​
Import

​
POST /api/projects/:projectId/project-io/import/preview

Perform a dry-run import to preview what changes will be applied without modifying any data. Auth is required Permission: project:import **Request body **
FieldTypeRequiredDescription
filesobjectYesMap of file paths to content strings
**Response body **
FieldTypeDescription
successbooleanWhether the preview succeeded
previewobjectPreview of operations that will be performed
errorobjectError details if preview failed
**Example request ** 
curl -X POST https://agents.kore.ai/api/projects/proj_abc/project-io/import/preview \
  -H "Authorization: Bearer abl_sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      "agents/support-agent.abl": "AGENT: support-agent\n...",
      "agents/new-agent.abl": "AGENT: new-agent\nFLOW:\n..."
    }
  }'
**Example response ** 
{
  "success": true,
  "preview": {
    "operations": [
      {
        "type": "update",
        "entity": "agent",
        "name": "support-agent",
        "reason": "Content changed"
      },
      {
        "type": "create",
        "entity": "agent",
        "name": "new-agent",
        "reason": "New agent"
      }
    ],
    "summary": {
      "create": 1,
      "update": 1,
      "delete": 0
    }
  }
}

​
POST /api/projects/:projectId/project-io/import

Apply an import, creating, updating, or deleting agents as needed. Auth is required Permission: project:import **Request body **
FieldTypeRequiredDescription
filesobjectYesMap of file paths to content strings
**Response body **
FieldTypeDescription
successbooleanWhether the import succeeded
appliedobjectSummary of applied changes
{
  "success": true,
  "applied": {
    "created": 1,
    "updated": 1,
    "deleted": 0
  }
}
**Example request ** 
curl -X POST https://agents.kore.ai/api/projects/proj_abc/project-io/import \
  -H "Authorization: Bearer abl_sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      "agents/support-agent.abl": "AGENT: support-agent\n...",
      "agents/new-agent.abl": "AGENT: new-agent\nFLOW:\n..."
    }
  }'
**Import limits **
LimitValue
Maximum file size (per file)1 MB
Maximum total content size50 MB
Maximum file count500
Maximum request body60 MB
Concurrent import lock TTL120 seconds
**Import validation ** The import endpoint validates each file before applying changes:
  • Path traversal prevention: Paths containing .., leading /, null bytes, or backslashes are rejected.
  • File size limits: Individual files exceeding 1 MB are rejected.
  • Total size limits: Combined content exceeding 50 MB is rejected.
  • Concurrent import protection: A distributed lock prevents simultaneous imports to the same project.
**Error responses **
StatusErrorCause
400Request body must contain a “files” objectMissing or invalid files field
400File content must be a stringNon-string value in files map
400Invalid file path (path traversal detected)Path traversal attempt
400File too large (max 1MB)Individual file exceeds size limit
400Total content size exceeds 50MBCombined content too large
400Too many filesFile count exceeds 500
413Request body too largeRequest body exceeds 60 MB
409Import already in progressAnother import is running for this project

​
Workflow: export from one project, import to another

# 1. Export from source project
export EXPORT=$(curl -s \
  "https://agents.kore.ai/api/projects/proj_source/project-io/export" \
  -H "Authorization: Bearer abl_sk-your-api-key")

# 2. Extract the files object
export FILES=$(echo "$EXPORT" | jq '.files')

# 3. Preview import in target project
curl -X POST \
  "https://agents.kore.ai/api/projects/proj_target/project-io/import/preview" \
  -H "Authorization: Bearer abl_sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d "{\"files\": $FILES}"

# 4. Apply import
curl -X POST \
  "https://agents.kore.ai/api/projects/proj_target/project-io/import" \
  -H "Authorization: Bearer abl_sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d "{\"files\": $FILES}"

​
Next steps