canonical: https://jentic.com/apis/api.notdiamond.ai/notdiamond

# Not Diamond API

Jentic publishes the only available OpenAPI specification for Not Diamond API, keeping it validated and agent-ready. Not Diamond is an AI model router that picks the most suitable large language model for each prompt based on quality, cost, and latency preferences. The API exposes model selection, prompt optimisation, custom router training, and user preference management so applications can offload routing decisions instead of hard-coding a single provider. It returns a recommended model per request and supports asynchronous prompt optimisation jobs that improve prompts before they are sent to the underlying LLM.

## For AI agents

Route a prompt to the best LLM for cost, quality, or latency, optimise prompts asynchronously, and train a custom router for your workload.

## Scope

Does not host or run language models, fine-tune base models, or stream completions - use for model selection and prompt optimisation only.

## Capabilities

- Select the best LLM for a given prompt and preference profile via `/v2/modelRouter/modelSelect`
- Create, update, and delete user preference profiles that bias model selection
- Submit a prompt for asynchronous optimisation with `/v2/prompt/optimize` and poll status
- Retrieve optimised prompt results and per-run cost breakdowns
- Train a custom router on labelled data via `/v2/pzn/trainCustomRouter`
- List currently supported models from `/v2/models`

## Use cases

### Cost-Aware Model Routing

Route each incoming prompt to the cheapest model that meets a configured quality threshold by calling `/v2/modelRouter/modelSelect` with a user preference profile. This shifts routing logic out of the application and into Not Diamond, so adding a new provider or changing weights does not require redeploying. Useful for SaaS products that want to expose 'auto' as a model choice without locking customers to one vendor.

Example prompt: Call POST `/v2/modelRouter/modelSelect` with a user preference favouring cost, supply the prompt, and return the recommended model identifier.

### Asynchronous Prompt Optimisation

Improve underperforming prompts by submitting them to `/v2/prompt/optimize`, polling `/v2/prompt/optimizeStatus` until the run completes, and retrieving the rewritten prompt from `/v2/prompt/optimizeResults.` The cost endpoint returns a breakdown of compute spent during the run so teams can budget the optimisation pipeline. This is suited to teams running prompt experiments at scale rather than ad-hoc tuning.

Example prompt: Submit a baseline prompt to POST `/v2/prompt/optimize`, poll `/v2/prompt/optimizeStatus/{id}` every 30 seconds, and return the optimised prompt once status is complete.

### Custom Router Training

Train a routing model tailored to your traffic by sending labelled examples to `/v2/pzn/trainCustomRouter.` The custom router can then be selected during model selection so that decisions reflect your evaluation criteria rather than the generic default. Suitable for teams with a stable internal eval set who want better routing on domain-specific prompts.

Example prompt: Send a training payload of prompt-completion pairs with labels to POST `/v2/pzn/trainCustomRouter` and capture the resulting custom router identifier.

### AI Agent LLM Selection via Jentic

Let an autonomous agent decide which LLM to use for each tool call by invoking the Not Diamond router through Jentic. The agent does not need to maintain a price-per-token table - Jentic returns the right modelSelect operation, the agent loads the schema, and the router responds with a model name to call next. Combined with Jentic credential isolation, this keeps Not Diamond's bearer token out of agent prompts.

Example prompt: Search Jentic for 'select the best LLM for this prompt', load Not Diamond's modelSelect schema, execute it with the agent's current prompt, and forward the result to the chosen model.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v2/modelRouter/modelSelect` | Select the best model for a prompt |
| POST | `/v2/preferences/userPreferenceCreate` | Create a user preference profile |
| POST | `/v2/prompt/optimize` | Submit a prompt for asynchronous optimisation |
| GET | `/v2/prompt/optimizeStatus/{optimization_run_id}` | Check optimisation run status |
| GET | `/v2/prompt/optimizeResults/{optimization_run_id}` | Retrieve optimised prompt results |
| POST | `/v2/pzn/trainCustomRouter` | Train a custom router |
| GET | `/v2/models` | List supported models |

## Key resources

- **Model Router** — Select the best model for a prompt
- **Preferences** — Create, update, and delete user preference profiles
- **Prompt Optimisation** — Async optimisation jobs with status, results, and cost endpoints
- **Custom Router** — Train a router on labelled data
- **Models** — List supported underlying LLMs

## Why Jentic

- **Setup:** Wiring Not Diamond by hand means setting up its bearer auth, polling the optimizeStatus and optimizeResults calls yourself, and threading run ids between steps. Through Jentic you install once, import Not Diamond from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Not Diamond takes its targets in the request body for the core routing and optimization calls, so scope the agent to the operations it needs, such as modelSelect and prompt optimize, and leave out training a custom router unless you add it. You choose the allowed operations, so the agent only calls what you list.
- **Credential handling:** Your Not Diamond bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'select the best LLM for this prompt' or 'optimize a prompt', and Jentic returns the matching Not Diamond operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenRouter API** — Unified gateway across many LLM providers with per-model pricing
- **Portkey AI Gateway** — AI gateway with routing, fallbacks, caching, and observability
- **Langfuse API** — Tracing and evaluation for LLM applications

## FAQ

### Why is there no official OpenAPI spec for Not Diamond API?

Not Diamond does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Not Diamond API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Not Diamond API use?

The Not Diamond API uses HTTP bearer token authentication. Each request must include an `Authorization: Bearer <token>` header. Through Jentic, the bearer token is stored encrypted in your Jentic One instance and injected at execution time, so it never appears in agent prompts or logs.

### Can I optimise prompts asynchronously with the Not Diamond API?

Yes. POST `/v2/prompt/optimize` starts an optimisation run and returns a run identifier. Poll `/v2/prompt/optimizeStatus/{optimization_run_id}` until the job is complete, then read `/v2/prompt/optimizeResults/{optimization_run_id}` for the rewritten prompt and `/v2/prompt/optimize/{optimization_run_id}/costs` for the cost breakdown.

### What are the rate limits for the Not Diamond API?

The published spec does not declare numeric rate limits. Treat `/v2/modelRouter/modelSelect` as the highest-volume endpoint and throttle accordingly. Watch for HTTP 429 responses and back off; cache `/v2/models` results since the supported model list changes infrequently.

### How do I route a prompt to the best model through Jentic?

Search Jentic for 'select the best LLM for this prompt', load the POST `/v2/modelRouter/modelSelect` schema, and execute it with your prompt and a user preference identifier. With `pip install jentic` the call is a single execute() invocation that returns the recommended model name.

### Is the Not Diamond API free?

Pricing is set by Not Diamond's account tiers and is not encoded in the spec. Most teams use a paid plan once they exceed evaluation usage; check the Not Diamond dashboard for the current limits attached to your bearer token.

### Can I limit what my agent is allowed to do with the Not Diamond API?

Yes. Because you self-host Jentic One, your own rules decide which Not Diamond operations and credentials the agent may use, and it can only call the operations you list. For a routing-only workload you can allow just POST `/v2/modelRouter/modelSelect` and the prompt optimisation calls (`/v2/prompt/optimize` with its status and results endpoints), since these take their targets in the request body. Leave out heavier operations such as POST `/v2/pzn/trainCustomRouter` and the user preference management calls unless you explicitly add them.