HTTP API

Use the REST API directly when an official SDK is not available for your language.

Base URL


https://api.kaplaix.com

Authentication

All requests require a Bearer token in the Authorization header:


Authorization: Bearer al_live_your_key_here

Endpoints summary

Method	Path	Description
`POST`	`/v1/events`	Ingest an event
`GET`	`/v1/sessions`	List sessions
`GET`	`/v1/sessions/:id`	Get session detail
`GET`	`/v1/sessions/:id/risk`	Compute risk score
`GET`	`/v1/sessions/:id/export.json`	Export session as JSON
`POST`	`/v1/agents`	Register agent
`GET`	`/v1/agents`	List agents
`GET`	`/v1/agents/:id`	Get agent
`PATCH`	`/v1/agents/:id`	Update agent
`GET`	`/v1/agents/:id/sessions`	List agent sessions
`POST`	`/v1/policies`	Create policy
`GET`	`/v1/policies`	List policies
`GET`	`/v1/policies/:id`	Get policy
`PATCH`	`/v1/policies/:id`	Update policy
`DELETE`	`/v1/policies/:id`	Archive policy
`POST`	`/v1/policies/check`	Check action against policy
`GET`	`/v1/guardian/pending-actions`	List pending actions
`POST`	`/v1/guardian/pending-actions/:id/decide`	Decide pending action
`POST`	`/v1/notification-channels`	Create webhook
`GET`	`/v1/notification-channels`	List webhooks

Sending an event


curl -X POST https://api.kaplaix.com/v1/events \
  -H "Authorization: Bearer al_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "agentId": "my-agent",
    "sessionId": "session-001",
    "sourceTimestamp": "2025-01-15T10:30:00Z",
    "category": "tool_api",
    "schemaVersion": "1.0",
    "payload": {
      "toolName": "web_search",
      "argumentsHash": "sha256-of-args",
      "responseStatus": 200
    }
  }'

Error format

All errors follow the same envelope:


{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable message",
    "details": [...]
  }
}

See Error Codes for the full list.

Pagination

List endpoints use cursor-based pagination:


# First page
curl "https://api.kaplaix.com/v1/sessions?limit=20"
 
# Next page
curl "https://api.kaplaix.com/v1/sessions?limit=20&cursor=eyJsYXN0..."

The nextCursor field is null when there are no more results.

Recommended headers

When building a custom integration, set these headers for better observability:

Header	Example	Purpose
`x-kaplaix-sdk`	`custom/1.0`	Identify your integration
`x-kaplaix-framework`	`langchain`	AI framework name
`x-kaplaix-agent-version`	`2.1.0`	Your agent version

Retry strategy

For production use, implement retries on these status codes:

Status	Meaning	Action
`429`	Rate limited	Retry after `Retry-After` header
`502`	Bad gateway	Retry with backoff
`503`	Service unavailable	Retry with backoff
`504`	Gateway timeout	Retry with backoff

Use exponential backoff with jitter. The official SDKs default to 3 retries.