Skill router contract

POST /api/v1/skills/route takes a user’s message and answers with the skills to show the model for it, plus a routing_id that ties the run to that answer. It needs an API key and is on every plan. Every framework’s agent_config() makes these calls for you, so you need this page only to call the API directly. Setup is on Frameworks. What the model receives is on How skills reach the model.

Route a message

curl -X POST https://api.decimal.ai/api/v1/skills/route \
  -H "Authorization: Bearer $DECIMAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Can I get a refund on a settled payment?", "agent_name": "support-agent", "top_k": 5}'

Field	Default	What it does
`query`	required	The user’s message
`agent_name`	none	Route among this agent’s skills. Without it, the organization-wide set
`top_k`	10	The most rows a `smart_routing` answer returns
`category`	none	Only skills in this category
`include_attachments`	`true`	Add each row’s bundled files to a `smart_routing` answer
`evaluation`	`false`	Mark an evaluation run: it joins no experiment and stays out of the agent’s numbers. Needs `agent_name`
`prompt_version`	none	An evaluation run on this saved prompt version, whose text comes back under `prompt`
`exclude_skills`	none	An evaluation run without these skills
`experiments`	none	`this_run` lets a running experiment put this run in a group. `capable` only names the experiment

An optional X-Decimal-Route-Budget: <seconds> header, up to 30, says how long you’ll wait for the answer.

The answer

{
  "strategy": "smart_routing",
  "skills": [
    {
      "name": "refund-policy",
      "description": "Process refunds for settled payments.",
      "version": 4,
      "relevance": 0.84,
      "performance": 0.87,
      "score": 0.91,
      "attachments": null
    }
  ],
  "prompt_fragment": "## Recommended Skills\n\n| Skill | Description | Relevance |\n...",
  "query_ranked": true,
  "routing_id": "rt_a1b2c3d4e5f60718a9b0c1d2"
}

`strategy`	When	Rows carry
`full_menu`	The whole list fits in 30 rows and about 1,500 estimated tokens, or ranking failed. `top_k` doesn’t apply	`name`, `description`, `version`
`smart_routing`	The list is larger. Text and vector search find candidates, then pass rates from the last 30 days re-rank them	Those, plus `relevance`, `performance`, `score`, `activation_count`, `trend`, `attachments` and debugging fields such as `rrf_raw`. Also `skill_id`, except on a row with attachments

GET /api/v1/skills/menu returns the full_menu shape with no message to rank by.

Field	What it means
`prompt_fragment`	The list and its instruction, ready for a system prompt
`stable_menu`, `stable_menu_skills`, `menu_instruction`, `routing_hint`	The same pieces apart. `stable_menu` doesn’t change with the message, so it can sit in a cached prompt prefix. `routing_hint` names the best matches, or is empty
`always_include`	`name` and `version` of skills the agent always gets in full
`query_ranked`	Whether this message set the order. `false` means the list isn’t about this message, as with small talk
`routing_id`	`rt_` and 24 hex characters. `null` if the decision couldn’t be saved: leave it off the trace
`relevance`	0 to 1, against the other candidates. `null` when there’s only one
`performance`	The skill’s pass rate, or 0.5 with no data
`attachments`	`null`, or files under `scripts`, `references`, `templates` and `assets`. Script text is inline up to 100 KB in total. Other files list metadata only
`skill_count`, `desc_tokens`, `rows_total`, `truncated`	`full_menu` only: rows returned, estimated tokens, rows eligible, and whether caps dropped any
`experiment`, `prompt`, `evaluation`	Present when the request asked for them

When something fell back, the answer adds degraded: true and a reason:

`degraded_reason`	What happened
`embedding_unavailable`, `embedding_unsupported`	The message couldn’t be embedded, so search used text matching alone
`performance_unavailable`	Pass rates couldn’t be read, so ranking used search alone
`no_retrieval_candidates`, `thin_retrieval_candidates`, `retrieval_failed`	Search found nothing, saw too little of the list, or failed. The answer is `full_menu`

Errors

Errors has the body shape.

Status	When
400	`query` is missing or empty
401, 403	The key is missing or invalid (401), or revoked or expired (403)
422	A malformed evaluation or `experiments` field, an evaluation run with no `agent_name`, or a version or skill that agent doesn’t have
429	Over your rate limit, or the server is shedding load. Honor `Retry-After`

Load a skill’s text

curl "https://api.decimal.ai/api/v1/skills/refund-policy/body?agent_name=support-agent&routing_id=rt_a1b2c3d4e5f60718a9b0c1d2" \
  -H "Authorization: Bearer $DECIMAL_API_KEY"

It returns name, version, version_id, skill_id, description, body, truncated, total_chars, content_hash and content_hash_matches_body.

Parameter	What it does
`routing_id`	The decision this load belongs to. A skill reachable only through the public registry is then served only if that decision offered it (404 otherwise). Skills your organization owns, has installed or has assigned are always served. Send it empty when routing returned no decision. Omit it outside a run
`agent_name`	Serve the version this agent was offered. Without it, the decision’s agent
`version`	A specific version number
`max_chars`	Trim the body (256 or more). `truncated` is then `true` and `content_hash_matches_body` is `false`

content_hash names the version: it’s the SHA-256 of the full text. Copy it onto the trace rather than computing your own. This route doesn’t count loads: the limits on a run are the SDK’s.

Raw trace ingest: the manifest handshake

A load reports back through the trace. Without the SDK, that takes three calls:

Register a manifest, once per agent version: POST /api/v1/manifests with manifest_hash (required), agent_name, version_label and components. Keep the manifest_id it returns.
Route the message and put prompt_fragment in your system prompt. Keep the routing_id.
Send the trace with POST /api/v1/traces:

{
  "agent_name": "support-agent",
  "manifest_id": "0b8e7f52-3c1d-4a96-8e27-5d4f1a6c9b30",
  "routing_id": "rt_a1b2c3d4e5f60718a9b0c1d2",
  "skills_offered_in_prompt": ["refund-policy", "shipping-policy"],
  "active_skills": [{"name": "refund-policy", "content_hash": "<content_hash from the load>"}]
}

Field	What it does
`manifest_id`	Required. A UUID of a manifest in your organization, or ingest answers 400
`routing_id`	Joins the trace to the decision. An unknown id doesn’t fail ingest, but those loads drop out of the offered-versus-loaded numbers
`skills_offered_in_prompt`	Names on the list the model saw: Offered
`skills_delivered`	Names whose text reached the model: Delivered
`skills_loaded_by_agent`	Names the model asked for: Loaded
`active_skills`	Loaded, with the version: `name` and `content_hash`, and optionally `skill_id` and `version_id`

From Python with no framework, decimalai.ingest_raw(payload) posts the same dict.

Python SDK

Skills in your repo

CLI

REST

Skill router contract

Route a message

The answer

Errors

Load a skill’s text

Raw trace ingest: the manifest handshake

​Route a message

​The answer

​Errors

​Load a skill’s text

​Raw trace ingest: the manifest handshake

Route a message

The answer

Errors

Load a skill’s text

Raw trace ingest: the manifest handshake