API Reference

Base URL: https://api.getkapex.ai/api/v1

All requests require the X-API-Key header (except trial signup and health endpoints). All request and response bodies are JSON.

Authentication

X-API-Key: your_api_key_here
Content-Type: application/json

See Authentication for details on API key management and rate limits.

POST /trial/signup

Create a new trial account and receive an API key.

Authentication: None required.

Request

curl -X POST https://api.getkapex.ai/api/v1/trial/signup \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Health",
    "email": "dev@acmehealth.com",
    "name": "Jordan Park"
  }'

Response `201 Created`

{
  "status": "trial_active",
  "tenant_id": "tn_acme_health_01",
  "api_key": "a1b2c3d4e5f6g7h8i9j0",
  "trial_ends": "2026-07-18T00:00:00Z",
  "limits": {
    "max_users": 25,
    "max_nodes_per_user": 5000,
    "rate_limit_rpm": 60,
    "rate_limit_daily": 10000,
    "features": "all"
  },
  "quickstart": "https://docs.getkapex.ai/",
  "base_url": "https://api.getkapex.ai/api/v1"
}

The api_key is only returned once. Store it securely.

Error Responses

POST /ingest

Store a new memory in the user's graph. KAPEX scores the content, extracts entities, creates embeddings, and runs safety checks.

Request

curl -X POST https://api.getkapex.ai/api/v1/ingest \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_001",
    "content": "I just got promoted to engineering manager at Dataflow. My team is 12 people now."
  }'

Response `201 Created`

{
  "node_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scoring": {
    "base_score": 0.48,
    "sdv": 0.62,
    "cscv": 0.0,
    "lcs": 0.55,
    "swv": 0.41,
    "pdv": 0.0,
    "signal_modifiers_applied": true
  },
  "entities_created": [
    "Dataflow",
    "engineering manager"
  ],
  "safety": {
    "crisis_detected": false
  }
}

Scoring fields:

Error Responses

POST /ingest/batch

Store multiple memories in a single request. Each item follows the same schema as the single ingest endpoint.

Request

curl -X POST https://api.getkapex.ai/api/v1/ingest/batch \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "user_id": "user_001",
        "content": "Got promoted to engineering manager at Dataflow."
      },
      {
        "user_id": "user_001",
        "content": "My team is 12 people now. Feeling overwhelmed."
      }
    ]
  }'

Response `200 OK`

{
  "results": [
    { "status": "stored", "node_id": "..." },
    { "status": "stored", "node_id": "..." }
  ],
  "total": 2,
  "succeeded": 2,
  "failed": 0
}

POST /query

Retrieve the most relevant memories for a user's current input. Returns a pre-formatted context block ready for LLM system prompt injection.

Request

curl -X POST https://api.getkapex.ai/api/v1/query \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_001",
    "current_input": "I am feeling overwhelmed at work lately"
  }'

Response `200 OK`

{
  "context": "## Known Context\n- Jordan was recently promoted to engineering manager at Dataflow, leading a team of 12.\n- Jordan has mentioned feeling stressed about the transition to management.\n- Jordan values mentorship and has expressed interest in leadership development.",
  "node_count": 3,
  "confidence": "HIGH",
  "retrieval_channels": {
    "salience": 2,
    "recency": 1,
    "constraints": 0
  },
  "nodes": [
    {
      "node_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "topic": "career promotion",
      "salience": 0.72,
      "framing": "assert"
    },
    {
      "node_id": "c89ab12d-3456-7890-abcd-ef1234567890",
      "topic": "management stress",
      "salience": 0.61,
      "framing": "hedged"
    },
    {
      "node_id": "d12ef34a-5678-9012-bcde-f12345678901",
      "topic": "leadership interests",
      "salience": 0.34,
      "framing": "hook"
    }
  ]
}

The context field is a pre-formatted text block. Insert it directly into your LLM's system prompt.

Context confidence levels:

Framing tiers determine how each memory is presented in the context block:

Error Responses

POST /score

Dry-run scoring. Scores content using the same pipeline as /ingest but does not store anything. Useful for testing how KAPEX will rate a piece of content before committing it.

Request

curl -X POST https://api.getkapex.ai/api/v1/score \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I just got promoted to engineering manager",
    "include_signals": true
  }'

Response `200 OK`

{
  "base_score": 0.72,
  "categories": ["career", "achievement"],
  "decay_modifier": 1.0,
  "signal_scores": {
    "sdv": 0.75,
    "cscv": 0.0,
    "lcs": 0.55,
    "swv": 0.60,
    "pdv": 0.0
  }
}

The signal_scores field is only included when include_signals is true.

Error Responses

POST /process/{node_id}

Register a processing event on a memory node. Each processing event increases the node's decay rate, modeling the principle that well-processed memories become less urgent over time.

