API Reference

Base URL: https://api.korastratum.com/ai/api/v1

All endpoints require Authorization and X-Tenant-ID headers unless otherwise noted. See Authentication for details.

Endpoints

Method	Endpoint	Description
GET	/ai/agents	List all registered agent types with metadata
GET	/ai/agents/{agent_id}/status	Get agent status for the authenticated tenant
POST	/ai/agents/{agent_id}/trigger	Manually trigger an agent run
PUT	/ai/agents/{agent_id}/config	Update agent configuration for this tenant
GET	/ai/agents/{agent_id}/decisions	List agent decisions with pagination
GET	/ai/agents/{agent_id}/metrics	Get performance metrics and shadow comparison
POST	/ai/agent-decisions	Log an agent decision (internal use only)

List agents

GET /ai/agents

Returns all registered agent types with their ID, tier, product, and description. This is a catalog of available agents, not tenant-specific configuration.

Response: 200 OK

{
  "agents": [
    {
      "agent_id": "reconciliation_agent",
      "tier": "core",
      "product": "gl",
      "description": "Analyzes reconciliation breaks and auto-resolves simple ones"
    }
  ],
  "total": 22
}

Get agent status

GET /ai/agents/{agent_id}/status

Returns the runtime status of a specific agent for the authenticated tenant, including mode, threshold, last run time, and total runs.

Path parameters:

Parameter	Type	Description
agent_id	string	The agent identifier (e.g., reconciliation_agent)

Response: 200 OK

{
  "agent_id": "reconciliation_agent",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "registered": true,
  "mode": "shadow",
  "auto_act_threshold": "LOW",
  "enabled": true,
  "last_run": "2026-04-06T22:00:00Z",
  "total_runs": 147
}

Trigger agent

POST /ai/agents/{agent_id}/trigger

Manually trigger an agent's Observe-Decide-Act cycle. In shadow mode, the agent observes and decides but does not act.

Path parameters:

Parameter	Type	Description
agent_id	string	The agent identifier

Request body:

{
  "trigger_data": {
    "date": "2026-04-06",
    "account_type": "clearing"
  }
}

Response: 200 OK

{
  "decision_id": "d4e5f6a7-b8c9-4d0e-a1f2-b3c4d5e6f7a8",
  "decision": "resolve",
  "confidence": 92.5,
  "risk_level": "LOW",
  "reasoning": "3 timing breaks within tolerance",
  "action_taken": false,
  "action_result": null
}

Error responses: 400 (disabled agent), 404 (not found), 500 (execution failed)

Update agent config

PUT /ai/agents/{agent_id}/config

Update agent configuration for the authenticated tenant. Supports partial updates — include only the fields you want to change.

Path parameters:

Parameter	Type	Description
agent_id	string	The agent identifier

Request body:

{
  "mode": "active",
  "auto_act_threshold": "MEDIUM",
  "enabled": true,
  "config": {
    "custom_key": "custom_value"
  }
}

Field	Type	Required	Description
mode	string	No	shadow, active, or disabled
auto_act_threshold	string	No	LOW, MEDIUM, HIGH, or CRITICAL
enabled	boolean	No	Enable or disable the agent
config	object	No	Agent-specific custom configuration

Response: 200 OK

{
  "status": "updated",
  "agent_id": "reconciliation_agent",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error responses: 400 (no fields to update), 500 (config update failed)

List decisions

GET /ai/agents/{agent_id}/decisions

List agent decisions with pagination, ordered by most recent first.

Path parameters:

Parameter	Type	Description
agent_id	string	The agent identifier

Query parameters:

Parameter	Type	Default	Description
limit	integer	50	Max results per page (1-200)
offset	integer	0	Number of results to skip

Response: 200 OK

{
  "decisions": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent_id": "reconciliation_agent",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "mode": "shadow",
      "trigger_type": "scheduled",
      "decision": "resolve",
      "confidence": 92.5,
      "risk_level": "LOW",
      "reasoning": "Timing break within T+1 tolerance",
      "action_taken": false,
      "action_result": null,
      "human_decision": "resolve",
      "human_agreed": true,
      "created_at": "2026-04-06T22:00:01Z"
    }
  ],
  "total": 147,
  "limit": 50,
  "offset": 0
}

Get metrics

GET /ai/agents/{agent_id}/metrics

Get performance metrics for an agent, including daily rollups and shadow mode comparison data.

Path parameters:

Parameter	Type	Description
agent_id	string	The agent identifier

Query parameters:

Parameter	Type	Required	Description
date_from	date	No	Start date filter (YYYY-MM-DD)
date_to	date	No	End date filter (YYYY-MM-DD)

Response: 200 OK

{
  "agent_id": "reconciliation_agent",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "daily_metrics": [
    {
      "date": "2026-04-06",
      "total_runs": 12,
      "auto_resolved": 8,
      "escalated": 4,
      "human_agreed": 10,
      "human_disagreed": 2,
      "avg_confidence": 88.7,
      "avg_latency_ms": 245
    }
  ],
  "shadow_comparison": {
    "total_decisions": 147,
    "agreement_rate": 91.2,
    "disagreements": 13
  },
  "ready_for_activation": true
}

Log decision (internal)

POST /ai/agent-decisions

info

This endpoint is used internally by the agent framework. It does not require user authentication and is not accessible from external networks.

Request body:

{
  "decision_id": "d4e5f6a7-b8c9-4d0e-a1f2-b3c4d5e6f7a8",
  "agent_id": "reconciliation_agent",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "resolve",
  "confidence": 92.5,
  "risk_level": "LOW",
  "reasoning": "Timing break within tolerance",
  "action_taken": false,
  "action_result": null,
  "created_at": "2026-04-06T22:00:01Z"
}

Response: 200 OK

{
  "status": "logged",
  "decision_id": "d4e5f6a7-b8c9-4d0e-a1f2-b3c4d5e6f7a8"
}