Router API

The Router classifies task intent, selects specialist models, and executes requests against model providers. It sits between the Security Gate (which validates inputs) and the Verifier (which validates outputs).

Base URL: https://router.tismjedi-homelab.com

Health Check

GET /health

Response

{
  "status": "ok",
  "service": "nomos-router"
}

Route

Classify a task and produce an execution plan without executing it. Useful for inspecting what the router would do before committing.

POST /route

Request Body

Field	Type	Required	Description
`text`	string	Yes	The task description or user message
`attestation_id`	string	Yes	Valid attestation ID from the Security Gate

Example

curl -s -X POST https://router.tismjedi-homelab.com/route \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Review this Go code for security vulnerabilities",
    "attestation_id": "att_7f3a9b2c1d4e5f6a"
  }' | jq .

Response

{
  "id": "plan_8e2f1a3b4c5d6e7f",
  "status": "planned",
  "attestation_id": "att_7f3a9b2c1d4e5f6a",
  "tasks": [
    {
      "id": "task_1a2b3c4d",
      "type": "security_analysis",
      "specialist": "security",
      "model": "claude-opus-4-20250514",
      "provider": "anthropic",
      "status": "pending",
      "result": null,
      "tokens_used": 0,
      "cost": 0.0,
      "elapsed_ms": 0
    }
  ]
}

The response includes the full plan with model and provider assignments. The plan is not executed until you call /dispatch.

Dispatch

Execute a previously created plan.

POST /dispatch

Request Body

Field	Type	Required	Description
`plan_id`	string	Yes	The plan ID returned by `/route`

Example

curl -s -X POST https://router.tismjedi-homelab.com/dispatch \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "plan_8e2f1a3b4c5d6e7f"}' \
  | jq .

Response

{
  "id": "plan_8e2f1a3b4c5d6e7f",
  "status": "completed",
  "attestation_id": "att_7f3a9b2c1d4e5f6a",
  "tasks": [
    {
      "id": "task_1a2b3c4d",
      "type": "security_analysis",
      "specialist": "security",
      "model": "claude-opus-4-20250514",
      "provider": "anthropic",
      "status": "completed",
      "result": "## Security Review\n\n### Critical Issues\n1. SQL injection in `handleQuery`...",
      "tokens_used": 1523,
      "cost": 0.0187,
      "elapsed_ms": 4231
    }
  ]
}

Route and Execute

Combined endpoint that routes and executes in a single call. This is the most common usage pattern.

POST /route-and-execute

Request Body

Field	Type	Required	Description
`text`	string	Yes	The task description or user message
`attestation_id`	string	Yes	Valid attestation ID from the Security Gate

Example

curl -s -X POST https://router.tismjedi-homelab.com/route-and-execute \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Convert this CSV data to a normalized JSON schema",
    "attestation_id": "att_7f3a9b2c1d4e5f6a"
  }' | jq .

Response

{
  "id": "plan_3c4d5e6f7a8b9c0d",
  "status": "completed",
  "attestation_id": "att_7f3a9b2c1d4e5f6a",
  "tasks": [
    {
      "id": "task_5e6f7a8b",
      "type": "data_analysis",
      "specialist": "analyst",
      "model": "gemini-2.5-pro",
      "provider": "google",
      "status": "completed",
      "result": "{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  ...",
      "tokens_used": 876,
      "cost": 0.0043,
      "elapsed_ms": 2156
    }
  ]
}

Check Plan Status

Check the current status of a plan. Useful for long-running tasks or when using the separate route/dispatch flow.

GET /status/:id

Example

curl -s https://router.tismjedi-homelab.com/status/plan_8e2f1a3b4c5d6e7f | jq .

Response

{
  "id": "plan_8e2f1a3b4c5d6e7f",
  "status": "executing",
  "attestation_id": "att_7f3a9b2c1d4e5f6a",
  "tasks": [
    {
      "id": "task_1a2b3c4d",
      "type": "security_analysis",
      "specialist": "security",
      "model": "claude-opus-4-20250514",
      "provider": "anthropic",
      "status": "executing",
      "result": null,
      "tokens_used": 0,
      "cost": 0.0,
      "elapsed_ms": 0
    }
  ]
}

Response Schema

All router endpoints return the same plan structure.

Plan Object

Field	Type	Description
`id`	string	Unique plan identifier
`status`	string	`planned`, `executing`, `completed`, or `failed`
`attestation_id`	string	The attestation from the Security Gate
`tasks`	array	List of task objects

Task Object

Field	Type	Description
`id`	string	Unique task identifier
`type`	string	Classified task type
`specialist`	string	Specialist role assigned
`model`	string	Model selected for execution
`provider`	string	API provider
`status`	string	`pending`, `executing`, `completed`, or `failed`
`result`	string or null	Model response (null until completed)
`tokens_used`	integer	Total tokens consumed
`cost`	float	Estimated cost in USD
`elapsed_ms`	integer	Execution time in milliseconds

Task Types

The router classifies inputs into one of the following task types:

Type	Description	Typical Specialist
`code_generation`	Writing new code	`coder`
`code_review`	Reviewing existing code	`reviewer`
`security_analysis`	Security audit, vulnerability analysis	`security`
`document_analysis`	Summarization, extraction, understanding	`analyst`
`media_conversion`	Format conversion, data transformation	`converter`
`strategic_reasoning`	Planning, decision-making, complex reasoning	`strategist`
`data_analysis`	Data processing, statistics, visualization	`analyst`
`general_chat`	General conversation, Q&A	`generalist`

Specialist-to-Model Mapping

The router maintains a configurable mapping from specialist roles to preferred models. The current defaults:

Specialist	Primary Model	Fallback
`coder`	Claude Sonnet	GPT-4o
`reviewer`	Claude Opus	GPT-4o
`security`	Claude Opus	GPT-4o
`analyst`	Gemini 2.5 Pro	Claude Sonnet
`converter`	GPT-4o	Claude Sonnet
`strategist`	Claude Opus	Gemini 2.5 Pro
`generalist`	Claude Sonnet	GPT-4o

Error Responses

400 Bad Request

{
  "error": "bad_request",
  "message": "Missing required field: attestation_id"
}

403 Forbidden

Invalid or expired attestation.

{
  "error": "invalid_attestation",
  "message": "Attestation att_xxx is not valid or has expired"
}

404 Not Found

Plan ID does not exist.

{
  "error": "not_found",
  "message": "Plan plan_xxx not found"
}

502 Bad Gateway

Upstream model provider returned an error.

{
  "error": "provider_error",
  "message": "Anthropic API returned 529: Overloaded",
  "provider": "anthropic"
}

500 Internal Server Error

{
  "error": "internal_error",
  "message": "Routing pipeline failed"
}