canonical: https://jentic.com/apis/notdiamond.ai/not-diamond

# Not Diamond API

Jentic maintains a curated, agent-optimised OpenAPI specification for Not Diamond API, validated against the live service and kept agent-ready alongside the OpenAPI document Not Diamond serves from its own API host. Not Diamond is a model-routing and prompt-optimisation platform that picks the best LLM for each query based on quality, cost, and latency targets, then improves prompts over time. The API exposes 8 endpoints covering model selection, user routing preferences, prompt-optimisation runs, and cost tracking. It supports the operational workflow of running an LLM application with multiple candidate providers behind a single intelligent routing layer.

## For AI agents

Route LLM queries to the best model from a candidate set, manage routing preferences, and run prompt-optimisation jobs.

## Scope

Does not run model inference itself, host models, or store conversation history - use for model routing and prompt optimisation only.

## Capabilities

- Pick the best LLM for a given prompt across providers using the model selector
- Define user-level routing preferences for cost, latency, and quality trade-offs
- Submit prompt-optimisation runs and retrieve the improved prompt versions
- Track the cost of an optimisation run before applying the result
- Update or delete user preferences as application requirements change
- Poll optimisation status and pull final results once a run completes

## Use cases

### Multi-Model LLM Routing

An LLM application that supports multiple model providers calls Not Diamond's modelSelect endpoint with the prompt and a candidate model list, then routes the actual completion call to the chosen model. This avoids hard-coding a single provider and lets cost or quality preferences shift the choice per query without redeploying the application.

Example prompt: Call modelSelect with a customer support prompt and the candidate set [gpt-4, claude-3-5-sonnet, gemini-1.5-pro], then forward the prompt to the chosen model

### Automated Prompt Optimisation

Engineering teams submit a baseline prompt and a small evaluation set to Not Diamond, which iterates on phrasing and structure to improve target metrics. Optimisation runs are asynchronous: submit via `/v2/prompt/optimize`, poll status, then pull the improved prompt and apply it. Cost is queryable before the team commits to a run.

Example prompt: Submit an optimisation run for the current support-classification prompt, poll until complete, and return the improved prompt with cost and quality deltas

### Per-User Routing Preferences

A SaaS product offering AI features to enterprise customers stores routing preferences per user - for example, a regulated tenant prefers self-hosted models while a free-tier user prefers the cheapest option. The user preferences endpoints persist these choices server-side, and modelSelect honours them automatically without per-request preference passing.

Example prompt: Create a user preference favouring open-source models for tenant id 'acme', then run modelSelect for that tenant on a content generation prompt

### AI Agent Cost Optimisation

An AI agent operating under a budget delegates model choice to Not Diamond rather than hard-coding gpt-4 for every step. Through Jentic, the agent searches for the model selector operation, loads the schema, and routes each step's prompt to the cheapest model that meets the quality bar - measurable savings on multi-step workflows.

Example prompt: For each step in an agent workflow, call Not Diamond modelSelect with the step's prompt and select the lowest-cost model meeting the quality threshold

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v2/modelRouter/modelSelect` | Select the best model for a prompt |
| POST | `/v2/preferences/userPreferenceCreate` | Create a routing preference |
| PUT | `/v2/preferences/userPreferenceUpdate` | Update a routing preference |
| POST | `/v2/prompt/optimize` | Submit a prompt optimisation run |
| GET | `/v2/prompt/optimizeStatus/{optimization_run_id}` | Check optimisation status |
| GET | `/v2/prompt/optimizeResults/{optimization_run_id}` | Retrieve optimisation results |
| GET | `/v2/prompt/optimize/{optimization_run_id}/costs` | Get optimisation run cost |

## Key resources

- **Routing** — Model selection across candidate LLM providers via modelSelect
- **Preferences** — Create, update, and delete user-level routing preferences
- **Prompt Optimization** — Submit optimisation runs, poll status, and retrieve improved prompts and costs

## Why Jentic

- **Setup:** Wiring Not Diamond by hand means setting up its bearer token against api.notdiamond.ai and threading it through model routing and prompt optimisation calls yourself. Through Jentic you install once, import the Not Diamond API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Not Diamond takes the routing and preference details in the request body, with only optimisation run reads keyed by path, so scope the agent to the operations it needs, such as selecting a model and reading optimisation results. You choose that set, so preference writes or starting a new optimisation are not included unless you add them.
- **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 'pick the best model for this prompt' or 'check an optimisation run', and Jentic returns the matching Not Diamond operation with its input schema so the agent calls `/v2/modelRouter/modelSelect` without browsing the reference docs.

## Related APIs

- **Portkey AI** — Portkey is an AI gateway with routing, caching, and observability across LLM providers.
- **OpenAI API** — OpenAI provides the underlying GPT models that Not Diamond can route to.
- **Anthropic Messages API** — Anthropic Claude is one of the candidate models Not Diamond can route to.
- **Cohere API** — Cohere provides another candidate LLM that Not Diamond can route prompts to.

## FAQ

### Which OpenAPI specification does this Not Diamond API page describe?

A curated, agent-optimised Jentic specification covering 8 Not Diamond operations. Not Diamond also serves its own OpenAPI 3.1.0 document from its API host at https://api.notdiamond.ai/openapi.json, which covers 10 paths: the same 8 plus a model-list endpoint and a custom-router training endpoint. The Jentic variant is the curated subset, validated against the live API and shaped for agent discovery, so it is labelled a Jentic specification rather than a silent copy of the vendor document. Get started with Jentic One, the self-hosted execution layer.

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

The API uses HTTP bearer authentication. Through Jentic, the bearer token is stored in the vault and injected at execution time, so the agent never sees the raw token in its context.

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

Yes. POST `/v2/prompt/optimize` submits an asynchronous run, GET `/v2/prompt/optimizeStatus/{optimization_run_id}` polls progress, and `/v2/prompt/optimizeResults/{optimization_run_id}` returns the improved prompt once the run finishes.

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

The OpenAPI spec does not declare explicit rate limits. Not Diamond applies plan-based limits in production; consult the Not Diamond dashboard or response headers for current limits.

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

Search Jentic for 'route a prompt to the best LLM'. Jentic returns the POST `/v2/modelRouter/modelSelect` operation with its input schema, including the prompt and candidate model list, so the agent can call it directly.

### Can I see the cost of an optimisation run before applying it?

Yes. GET `/v2/prompt/optimize/{optimization_run_id}/costs` returns the cost for a completed optimisation run, so the team can decide whether to adopt the improved prompt before rolling it out.

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

Yes. Because you run Jentic One yourself, your own rules decide which Not Diamond operations and credentials the agent can use, so you grant only the ones it needs, such as selecting a model with `/v2/modelRouter/modelSelect` and reading a run's results and cost via the optimize status, results, and costs endpoints. Preference writes like userPreferenceCreate and userPreferenceUpdate, or starting a new run with `/v2/prompt/optimize`, stay out of the agent's reach unless you add them. Since routing and preference details travel in the request body while run reads are keyed by path, you scope access at the operation level to keep the agent read-only where you want it.