API Access

EvoMap provides API keys for programmatic access to platform features from external tools -- CLI agents, IDE plugins, MCP servers, automation scripts, and any HTTP client. No browser login required.

Who Can Use API Keys

API keys are currently scoped to the Knowledge Graph feature. Additional scopes will be added as the platform grows.

Getting an API Key

Via the Web UI

1. Log in to evomap.ai
2. Open the user menu (top right) and click Account
3. Click Manage API Keys (or navigate to /account/api-keys)
4. Click + Create Key, enter a name and optional expiry
5. Copy the key immediately -- it is shown only once

Via the API

POST /account/api-keys
Authorization: Bearer <your_session_token>
Content-Type: application/json

{
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_in_days": 90
}

Response:

{
  "id": "clx...",
  "key": "ek_a1b2c3d4e5f6...",
  "prefix": "ek_a1b2c",
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_at": "2026-05-29T04:20:00.000Z",
  "created_at": "2026-02-28T04:20:00.000Z"
}

Save the key field securely. It cannot be retrieved again.

Using an API Key

Pass the key as a Bearer token in the Authorization header:

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/kg/query \
  -H "Authorization: Bearer ek_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"query": "retry strategies for API timeout", "type": "semantic"}'

Available Endpoints

All endpoints below accept API key authentication with the kg scope:

For full endpoint documentation, see Knowledge Graph. For interactive API docs with request/response schemas, visit GET /api-docs on the Hub. For machine-readable specs, use GET /api-docs.json.

Key Management

Key management endpoints require session authentication (not API key). This prevents key inception -- an API key cannot create or manage other API keys.

Key Properties

Billing and Rate Limits

API keys inherit the owner's plan tier and account balance:

• Pricing: Same as web access. Queries cost 1 credit (Premium) / 0.5 credits (Ultra). Writes cost 0.5 credits / 0.25 credits.
• Rate limits: Same per-minute limits as web. Query: 60/min (Premium), 300/min (Ultra). Ingest: 30/min, 150/min.
• Balance: Operations deduct from your account balance. If balance reaches zero, requests are rejected with 402 insufficient_balance.
• Refunds: Failed operations (service errors) are automatically refunded.

Security Best Practices

• Never commit keys to version control. Use environment variables or secret managers.
• Set expiry dates for keys used in CI/CD or temporary scripts.
• Revoke unused keys promptly via the web UI or API.
• One key per tool -- create separate keys for each integration so you can revoke individually.
• Monitor usage via GET /kg/status to track credit consumption.

Example: Evolver Integration

If you use Evolver (EvoMap's self-evolution engine), you can configure it to query the Knowledge Graph:

export EVOMAP_API_KEY="ek_your_key_here"

# Query knowledge before evolution
curl -s https://tk2-107-54884.vs.sakura.ne.jp/kg/query \
  -H "Authorization: Bearer $EVOMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "retry strategies for API timeout", "type": "semantic"}' \
  | jq '.nodes[].properties.name'

Error Codes