Request

curl -X POST "https://api.getkapex.ai/api/v1/process/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_001"
  }'

Response `200 OK`

{
  "node_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "processed",
  "processing_count": 4
}

Error Responses

GET /nodes/{node_id}

Retrieve the full detail for a specific memory node.

Request

curl "https://api.getkapex.ai/api/v1/nodes/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-API-Key: your_api_key_here"

Response `200 OK`

{
  "node_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "topic": "career promotion",
  "summary": "Promoted to engineering manager at Dataflow, leading team of 12",
  "current_salience": 0.72,
  "base_score": 0.68,
  "domain": "work",
  "entities": ["Dataflow", "engineering manager"],
  "processing_count": 3,
  "created_at": "2026-06-15T14:30:00Z",
  "last_accessed": "2026-06-18T09:12:00Z"
}

Error Responses

GET /context/{user_id}

Retrieve structured, domain-organized context for a user's memory graph. Unlike /query (which takes a current input and returns relevance-scored results), this endpoint returns the full organized context for the user.

Request

curl "https://api.getkapex.ai/api/v1/context/user_001" \
  -H "X-API-Key: your_api_key_here"

Response `200 OK`

{
  "domains": [
    {
      "name": "work",
      "entities": [
        {
          "name": "Dataflow",
          "salience": 0.72,
          "facets": ["engineering manager", "team of 12"],
          "themes": ["management transition stress"]
        }
      ]
    }
  ],
  "total_entities": 42,
  "total_domains": 5
}

Error Responses

DELETE /users/{user_id}

Permanently delete all data for a user. This is an atomic operation that removes all memory nodes, entities, edges, domain memberships, processing history, and cached results. Supports GDPR Article 17 (Right to Erasure) and CCPA compliance.

Request

curl -X DELETE "https://api.getkapex.ai/api/v1/users/user_001" \
  -H "X-API-Key: your_api_key_here"

Response `200 OK`

{
  "status": "deleted",
  "user_id": "user_001",
  "nodes_deleted": 47
}

This operation is irreversible. All nodes, edges, memberships, and cached data for the user are permanently removed.

Error Responses

GET /stats

Retrieve usage statistics for your trial or account.

Request

curl https://api.getkapex.ai/api/v1/stats \
  -H "X-API-Key: your_api_key_here"

Response `200 OK`

{
  "tier": "trial",
  "trial": {
    "trial_ends": "2026-07-18T00:00:00Z",
    "days_remaining": 22
  },
  "users": {
    "total": 3,
    "limit": 25
  },
  "memory_nodes": {
    "total": 87,
    "avg_salience": 0.41,
    "high_salience": 12
  },
  "api_calls": {
    "today": 142,
    "this_month": 1205,
    "rpm_limit": 60,
    "daily_limit": 10000
  }
}

Error Responses

GET /profile

Retrieve the active configuration profile for your tenant.

Request

curl https://api.getkapex.ai/api/v1/profile \
  -H "X-API-Key: your_api_key_here"

Response `200 OK`

Returns the full configuration profile including preset name and all parameters. See Config Presets for details.

PUT /profile

Update your tenant's configuration profile. You can apply a named preset or provide custom parameter overrides.

Request (preset)

curl -X PUT https://api.getkapex.ai/api/v1/profile \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "reflective"
  }'

Request (custom overrides)

curl -X PUT https://api.getkapex.ai/api/v1/profile \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": {
      "decay_profile": {
        "base_rate": 0.01,
        "processing_boost": 0.5
      },
      "injection_template": {
        "max_tokens": 8000
      }
    }
  }'

See Config Presets for available presets and configuration options.

Error Responses

GET /profile/presets

List all available configuration presets.

Request

curl https://api.getkapex.ai/api/v1/profile/presets \
  -H "X-API-Key: your_api_key_here"

Response `200 OK`

Returns a list of available preset names and their descriptions.

GET /diagnostics/{user_id}

Retrieve diagnostic information for a user's memory graph. Useful for debugging retrieval behavior and understanding graph health.

Request

curl "https://api.getkapex.ai/api/v1/diagnostics/user_001" \
  -H "X-API-Key: your_api_key_here"

Response `200 OK`

Returns graph metrics including domain distribution, salience distribution, entity counts, and retrieval statistics.

GET /health

System health check. No authentication required.

Request

curl https://api.getkapex.ai/api/v1/health

Response `200 OK`

{
  "status": "ok",
  "version": "v8.0.0"
}

Common Error Response Format

All error responses follow a consistent format:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: user_id"
  }
}

Error Codes

Rate Limits

When rate limited, the response includes a Retry-After header indicating how many seconds to wait before retrying. See Authentication for details.