---
name: neosyntropy-router
description: Builds constrained routing and ranking integrations with the NeoSyntropy Router API. Use for intent routing, candidate selection, queues, tool choice, or reranking where outputs must stay inside a caller-defined set.
---

# NeoSyntropy Router

## Contract

- Base URL: `https://api.neosyntropy.com/api/v1`
- Read `NEOSYNTROPY_API_KEY` from the environment.
- Send `Authorization: Bearer $NEOSYNTROPY_API_KEY`.
- Never place credentials in source, logs, URLs, or browser bundles.

## Choose an endpoint

Use `POST /route` for workflow routing. Send:

- `input`: JSON context.
- `candidates`: 1–9 allowed actions with stable IDs and descriptions.
- `fallback`: one explicit out-of-scope action.
- `metadata`: optional trace context.

Read `execution_plan`, `confidence`, and `out_of_distribution`. Execute only IDs already present in the local allowlist.

Use `POST /rank` to order 2–100 unique candidate strings. Send `context`, optional `question`, `answers`, and a documented model alias.

## Implementation workflow

1. Enumerate the real actions the application can execute.
2. Write descriptions that separate similar candidates.
3. Add an explicit fallback for ambiguous or out-of-scope inputs.
4. Call the endpoint from trusted server code.
5. Validate the response against the original candidate set.
6. Route low-confidence or out-of-distribution results to fallback.
7. Evaluate thresholds on labeled application traffic.

## Few-shot guidance

Put representative examples in the request context or the surrounding application prompt, but keep the actual candidate IDs stable:

```json
{
  "examples": [
    {"message": "charged twice", "expected": "billing"},
    {"message": "cannot sign in", "expected": "account"},
    {"message": "SDK returns 500", "expected": "technical"}
  ]
}
```

Examples guide interpretation. They never expand the allowed action set.

## Safety

- Treat ranking as data, not authorization for a side effect.
- Preserve the fallback even when examples look exhaustive.
- Retry only transient 429 or 503 failures with bounded backoff.
- Do not invent undocumented fields or model IDs.

