Skip to main content

Documentation Index

Fetch the complete documentation index at: https://koreai-v2-home-nav.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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 required: Yes (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://api.ablplatform.com/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://api.ablplatform.com/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://api.ablplatform.com/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 required: Yes 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://api.ablplatform.com/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 required: Yes
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 required: Yes
Query parameters
ParameterTypeRequiredDescription
identitystringYesIdentity value to search for
identityTypestringNoIdentity type (email, phone, external)
Example request
curl "https://api.ablplatform.com/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 required: Yes
Path parameters
ParameterTypeDescription
idstringContact ID

PUT /api/contacts/:id

Update a contact’s information. Auth required: Yes 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 required: Yes 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 required: Yes 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 required: Yes 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
categorystringFilter 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://api.ablplatform.com/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 required: Yes Permission: session:read
Query parameters
ParameterTypeDefaultDescription
fromstring24 hours agoISO 8601 start date
tostringNowISO 8601 end date
categorystringFilter by event category
eventTypesstringComma-separated event type filter
sessionIdstringFilter by session ID
agentNamestringFilter by agent name
hasErrorstringSet to true to show only error events
limitinteger100Items per page (max 10,000)
offsetinteger0Items to skip
Example request
curl "https://api.ablplatform.com/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 required: Yes 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 required: Yes 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 required: Yes Permission: session:read

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

Execute an ad-hoc event query with custom filters. Auth required: Yes 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 required: Yes 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 required: Yes 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 required: Yes 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 required: Yes Permission: session:read

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

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

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

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

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

Export session traces as CSV. Auth required: Yes 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 required: Yes 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://api.ablplatform.com/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 required: Yes 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://api.ablplatform.com/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 required: Yes 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://api.ablplatform.com/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 required: Yes 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://api.ablplatform.com/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://api.ablplatform.com/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://api.ablplatform.com/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://api.ablplatform.com/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