# Not Diamond Documentation

> Not Diamond is an intelligent multi-model AI infrastructure platform that helps you adapt prompts across models and predictively determine which LLM is best-suited to respond to each input in your application, accelerating development, improving accuracy, and lowering costs.

## Guides
- [What is Not Diamond?](https://docs.notdiamond.ai/docs/what-is-not-diamond.md)
- [API keys](https://docs.notdiamond.ai/docs/api-keys.md)
- [What is Model Routing?](https://docs.notdiamond.ai/docs/what-is-model-routing.md)
- [Pre-trained router: Code](https://docs.notdiamond.ai/docs/pre-trained-router-code.md)
- [Pre-trained router: Chat](https://docs.notdiamond.ai/docs/quickstart-routing.md)
- [Training a custom router](https://docs.notdiamond.ai/docs/router-training-quickstart.md)
- [Supported models (routing)](https://docs.notdiamond.ai/docs/llm-models.md)
- [Routing between custom models](https://docs.notdiamond.ai/docs/routing-between-custom-models.md)
- [Key concepts](https://docs.notdiamond.ai/docs/key-concepts.md)
- [What is Prompt Optimization?](https://docs.notdiamond.ai/docs/what-is-prompt-optimization.md)
- [Quick start](https://docs.notdiamond.ai/docs/quickstart-prompt-optimization.md)
- [Key concepts](https://docs.notdiamond.ai/docs/requirements-and-concepts.md)
- [Classification](https://docs.notdiamond.ai/docs/classification.md)
- [Supported models (prompt optimization)](https://docs.notdiamond.ai/docs/prompt-optimization-models.md)
- [Evaluation metrics](https://docs.notdiamond.ai/docs/evaluation-metrics.md)
- [How Prompt Optimization works](https://docs.notdiamond.ai/docs/how-prompt-optimization-works.md)
- [Rate limits](https://docs.notdiamond.ai/docs/rate-limits.md)
- [Support](https://docs.notdiamond.ai/docs/support.md)
- [Security](https://docs.notdiamond.ai/docs/privacy-security-and-local-deployments.md)

## API Reference
- [/optimizeStatus](https://docs.notdiamond.ai/reference/get_optimize_status_v2_prompt_optimizestatus__optimization_run_id__get.md): Check the status of a prompt optimization run.  Use this endpoint to poll the status of your optimization request. Processing is asynchronous, so you'll need to check periodically until the status indicates completion.  **Status Values:** - `created`: Initial state, not yet processing - `queued`: Waiting for processing capacity (check queue_position) - `processing`: Currently optimizing prompts - `completed`: All target models have been processed successfully - `failed`: One or more target models failed to process  **Polling Recommendations:** - Poll every 30-60 seconds during processing - Check queue_position if status is 'queued' to estimate wait time - Stop polling once status is 'completed' or 'failed' - Use GET /v2/prompt/optimizeResults to retrieve results after completion  **Queue Position:** - Only present when status is 'queued' - Lower numbers mean earlier processing (position 1 is next) - Typical wait time: 1-5 minutes per position  **Note:** This endpoint only returns status information. To get the actual optimized prompts and evaluation results, use GET /v2/prompt/optimizeResults once status is 'completed'.
- [/optimizeResults](https://docs.notdiamond.ai/reference/get_optimize_results_v2_prompt_optimizeresults__optimization_run_id__get.md): Retrieve the complete results of a prompt optimization run, including optimized prompts for all target models.  This endpoint returns the optimized prompts and evaluation metrics for each target model in your optimization request. Call this endpoint after the optimization status is 'completed' to get your optimized prompts.  **Response Structure:** - **origin_model**: Baseline performance of your original prompt on the origin model   - Includes: system_prompt, user_message_template, score, evaluation metrics, cost - **target_models**: Array of results for each target model   - Includes: optimized system_prompt, user_message_template, template_fields   - pre_optimization_score: Performance before optimization   - post_optimization_score: Performance after optimization   - Evaluation metrics and cost information  **Using Optimized Prompts:** 1. Extract the `system_prompt` and `user_message_template` from each target model result 2. Use `user_message_template_fields` to know which fields to substitute 3. Apply the optimized prompts when calling the respective target models 4. Compare pre/post optimization scores to see improvement  **Status Handling:** - If optimization is still processing, target model results will have `result_status: "processing"` - Only completed target models will have system_prompt and template values - Failed target models will have `result_status: "failed"` with null values  **Cost Information:** - Each model result includes cost in USD for the optimization process - Costs vary based on model pricing and number of evaluation examples - Typical range: $0.10 - $2.00 per target model  **Best Practices:** 1. Wait for status 'completed' before calling this endpoint 2. Check result_status for each target model 3. Validate that post_optimization_score > pre_optimization_score 4. Save optimized prompts for production use 5. A/B test optimized prompts against originals in production
- [/optimize](https://docs.notdiamond.ai/reference/optimize_prompt_v2_prompt_optimize_post.md): Optimize your prompt from one LLM to work optimally across different target LLMs.  This endpoint automatically optimizes your prompt (system prompt + user message template) to improve accuracy on your use case across various models. Each model has unique characteristics, and what works well for GPT-5 might not work as well for Claude or Gemini.  **How Prompt Optimization Works:** 1. You provide your current prompt and optionally your current origin model 2. You specify the target models you want to optimize your prompt to 3. You provide evaluation examples (golden records) with expected answers 4. The system runs optimization to find the best prompt for each target model 5. You receive optimized prompts that perform well on your target models  **Evaluation Metrics:** Choose either a standard metric or provide custom evaluation: - **Standard metrics**: LLMaaJ:Sem_Sim_1 (semantic similarity), JSON_Match - **Custom evaluation**: Provide evaluation_config with your own LLM judge, prompt, and cutoff  **Dataset Requirements:** - Minimum 25 examples in train_goldens (more examples = better optimization) - **Prototype mode**: Set `prototype_mode: true` to use as few as 3 examples for prototyping   - Recommended when you don't have enough data yet to build a proof-of-concept   - Note: Performance may be degraded compared to standard mode (25+ examples)   - Trade-off: Faster iteration with less data vs. potentially less generalizability - Each example must have fields matching your template placeholders - Supervised evaluation requires 'answer' field in each golden record - Unsupervised evaluation can work without answers  **Training Time:** - Processing is asynchronous and typically takes 10-30 minutes - Time depends on: number of target models, dataset size, model availability - Use the returned optimization_run_id to check status and retrieve results  **Example Workflow:** ``` 1. POST /v2/prompt/optimize - Submit optimization request 2. GET /v2/prompt/optimizeStatus/{id} - Poll status until completed 3. GET /v2/prompt/optimizeResults/{id} - Retrieve optimized prompts 4. Use optimized prompts in production with target models ```
- [/optimize/{optimization_run_id}/costs ](https://docs.notdiamond.ai/reference/get_optimization_run_costs_v2_prompt_optimize__optimization_run_id__costs_get.md): Get LLM usage costs for a specific prompt optimization run.  This endpoint returns the total cost and detailed usage records for all LLM requests made during a prompt optimization run. Use this to track costs associated with optimizing prompts for different target models.  **Cost Breakdown:** - Total cost across all models used in the optimization - Individual usage records with provider, model, tokens, and costs - Timestamps for each LLM request  **Access Control:** - Only accessible by the user who created the optimization run - Requires prompt optimization access
- [/modelSelect](https://docs.notdiamond.ai/reference/token_model_select_v2_modelrouter_modelselect_post.md): Select the optimal LLM to handle your query based on Not Diamond's routing algorithm.  This endpoint analyzes your messages and returns the best-suited model from your specified models. The router considers factors like query complexity, model capabilities, cost, and latency based on your preferences.  **Key Features:** - Intelligent routing across multiple LLM providers - Support for custom routers trained on your evaluation data - Optional cost/latency optimization - Function calling support for compatible models  **Usage:** 1. Pass your messages in OpenAI format (array of objects with 'role' and 'content') 2. Specify which LLM providers you want to route between 3. Optionally provide a preference_id to use a custom router that you've trained 4. Receive a recommended model and session_id 5. Use the session_id to submit feedback and improve routing  **Related Endpoints:** - `POST /v2/preferences/userPreferenceCreate` - Create a preference ID for personalized routing - `POST /v2/pzn/trainCustomRouter` - Train a custom router on your evaluation data
- [/trainCustomRouter](https://docs.notdiamond.ai/reference/train_custom_router_v2_pzn_traincustomrouter_post.md): Train a custom router on your evaluation data to optimize routing for your specific use case.  This endpoint allows you to train a domain-specific router that learns which models perform best for different types of queries in your application. The router analyzes your evaluation dataset, clusters similar queries, and learns model performance patterns.  **Training Process:** 1. Upload a CSV file with your evaluation data 2. Specify which models to route between 3. Define the evaluation metric (score column) 4. The system trains asynchronously and returns a preference_id 5. Use the preference_id in model_select() calls once training completes  **Dataset Requirements:** - Format: CSV file - Minimum samples: 25 (more is better for accuracy) - Required columns:   - Prompt column (specified in prompt_column parameter)   - For each model: `{provider}/{model}/score` and `{provider}/{model}/response`  **Example CSV structure:** ``` prompt,openai/gpt-4o/score,openai/gpt-4o/response,anthropic/claude-sonnet-4-5-20250929/score,anthropic/claude-sonnet-4-5-20250929/response "Explain quantum computing",0.95,"Quantum computing uses...",0.87,"Quantum computers leverage..." "Write a Python function",0.82,"def my_function()...",0.91,"Here's a Python function..." ```  **Model Selection:** - Specify standard models: `{"provider": "openai", "model": "gpt-4o"}` - Or custom models with pricing: `{"provider": "custom", "model": "my-model", "is_custom": true, "input_price": 10.0, "output_price": 30.0, "context_length": 8192, "latency": 1.5}`  **Training Time:** - Training is asynchronous and typically takes 5-15 minutes - Larger datasets or more models take longer - You'll receive a preference_id immediately - Check training status by attempting to use the preference_id in model_select()  **Best Practices:** 1. Use diverse, representative examples from your production workload 2. Include at least 50-100 samples for best results 3. Ensure consistent evaluation metrics across all models 4. Use the same models you plan to route between in production  **Related Documentation:** See https://docs.notdiamond.ai/docs/adapting-prompts-to-new-models for detailed guide.
- [/models](https://docs.notdiamond.ai/reference/list_models_v2_models_get.md): List all supported text generation models with optional filtering.  including pricing, context length, latency, and OpenRouter availability.  **Note:** Image generation models are excluded from this endpoint.  **Examples:** - Get all models: `/v2/models` - OpenRouter only: `/v2/models?openrouter_only=true` - Specific provider: `/v2/models?provider=openai` - Multiple providers: `/v2/models?provider=openai&provider=anthropic`  **Query Parameters:** - **provider**: Filter by provider name(s). Can specify multiple times for multiple providers   (e.g., `?provider=openai&provider=anthropic`) - **openrouter_only**: Return only models that have OpenRouter support (default: false)  **Returns:** - **models**: List of active text generation model objects with metadata - **total**: Total number of active models returned - **deprecated_models**: List of deprecated text generation model objects with metadata   (respects the same filters as active models)  **Caching:** - Response is cacheable for 1 hour (model list rarely changes)