{ "openapi": "3.0.3", "info": { "title": "Valyu API", "version": "2.3.0", "description": "The search API built for AI agents. One API that gives your AI unified access to web search, academic papers, financial data, SEC filings, clinical trials, patents, genomics, and 40+ proprietary data sources.\n\n## Products\n\n| Product | Endpoint | Description |\n| --- | --- | --- |\n| **Search** | `POST /v1/search` | Multi-source search across web and proprietary datasets |\n| **Contents** | `POST /v1/contents` | Extract clean, structured content from URLs |\n| **Answer** | `POST /v1/answer` | AI-powered answers with real-time search |\n| **DeepResearch** | `POST /v1/deepresearch/tasks` | Async research agents for comprehensive analysis |\n| **Workflows** (Beta) | `GET /v1/workflows` | Templated, versioned DeepResearch for repeatable knowledge work |\n| **Datasources** | `GET /v1/datasources` | Discover available data sources and their schemas |\n\n## Authentication\n\nAll endpoints require an API key passed via the `X-API-Key` header (the lowercase `x-api-key` form is also accepted). Get your key at [platform.valyu.ai](https://platform.valyu.ai).\n\n```\nX-API-Key: your_api_key_here\n```\n\n## Pricing\n\nValyu uses transparent, pay-per-use pricing. Credits are shared across every API.\n- **Search**: CPM-based (cost per mille tokens retrieved)\n- **Contents**: $0.001 per URL extracted, +$0.001 with AI features\n- **Answer**: $0.10 per request + variable search and AI costs\n- **DeepResearch**: Fixed per-task pricing by mode ($0.10 - $15.00)\n\nAll plans include web search and open academic sources. A subscription unlocks specialised and proprietary sources (SEC filings, patents, drug discovery, genomics, and more) at a lower cost per credit. See [docs.valyu.ai](https://docs.valyu.ai) for full pricing details.\n\n## SDKs\n\n- [Python SDK](https://pypi.org/project/valyu/) - `pip install valyu`\n- [TypeScript SDK](https://www.npmjs.com/package/valyu) - `npm install valyu`\n", "contact": { "name": "Valyu Support", "url": "https://valyu.ai", "email": "support@valyu.ai" }, "x-logo": { "url": "https://valyu.ai/logo.png", "altText": "Valyu" } }, "servers": [ { "url": "https://api.valyu.ai", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Search", "description": "Search across web, academic, financial, and proprietary data sources. Returns results ready for RAG pipelines, AI agents, and applications.", "externalDocs": { "description": "Search API Guide", "url": "https://docs.valyu.ai/search/quickstart" } }, { "name": "Contents", "description": "Extract clean, structured content from web pages at scale. Supports batch processing, AI-powered summaries, structured extraction via JSON schemas, and async jobs for large URL sets.", "externalDocs": { "description": "Contents API Guide", "url": "https://docs.valyu.ai/guides/content-extraction" } }, { "name": "Answer", "description": "Get AI-powered answers grounded in real-time search results. The Answer API searches across web, academic, and financial sources, then uses AI to generate a readable response via Server-Sent Events streaming.", "externalDocs": { "description": "Answer API Guide", "url": "https://docs.valyu.ai/guides/answer-api" } }, { "name": "DeepResearch", "description": "Async research agents that perform comprehensive, multi-step research. DeepResearch searches multiple sources, analyzes content, and generates detailed reports with citations. Tasks run in the background and can take minutes to complete.", "externalDocs": { "description": "DeepResearch Guide", "url": "https://docs.valyu.ai/guides/deepresearch" } }, { "name": "Batches", "description": "Run multiple DeepResearch tasks in parallel with shared configuration, unified monitoring, and aggregated cost tracking.", "externalDocs": { "description": "Batch API Guide", "url": "https://docs.valyu.ai/guides/deepresearch-batch-quickstart" } }, { "name": "Workflows", "description": "**Beta.** Templated, versioned DeepResearch for repeatable knowledge work - earnings previews, diligence reads, market sizings. A workflow bundles a prompt template with typed variables, a research strategy, report format, deliverables, tools, and a recommended mode. Workflows are immutably versioned; runs can pin a version. Two scopes exist: your organization's private workflows and curated Valyu workflows available to everyone. Run a workflow by passing `workflow_id` + `workflow_params` to `POST /v1/deepresearch/tasks` - same auth, billing, and task lifecycle as freeform DeepResearch.", "externalDocs": { "description": "Workflows Guide (Beta)", "url": "https://docs.valyu.ai/guides/workflows" } }, { "name": "Datasources", "description": "Discover available data sources and their schemas. A tool manifest for AI agents - instead of hardcoding knowledge of available datasets, agents can query this API to discover sources, filter by category, and use `example_queries` for few-shot prompting.", "externalDocs": { "description": "Datasources Guide", "url": "https://docs.valyu.ai/guides/datasources" } } ], "paths": { "/v1/search": { "post": { "operationId": "search", "summary": "Search across web and proprietary data sources", "description": "Search the web, academic journals, financial databases, and 40+ proprietary data sources. Returns ranked results with extracted content, ready for RAG pipelines and AI agents.\n\nResults are ranked by relevance using semantic reranking (unless `fast_mode` is enabled). You only pay for results returned - pricing is CPM-based (cost per mille tokens).\n\n**Integrating search into an agent?** Consider [DeepResearch](https://docs.valyu.ai/guides/deepresearch) - a cost-effective autonomous agent built on top of this search engine, purpose-built for knowledge work.", "tags": [ "Search" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "examples": { "basic": { "summary": "Basic web search", "value": { "query": "latest developments in quantum computing", "max_num_results": 5 } }, "academic": { "summary": "Academic paper search", "value": { "query": "CRISPR gene editing clinical trials 2024", "search_type": "proprietary", "max_num_results": 10, "included_sources": [ "medical" ] } }, "filtered": { "summary": "Source-filtered search with date range", "value": { "query": "climate change impact on agriculture", "included_sources": [ "valyu/valyu-arxiv", "valyu/valyu-pubmed", "valyu/valyu-biorxiv" ], "start_date": "2024-01-01", "end_date": "2024-12-31", "max_num_results": 10 } }, "pubmed_abstracts": { "summary": "PubMed abstract search", "value": { "query": "clonal hematopoiesis cardiovascular disease", "included_sources": [ "valyu/valyu-pubmed" ], "include_abstracts": true, "max_num_results": 10 } }, "fast": { "summary": "Low-latency web search", "value": { "query": "Tesla stock price today", "fast_mode": true, "max_num_results": 5 } } } } } }, "responses": { "200": { "description": "Search completed successfully with results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { "success": { "summary": "Successful search with web and proprietary results", "value": { "success": true, "error": null, "tx_id": "tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "query": "latest developments in quantum computing", "results": [ { "id": "https://arxiv.org/abs/2024.12345", "title": "Quantum Computing Breakthrough: New Error Correction Method", "url": "https://arxiv.org/abs/2024.12345", "content": "Researchers at MIT have developed a revolutionary quantum error correction method that reduces qubit errors by 99.9%...", "description": "Major breakthrough in quantum error correction methodology", "source": "web", "price": 0.0015, "length": 15420, "image_url": null, "relevance_score": 0.95, "data_type": "unstructured", "source_type": "website", "publication_date": "2024-06-15" }, { "id": "valyu/valyu-arxiv/2401.12345", "title": "Advances in Topological Quantum Computing", "url": "https://arxiv.org/abs/2401.12345", "content": "We present a novel approach to topological quantum error correction...", "description": "Topological approaches to fault-tolerant quantum computation", "source": "valyu/valyu-arxiv", "price": 0.0005, "length": 28000, "image_url": null, "relevance_score": 0.89, "data_type": "unstructured", "source_type": "paper", "publication_date": "2024-01-15", "doi": "10.48550/arXiv.2401.12345", "authors": [ "J. Smith", "A. Chen", "M. Kumar" ] } ], "results_by_source": { "web": 3, "proprietary": 2 }, "total_deduction_dollars": 0.0075, "total_characters": 45230 } }, "fast_mode": { "summary": "Fast mode search (web only, no reranking)", "value": { "success": true, "error": null, "tx_id": "tx_fast12345-6789-abcd-ef01-234567890abc", "query": "Tesla stock price today", "results": [ { "id": "https://fred.stlouisfed.org/series/TSLA", "title": "Tesla, Inc. (TSLA) Stock Price, News, Quote & History", "url": "https://fred.stlouisfed.org/series/TSLA", "content": "Tesla Inc (TSLA) stock price...", "source": "web", "price": 0.0015, "length": 5200, "data_type": "unstructured", "source_type": "website" } ], "results_by_source": { "web": 5 }, "total_deduction_dollars": 0.0075, "total_characters": 26000 } } } } } }, "206": { "description": "Partial success - some sources failed or no results found, but the request was processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/contents": { "post": { "operationId": "extractContents", "summary": "Extract clean, structured content from URLs", "description": "Turn any web page into clean, structured data. Extract content from up to 10 URLs per request with optional AI-powered summaries, structured extraction via JSON schemas, and screenshot capture.\n\n- **Synchronous (default)**: Returns extracted content directly\n- **Async**: Set `async: true` to process in the background and poll a `job_id`\n- **Pay-per-success**: Only charged for URLs that are successfully processed ($0.001/URL, +$0.001 with AI features). Failed URLs are free\n- **Partial / total failure**: A `206` is returned when some URLs fail; a `422` is returned when every URL fails", "tags": [ "Contents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsRequest" }, "examples": { "basic": { "summary": "Basic content extraction", "value": { "urls": [ "https://en.wikipedia.org/wiki/Quantum_computing" ] } }, "With Summary": { "summary": "Extraction with AI summary", "value": { "urls": [ "https://arxiv.org/abs/2401.00001" ], "summary": "Summarize the key findings and methodology", "response_length": "medium" } }, "structured": { "summary": "Structured data extraction with JSON schema", "value": { "urls": [ "https://example.com/product-page" ], "summary": { "type": "object", "properties": { "product_name": { "type": "string" }, "price": { "type": "number" }, "features": { "type": "array", "items": { "type": "string" } } } } } }, "Async Batch": { "summary": "Async batch processing with webhook", "value": { "urls": [ "https://example.com/page1", "https://example.com/page2" ], "async": true, "webhook_url": "https://your-app.com/webhooks/valyu" } } } } } }, "responses": { "200": { "description": "All URLs processed successfully (synchronous).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsResponse" }, "examples": { "basic": { "summary": "Basic extraction", "value": { "success": true, "error": null, "tx_id": "tx_c1d2e3f4-a5b6-7890-cdef-123456789abc", "urls_requested": 2, "urls_processed": 2, "urls_failed": 0, "results": [ { "url": "https://en.wikipedia.org/wiki/Quantum_computing", "status": "success", "title": "Quantum computing - Wikipedia", "content": "# Quantum computing\\n\\nQuantum computing is a type of computation that harnesses quantum mechanical phenomena...", "description": "Quantum computing is a type of computation that harnesses quantum mechanical phenomena.", "source": "web", "price": 0.001, "length": 24500, "data_type": "unstructured", "source_type": "website", "image_url": { "0": "https://upload.wikimedia.org/quantum.png" }, "screenshot_url": null } ], "total_cost_dollars": 0.002, "total_characters": 49000 } }, "structured": { "summary": "Structured data extraction", "value": { "success": true, "error": null, "tx_id": "tx_struct-1234-5678-abcd-ef0123456789", "urls_requested": 1, "urls_processed": 1, "urls_failed": 0, "results": [ { "url": "https://example.com/product-page", "status": "success", "title": "Product Page", "content": { "product_name": "Widget Pro", "price": 29.99, "features": [ "Feature A", "Feature B" ] }, "source": "web", "price": 0.002, "length": 150, "data_type": "structured", "summary_success": true } ], "total_cost_dollars": 0.002, "total_characters": 150 } } } } } }, "202": { "description": "Async job created. Poll the `poll_url` for results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsAsyncResponse" }, "examples": { "example": { "summary": "Async job created", "value": { "success": true, "job_id": "cj_a1b2c3d4e5f6g7h8", "status": "pending", "urls_total": 25, "poll_url": "/contents/jobs/cj_a1b2c3d4e5f6g7h8", "tx_id": "tx_async-1234-5678-abcd-ef0123456789", "webhook_secret": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678" } } } } } }, "206": { "description": "Partial success - some URLs failed processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "All URLs failed to process. No charge is applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/contents/jobs/{job_id}": { "get": { "operationId": "getContentsJob", "summary": "Poll async content extraction job status", "description": "Check the status and retrieve results of an async content extraction job.", "tags": [ "Contents" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The job ID returned by the async contents request.", "example": "cj_a1b2c3d4e5f6g7h8" } ], "responses": { "200": { "description": "Job status and results (when complete).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsJobResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/answer": { "post": { "operationId": "answer", "summary": "Get AI-powered answers with real-time search", "description": "Searches across web, academic, and financial sources, then uses AI to generate a readable, cited response. Returns results as a **Server-Sent Events (SSE)** stream.\n\nThe AI agent performs multi-round search with up to 2 tool call rounds (3 in `fast_mode`), can decompose queries into sub-queries, and synthesizes findings into a coherent answer.\n\n## SSE Event Types\n\nEvents are sent as `data: {json}\\n\\n` with the following types:\n\n| Event | Description |\n| --- | --- |\n| `search_results` | Search sources found (may occur multiple times) |\n| `content` | Partial answer text chunk (OpenAI-compatible delta format) |\n| `metadata` | Final metadata with costs, token usage, and all search results |\n| `[DONE]` | Stream complete |\n\n## Cost Structure\n\nEach request costs a base of ~$0.10 plus variable search and AI token costs. The `cost` object in the metadata event provides a full breakdown.", "tags": [ "Answer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerRequest" }, "examples": { "basic": { "summary": "Basic question", "value": { "query": "What are the latest FDA-approved treatments for type 2 diabetes?" } }, "structured": { "summary": "Structured output with JSON schema", "value": { "query": "Compare the top 5 electric vehicles by range and price in 2024", "structured_output": { "type": "object", "properties": { "vehicles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "range_miles": { "type": "number" }, "base_price": { "type": "number" } } } } } } } }, "filtered": { "summary": "Source-filtered with custom instructions", "value": { "query": "SEC enforcement actions against crypto exchanges", "search_type": "proprietary", "included_sources": [ "finance" ], "system_instructions": "You are a financial regulatory analyst. Focus on enforcement actions and penalties.", "start_date": "2024-01-01" } } } } } }, "responses": { "200": { "description": "SSE stream of search results, answer chunks, and metadata.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream. Each event has format: `data: {json}\\n\\n`\n\n**search_results event:**\n```json\n{\"search_results\": [{\"title\": \"...\", \"url\": \"...\", \"content\": \"...\", ...}]}\n```\n\n**content event (OpenAI-compatible):**\n```json\n{\"choices\": [{\"delta\": {\"role\": \"assistant\", \"content\": \"text chunk\"}, \"index\": 0}]}\n```\n\n**metadata event:**\n```json\n{\"success\": true, \"tx_id\": \"ai_tx_...\", \"data_type\": \"unstructured\", \"search_results\": [...], \"search_metadata\": {\"tx_ids\": [...], \"number_of_results\": 10, \"total_characters\": 50000}, \"ai_usage\": {\"input_tokens\": 15000, \"output_tokens\": 2000}, \"cost\": {\"total_deduction_dollars\": 0.15, \"search_deduction_dollars\": 0.03, \"ai_deduction_dollars\": 0.10, \"contents_deduction_dollars\": 0.02}}\n```\n\n**done signal:**\n```\ndata: [DONE]\n```" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/tasks": { "post": { "operationId": "createDeepResearch", "summary": "Create a DeepResearch task", "description": "Start an async research task that performs comprehensive, multi-step research. The research agent searches multiple sources, analyzes content, executes code, and generates a detailed report with citations.\n\nTasks run in the background and typically take 1-10 minutes depending on the `mode`. Poll the status endpoint or use webhooks to get results.", "tags": [ "DeepResearch" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchCreateRequest" }, "examples": { "basic": { "summary": "Basic research task", "value": { "query": "Comprehensive analysis of CRISPR gene therapy clinical trials in 2024", "mode": "standard" } }, "advanced": { "summary": "Advanced research with PDF output and file attachments", "value": { "query": "Compare efficacy data across Phase 3 CRISPR trials", "mode": "heavy", "strategy": "Focus on safety profiles, patient outcomes, and regulatory pathways", "output_formats": [ "markdown", "pdf" ], "search": { "search_type": "proprietary", "included_sources": [ "medical" ], "start_date": "2023-01-01" }, "urls": [ "https://clinicaltrials.gov/study/NCT12345678" ], "webhook_url": "https://your-app.com/webhooks/deepresearch" } }, "structured": { "summary": "Structured JSON output", "value": { "query": "Top 10 AI companies by funding raised in 2024", "mode": "fast", "output_formats": [ { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "funding_millions": { "type": "number" }, "focus_area": { "type": "string" } } } } } } ] } } } } } }, "responses": { "202": { "description": "Research task created and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchCreateResponse" }, "examples": { "running": { "summary": "Task started immediately", "value": { "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b", "status": "running", "mode": "standard", "created_at": "2024-06-15T10:30:00.000Z", "metadata": { "project": "drug-discovery" }, "public": false } }, "queued": { "summary": "Task queued (capacity limit)", "value": { "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "queued", "mode": "heavy", "created_at": "2024-06-15T10:30:00.000Z", "public": false, "message": "Task queued. Current position: 3", "webhook_secret": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/tasks/{id}/status": { "get": { "operationId": "getDeepResearchStatus", "summary": "Get DeepResearch task status and results", "description": "Retrieve the current status, progress, and results of a DeepResearch task. Poll this endpoint to track research progress and retrieve the final output.", "tags": [ "DeepResearch" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "DeepResearch task ID.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ], "responses": { "200": { "description": "Task status and results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchStatusResponse" }, "examples": { "running": { "summary": "Task in progress", "value": { "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "running", "query": "Comprehensive analysis of CRISPR gene therapy clinical trials", "mode": "standard", "output_formats": [ "markdown", "pdf" ], "created_at": "2024-06-15T10:30:00.000Z", "public": false, "progress": { "current_step": 5, "total_steps": 15 } } }, "completed": { "summary": "Task completed with output", "value": { "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "completed", "query": "Comprehensive analysis of CRISPR gene therapy clinical trials", "mode": "standard", "output_formats": [ "markdown", "pdf" ], "created_at": "2024-06-15T10:30:00.000Z", "completed_at": "2024-06-15T10:42:00.000Z", "public": false, "output_type": "markdown", "output": "# CRISPR Gene Therapy Clinical Trials: A Comprehensive Analysis\\n\\n## Executive Summary\\n\\nThis report analyzes...", "sources": [ { "title": "CRISPR Gene Therapy: A Comprehensive Review", "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/", "snippet": "CRISPR-based gene therapy has shown remarkable progress...", "source": "pubmed", "doi": "10.1038/s41586-024-07107-7", "word_count": 8500, "fragment": "#:~:text=CRISPR-based%20gene%20therapy%20has%20shown%20remarkable%20progress" }, { "title": "Phase 3 Results: Exa-cel for Sickle Cell Disease", "url": "https://clinicaltrials.gov/study/NCT04208529", "snippet": "The pivotal trial demonstrated...", "source": "web", "word_count": 3200 } ], "cost": 0.5, "pdf_url": "https://storage.valyu.ai/pdfs/a1b2c3d4.pdf", "images": [ { "image_id": "img_chart001", "image_type": "chart", "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "CRISPR Trial Phases Distribution", "image_url": "https://storage.valyu.ai/images/img_chart001.png", "chart_type": "bar", "created_at": "2024-06-15T10:38:00.000Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/list": { "get": { "operationId": "listDeepResearchTasks", "summary": "List DeepResearch tasks", "description": "Retrieve a list of all DeepResearch tasks for the authenticated API key.", "tags": [ "DeepResearch" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of tasks to return." } ], "responses": { "200": { "description": "List of DeepResearch tasks.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeepResearchListItem" } }, "examples": { "success": { "summary": "List of research tasks", "value": [ { "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b", "query": "CRISPR gene therapy clinical trials", "status": "completed", "created_at": "2024-06-15T10:30:00.000Z", "public": false }, { "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "query": "Quantum computing market analysis", "status": "running", "created_at": "2024-06-15T11:00:00.000Z", "public": false } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/tasks/{id}/update": { "post": { "operationId": "updateDeepResearch", "summary": "Add a follow-up instruction to a running task", "description": "Send a follow-up instruction to a running DeepResearch task. The instruction can only be added before the writing phase begins. Use this to steer the research in a specific direction based on intermediate findings.", "tags": [ "DeepResearch" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "DeepResearch task ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchUpdateRequest" }, "examples": { "Add Instruction": { "summary": "Add follow-up instruction", "value": { "instruction": "Also compare the safety profiles across all trials" } } } } } }, "responses": { "200": { "description": "Instruction added successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchUpdateResponse" }, "examples": { "success": { "summary": "Task updated", "value": { "success": true, "message": "Task updated successfully", "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } }, "400": { "description": "Task is not in a state that accepts updates (writing phase has started or task is not running).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/tasks/{id}/cancel": { "post": { "operationId": "cancelDeepResearch", "summary": "Cancel a running or queued task", "description": "Cancel a DeepResearch task that is currently running or queued. Completed, failed, or already cancelled tasks cannot be cancelled.", "tags": [ "DeepResearch" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "DeepResearch task ID." } ], "responses": { "200": { "description": "Task cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchCancelResponse" }, "examples": { "success": { "summary": "Task cancelled", "value": { "success": true, "message": "Task cancelled successfully", "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } }, "400": { "description": "Task cannot be cancelled (not running or queued).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/tasks/{id}/delete": { "delete": { "operationId": "deleteDeepResearch", "summary": "Delete a completed, failed, or cancelled task", "description": "Permanently delete a DeepResearch task and its associated data (output, sources, PDF, images). Running or queued tasks must be cancelled first.", "tags": [ "DeepResearch" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "DeepResearch task ID." } ], "responses": { "200": { "description": "Task deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchDeleteResponse" }, "examples": { "success": { "summary": "Task deleted", "value": { "success": true, "message": "Task deleted successfully", "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } }, "400": { "description": "Task cannot be deleted (still running or queued).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/tasks/{id}/public": { "post": { "operationId": "toggleDeepResearchPublic", "summary": "Toggle public access for a task", "description": "Toggle the public visibility of a DeepResearch task. When set to `true`, the task results become accessible via a public share link without authentication. Only the task owner can modify the public flag.", "tags": [ "DeepResearch" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "DeepResearch task ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchTogglePublicRequest" }, "examples": { "Make Public": { "summary": "Make task publicly accessible", "value": { "public": true } }, "Make Private": { "summary": "Make task private", "value": { "public": false } } } } } }, "responses": { "200": { "description": "Public flag updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepResearchTogglePublicResponse" }, "examples": { "Made Public": { "summary": "Task made public", "value": { "success": true, "message": "Public flag updated", "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "public": true } }, "Made Private": { "summary": "Task made private", "value": { "success": true, "message": "Public flag updated", "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "public": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/tasks/{id}/respond": { "post": { "operationId": "respondToDeepResearch", "summary": "Respond to a HITL checkpoint", "description": "Respond to a human-in-the-loop checkpoint. The task must be in `awaiting_input` or `paused` status. Pass the `interaction_id` from the task's `interaction` field along with the response data matching the checkpoint type.", "tags": [ "DeepResearch" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "DeepResearch task ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["interaction_id", "response"], "properties": { "interaction_id": { "type": "string", "description": "The interaction_id from the task's interaction field." }, "response": { "description": "Response data — shape depends on the checkpoint type (`interaction.type`).", "oneOf": [ { "$ref": "#/components/schemas/HitlPlanningQuestionsResponse" }, { "$ref": "#/components/schemas/HitlPlanReviewResponse" }, { "$ref": "#/components/schemas/HitlSourceReviewResponse" }, { "$ref": "#/components/schemas/HitlOutlineReviewResponse" } ] } } }, "examples": { "Planning Questions": { "summary": "Answer planning questions", "value": { "interaction_id": "int_abc123", "response": { "answers": [ {"question": "What geographic regions?", "answer": "North America and EU"}, {"question": "Specific competitors?", "answer": "Tesla, BYD, Rivian"} ] } } }, "Plan Review": { "summary": "Approve research plan", "value": { "interaction_id": "int_abc123", "response": { "approved": true } } }, "Source Review": { "summary": "Filter sources by domain", "value": { "interaction_id": "int_abc123", "response": { "included_domains": ["sec.gov", "plos.org"], "excluded_domains": ["example.com"] } } } } } } }, "responses": { "200": { "description": "Response accepted. Task resumes processing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "string", "description": "`running` if container was still alive, `queued` if task was re-enqueued from paused state.", "enum": ["running", "queued"], "example": "running" }, "deepresearch_id": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } }, "400": { "description": "Validation error in response data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "response.answers must be an array" } } } } } }, "409": { "description": "Task is not in awaiting_input or paused status, or interaction_id mismatch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Cannot respond to task with status: running. Task must be in 'awaiting_input' or 'paused' status." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/batches": { "post": { "operationId": "createBatch", "summary": "Create a new batch", "description": "Create a batch for running multiple DeepResearch tasks with shared configuration. After creation, add tasks with the Add Tasks endpoint. The batch transitions from `open` to `processing` when tasks are added.", "tags": [ "Batches" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBatchRequest" }, "examples": { "example": { "summary": "Create a batch for earnings analysis", "value": { "name": "Q4 2024 Earnings Analysis", "mode": "standard", "output_formats": [ "markdown", "pdf" ], "search": { "search_type": "proprietary", "included_sources": [ "finance" ] } } } } } } }, "responses": { "201": { "description": "Batch created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" }, "examples": { "example": { "summary": "Batch created successfully", "value": { "batch_id": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "open", "mode": "standard", "name": "Q4 2024 Earnings Analysis", "output_formats": [ "markdown", "pdf" ], "search_params": { "search_type": "proprietary", "included_sources": [ "finance" ] }, "counts": { "total": 0, "queued": 0, "running": 0, "completed": 0, "failed": 0, "cancelled": 0 }, "cost": 0, "created_at": "2024-06-15T10:30:00.000Z", "webhook_secret": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "listBatches", "summary": "List all batches", "description": "Retrieve all batches for the authenticated API key.", "tags": [ "Batches" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Maximum number of batches to return." } ], "responses": { "200": { "description": "List of batches.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResponse" } }, "examples": { "success": { "summary": "List of batches", "value": [ { "batch_id": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "completed", "mode": "standard", "created_at": "2024-06-15T10:30:00.000Z", "counts": { "total": 5, "queued": 0, "running": 0, "completed": 5, "failed": 0, "cancelled": 0 }, "cost": 2.5 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/batches/{id}": { "get": { "operationId": "getBatchStatus", "summary": "Get batch status", "description": "Retrieve the current status, task counts, and aggregated cost of a batch.", "tags": [ "Batches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch ID.", "example": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ], "responses": { "200": { "description": "Batch status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" }, "examples": { "success": { "summary": "Batch status with counts", "value": { "batch_id": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "processing", "mode": "standard", "created_at": "2024-06-15T10:30:00.000Z", "counts": { "total": 10, "queued": 2, "running": 3, "completed": 4, "failed": 1, "cancelled": 0 }, "cost": 2.0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/batches/{id}/tasks": { "post": { "operationId": "addBatchTasks", "summary": "Add tasks to a batch", "description": "Add up to 100 research tasks to an existing batch. The batch must be in `open` or `processing` status.", "tags": [ "Batches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddBatchTasksRequest" }, "examples": { "example": { "summary": "Add earnings analysis tasks", "value": { "tasks": [ { "query": "Analyze Tesla Q4 2024 earnings and forward guidance", "id": "task-tesla" }, { "query": "Analyze Apple Q4 2024 earnings and iPhone sales", "id": "task-apple" }, { "query": "Analyze Microsoft Q4 2024 earnings and Azure growth", "id": "task-msft" } ] } } } } } }, "responses": { "202": { "description": "Tasks added and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddBatchTasksResponse" } } } }, "400": { "description": "Batch is not accepting tasks (not open or processing).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "listBatchTasks", "summary": "List tasks in a batch", "description": "Retrieve tasks within a batch with optional status filtering and cursor-based pagination. Use `include_output=true` to get full output, sources, images, and cost for each task. When `include_output` is false (default), returns a lightweight listing with status only.", "tags": [ "Batches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch ID." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "description": "Filter tasks by status." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Maximum number of tasks to return." }, { "name": "last_key", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Pagination cursor. Omit on first request. Pass the `last_key` value from a previous response to fetch the next page." }, { "name": "include_output", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "example": true, "description": "Include full output, sources, images, and cost for each task. When false (default), returns lightweight task listing with status only." } ], "responses": { "200": { "description": "Paginated list of batch tasks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchTaskListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/deepresearch/batches/{id}/cancel": { "post": { "operationId": "cancelBatch", "summary": "Cancel a batch", "description": "Cancel all queued and running tasks in a batch. The batch must be in `open` or `processing` status.", "tags": [ "Batches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch ID." } ], "responses": { "200": { "description": "Batch cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelBatchResponse" }, "examples": { "success": { "summary": "Batch cancelled", "value": { "batch_id": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "cancelled", "cancelled_count": 3 } } } } } }, "400": { "description": "Batch cannot be cancelled (not open or processing).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/datasources": { "get": { "operationId": "listDatasources", "summary": "List available data sources", "description": "Discover all data sources available through Valyu's search API. Each datasource includes metadata, example queries (optimized for few-shot prompting), pricing information, and response schemas.\n\nUse this endpoint to build dynamic tool manifests for AI agents instead of hardcoding knowledge of available datasets.", "tags": [ "Datasources" ], "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter datasources by category. Use the categories endpoint to discover available categories.", "example": "research" } ], "responses": { "200": { "description": "List of available datasources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasourcesResponse" }, "examples": { "example": { "summary": "All datasources", "value": { "success": true, "datasources": [ { "id": "valyu/valyu-arxiv", "name": "arXiv", "description": "Preprints in physics, mathematics, computer science, quantitative biology, and more.", "category": "research", "topics": [ "physics", "mathematics", "computer science" ], "modality": "text", "example_queries": [ "CRISPR gene editing mechanisms", "quantum error correction methods" ], "pricing": { "cpm": 0.5 }, "update_frequency": "daily", "size": "2.5M papers" }, { "id": "valyu/valyu-pubmed", "name": "PubMed", "description": "Biomedical literature from MEDLINE, life science journals, and online books.", "category": "healthcare", "topics": [ "medicine", "biology", "pharmacology" ], "modality": "text", "example_queries": [ "GLP-1 receptor agonists for type 2 diabetes", "CAR-T cell therapy advances" ], "pricing": { "cpm": 0.5 }, "update_frequency": "daily", "size": "36M citations" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/datasources/categories": { "get": { "operationId": "listDatasourceCategories", "summary": "List datasource categories", "description": "Retrieve all available datasource categories. Use these to filter the datasources endpoint.\n\nCategories include: `research`, `healthcare`, `markets`, `company`, `economic`, `predictions`, `transportation`, `legal`, `politics`, `patents`.", "tags": [ "Datasources" ], "responses": { "200": { "description": "List of datasource categories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasourceCategoriesResponse" }, "examples": { "example": { "summary": "All categories", "value": { "success": true, "categories": [ { "id": "research", "name": "Research", "description": "Academic papers, preprints, and scholarly articles.", "dataset_count": 8 }, { "id": "healthcare", "name": "Healthcare", "description": "Medical literature, clinical trials, drug data, and health records.", "dataset_count": 6 }, { "id": "markets", "name": "Markets", "description": "Stock prices, earnings, SEC filings, and financial data.", "dataset_count": 5 } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/datasources/search": { "get": { "operationId": "searchDatasources", "summary": "Search datasources", "description": "Find datasets by describing what you need in natural language, e.g. `Wiley medical literature`, `FDA drug labels`, `insider transactions`, `CPI inflation`. Ranking is semantic (embedding similarity) blended with exact-term matching, so both descriptive phrases and terse acronyms work.\n\nUse the returned `id` values as `included_sources` on the Search API. Results are ranked best-first with a `relevance_score` in the range 0-1; a query matching nothing in the catalog returns an empty list rather than a weak guess.\n\nOnly datasets your key can search are returned (the same visibility rules as `GET /v1/datasources`).", "tags": [ "Datasources" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Natural-language description of the data you want.", "example": "clinical trial results" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of datasets to return." } ], "responses": { "200": { "description": "Ranked datasets matching the query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasourceSearchResponse" }, "examples": { "example": { "summary": "FDA drug label", "value": { "success": true, "query": "FDA drug label", "search_mode": "semantic", "total_count": 3, "results": [ { "id": "valyu/valyu-drug-labels", "name": "FDA Drug Labels", "category": "healthcare", "relevance_score": 0.7969 }, { "id": "valyu/valyu-openfda-drug-events", "name": "openFDA Drug Adverse Events", "category": "healthcare", "relevance_score": 0.3927 }, { "id": "valyu/valyu-pubchem", "name": "PubChem", "category": "healthcare", "relevance_score": 0.2539 } ] } } } } } }, "400": { "description": "Missing `q` parameter." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/workflows": { "get": { "operationId": "listWorkflows", "summary": "List workflows (Beta)", "description": "**Beta.** List workflows visible to your organization. Includes both your org's private workflows and curated Valyu workflows. Run a workflow by passing its `slug` as `workflow_id` to `POST /v1/deepresearch/tasks`.", "tags": [ "Workflows" ], "parameters": [ { "name": "vertical", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by vertical (e.g. `finance`, `life-sciences`).", "example": "finance" }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": ["valyu", "org", "all"], "default": "all" }, "description": "Which workflows to return: `valyu` (curated only), `org` (your org only), or `all` (both, default)." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search across title, subtitle, and description.", "example": "diligence" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated tags to filter by.", "example": "earnings,equities" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of workflows to return (max 100)." }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of fields to expand. Pass `version` to include the full current version row for each workflow.", "example": "version" } ], "responses": { "200": { "description": "List of workflows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createWorkflow", "summary": "Create an organization workflow (Beta)", "description": "**Beta.** Create a private workflow owned by your organization. Subject to your org's workflow quota (default 100). Returns `409 workflow_quota_exceeded` when the quota is reached.", "tags": [ "Workflows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowCreateRequest" } } } }, "responses": { "201": { "description": "Workflow created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/WorkflowBadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/WorkflowConflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/workflows/{slug}": { "get": { "operationId": "getWorkflow", "summary": "Get a workflow (Beta)", "description": "**Beta.** Retrieve a single workflow with its resolved version. By default returns the current version; pass `version` to fetch a specific one.", "tags": [ "Workflows" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workflow slug.", "example": "ib-company-profile" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Version to return. Defaults to the current version.", "example": 3 } ], "responses": { "200": { "description": "The workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/WorkflowNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateWorkflow", "summary": "Edit a workflow / publish a new version (Beta)", "description": "**Beta.** Edit an organization workflow, publishing a new immutable version. A `changelog` is required (`changelog_required` otherwise). Valyu-curated workflows are read-only and return `403 cannot_edit_valyu_workflow`.", "tags": [ "Workflows" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workflow slug.", "example": "ib-company-profile" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowUpdateRequest" } } } }, "responses": { "200": { "description": "New version published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/WorkflowBadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/WorkflowForbidden" }, "404": { "$ref": "#/components/responses/WorkflowNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteWorkflow", "summary": "Delete a workflow (Beta)", "description": "**Beta.** Soft-delete an organization workflow. Valyu-curated workflows cannot be deleted and return `403 cannot_delete_valyu_workflow`.", "tags": [ "Workflows" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workflow slug.", "example": "ib-company-profile" } ], "responses": { "200": { "description": "Workflow deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/WorkflowForbidden" }, "404": { "$ref": "#/components/responses/WorkflowNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/workflows/{slug}/versions": { "get": { "operationId": "listWorkflowVersions", "summary": "List workflow versions (Beta)", "description": "**Beta.** List all immutable versions of a workflow, newest first.", "tags": [ "Workflows" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workflow slug.", "example": "ib-company-profile" } ], "responses": { "200": { "description": "List of versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowVersionListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/WorkflowNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/workflows/{slug}/versions/{n}": { "get": { "operationId": "getWorkflowVersion", "summary": "Get a specific workflow version (Beta)", "description": "**Beta.** Retrieve a workflow resolved at a specific immutable version. Returns the same flat workflow object as `GET /v1/workflows/{slug}?version={n}`.", "tags": [ "Workflows" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workflow slug.", "example": "ib-company-profile" }, { "name": "n", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The version number.", "example": 2 } ], "responses": { "200": { "description": "The workflow resolved at the requested version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/WorkflowNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/workflows/{slug}/preview": { "post": { "operationId": "previewWorkflow", "summary": "Preview a resolved workflow (Beta)", "description": "**Beta.** Resolve a workflow's prompt template against supplied `workflow_params` without running it. Returns the resolved prompt, research strategy, report format, deliverables, recommended mode, and tools - exactly what a run would use. Useful for validating parameters before incurring a DeepResearch cost.", "tags": [ "Workflows" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workflow slug.", "example": "ib-company-profile" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowPreviewRequest" } } } }, "responses": { "200": { "description": "Resolved configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowPreviewResponse" } } } }, "400": { "$ref": "#/components/responses/WorkflowBadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/WorkflowNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "externalDocs": { "description": "Complete API Documentation", "url": "https://docs.valyu.ai" }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for authentication. Get yours at [platform.valyu.ai](https://platform.valyu.ai)." } }, "schemas": { "Error": { "type": "object", "description": "Standard error response.", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "description": "Always `false` for error responses.", "example": false }, "error": { "type": "string", "description": "Human-readable error message describing what went wrong.", "example": "Invalid request parameters" } } }, "SearchRequest": { "type": "object", "required": [ "query" ], "additionalProperties": false, "description": "Search request parameters.", "properties": { "query": { "type": "string", "description": "The search query to execute. Supports natural language queries.", "example": "latest developments in quantum computing" }, "max_num_results": { "type": "integer", "description": "Maximum number of results to return. Higher limits (up to 100) available on request.", "default": 5, "minimum": 1, "maximum": 20, "example": 10 }, "search_type": { "type": "string", "description": "Controls which data sources are searched.\n\n- `all` - Web and proprietary sources (default). An LLM router selects the best sources for your query.\n- `web` - Web search only. Best for current events and general topics.\n- `proprietary` - Academic, financial, and premium sources only. Best for research and technical analysis.\n- `news` - News articles only. Best for recent news and current events.", "enum": [ "all", "web", "proprietary", "news" ], "default": "all", "example": "all" }, "max_price": { "type": "number", "description": "Maximum budget in CPM (cost per mille/thousand tokens). When not set, automatically calculated based on `max_num_results` and `search_type`.", "minimum": 0, "exclusiveMinimum": true, "example": 20.0 }, "relevance_threshold": { "type": "number", "description": "Minimum relevance score (0.0-1.0) for results after reranking. Results below this threshold are filtered out.", "default": 0.5, "minimum": 0.0, "maximum": 1.0, "example": 0.5 }, "included_sources": { "type": "array", "description": "Sources to include in the search. Accepts:\n- Domain names or URLs for web filtering (e.g. `\"arxiv.org\"`, `\"https://arxiv.org\"`)\n- Dataset identifiers for proprietary sources (e.g. `\"valyu/valyu-arxiv\"`)\n- Preset names that expand to curated source groups: `\"academic\"`, `\"finance\"`, `\"patent\"`, `\"transportation\"`, `\"politics\"`, `\"legal\"`, `\"health\"`, `\"genomics\"`, `\"chemistry\"`, `\"physics\"`\n- `\"web\"` keyword to explicitly include web search alongside proprietary sources\n- `\"collection:NAME\"` to reference an org-scoped saved source collection\n\nNote: most specialised and proprietary sources require a subscription. All plans include web search and open academic sources (arXiv, PubMed).", "items": { "type": "string" }, "example": [ "valyu/valyu-arxiv", "valyu/valyu-pubmed" ] }, "excluded_sources": { "type": "array", "description": "Sources to exclude from the search. Same format as `included_sources` except presets are not supported.", "items": { "type": "string" }, "example": [ "reddit.com" ] }, "source_biases": { "type": "object", "description": "Bias values for specific sources to influence ranking without hard filtering. Keys are domains (e.g., 'nasa.gov') or URL paths (e.g., 'nih.gov/research'). Values are integers from -5 (strong demotion) to +5 (strong boost). Most specific path match wins.", "additionalProperties": { "type": "integer", "minimum": -5, "maximum": 5 }, "nullable": true, "example": { "nasa.gov": 5, "noaa.gov": 3, "nih.gov": 1, "example.com": -4 } }, "instructions": { "type": "string", "description": "Natural language instructions to help rank results by relevance to user intent. Acts as a system prompt for the search. Max 500 characters. Ignored when fast_mode is true.", "maxLength": 500, "example": "Focus on oncology clinical trials from 2023 onwards" }, "category": { "type": "string", "deprecated": true, "description": "**Deprecated.** Use `instructions` instead. Falls back to this value if `instructions` is not set.", "maxLength": 500 }, "is_tool_call": { "type": "boolean", "description": "Indicates whether this request originates from an AI tool call. Affects query rewriting behavior.", "default": true }, "response_length": { "description": "Controls the maximum character length of content per result.\n\n- `\"short\"` - 25,000 characters (default)\n- `\"medium\"` - 50,000 characters\n- `\"large\"` - 100,000 characters\n- `\"max\"` - No limit\n- Any positive integer for a custom character limit", "oneOf": [ { "type": "string", "enum": [ "short", "medium", "large", "max" ] }, { "type": "integer", "minimum": 1 } ], "default": "short", "example": "short" }, "start_date": { "type": "string", "format": "date", "description": "Filter results published on or after this date. Format: `YYYY-MM-DD`. If set without `end_date`, defaults to today.", "example": "2024-01-01" }, "end_date": { "type": "string", "format": "date", "description": "Filter results published on or before this date. Format: `YYYY-MM-DD`. If set without `start_date`, defaults to `1900-01-01`.", "example": "2024-12-31" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code for geo-targeted web search results.", "enum": [ "ALL", "AR", "AU", "AT", "BE", "BR", "CA", "CL", "DK", "FI", "FR", "DE", "HK", "IN", "ID", "IT", "JP", "KR", "MY", "MX", "NL", "NZ", "NO", "CN", "PL", "PT", "PH", "RU", "SA", "ZA", "ES", "SE", "CH", "TW", "TR", "GB", "US" ], "example": "US" }, "fast_mode": { "type": "boolean", "description": "Bypass LLM query rewriting and reranking for lower latency. Forces web-only search. Cannot be used with `search_type: \"proprietary\"`.", "default": false }, "url_only": { "type": "boolean", "description": "Return only URLs without full content extraction. Only available when `search_type` is `\"web\"` or `\"news\"`. Skips reranking.", "default": false }, "historical_cache": { "type": "boolean", "description": "Run the search as a point-in-time query: serve the newest cached snapshot inside the `start_date`/`end_date` window instead of the latest crawl. This is what makes a historical backtest reproducible and keeps it from seeing content published after its cutoff. Also required to pass a sub-day timestamp on `start_date`/`end_date` — a full ISO-8601 datetime without it returns HTTP 400. No-op without a date range.", "default": false }, "historical_cache_strict": { "type": "string", "enum": ["off", "prefer", "only"], "description": "Point-in-time strictness for a `historical_cache` search. `\"only\"` serves ONLY content provably captured at or before `end_date`, dropping a result rather than falling back to a live crawl — use it for strict backtests, where a post-cutoff leak is worse than a missing result. `\"prefer\"` (the default) serves an in-window snapshot when one exists and otherwise falls back to a LIVE crawl so the query is never empty. `\"off\"` disables the point-in-time guarantee. No-op without `historical_cache: true`.", "default": "prefer" }, "include_abstracts": { "type": "boolean", "description": "Expand PubMed search from papers with available full text to the complete abstract corpus. Results include the abstract and, when full text is available, the most relevant full-text chunks. Has no effect on other sources.", "default": false } } }, "SearchResult": { "type": "object", "description": "A single search result with extracted content.", "required": [ "id", "title", "url", "content", "source", "price", "length", "data_type", "source_type" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this result (typically the URL).", "example": "https://arxiv.org/abs/2024.12345" }, "title": { "type": "string", "description": "Title of the source document.", "example": "Quantum Computing Breakthrough: New Error Correction Method" }, "url": { "type": "string", "format": "uri", "description": "URL of the source document.", "example": "https://arxiv.org/abs/2024.12345" }, "content": { "type": "string", "description": "Extracted text content in markdown format, truncated to `response_length`.", "example": "Researchers at MIT have developed a revolutionary quantum error correction method..." }, "description": { "type": "string", "nullable": true, "description": "Short description or meta summary of the document.", "example": "Major breakthrough in quantum error correction methodology" }, "source": { "type": "string", "description": "Source identifier. `\"web\"` for web results, or a proprietary source name.", "example": "web" }, "price": { "type": "number", "description": "Cost in USD for this individual result.", "example": 0.0015 }, "length": { "type": "integer", "description": "Character count of the `content` field.", "example": 15420 }, "image_url": { "nullable": true, "description": "Image URLs associated with this result, keyed by index. `null` if no images.", "oneOf": [ { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, { "type": "string", "format": "uri" } ], "example": { "0": "https://example.com/image.jpg" } }, "relevance_score": { "type": "number", "description": "Relevance score from reranking (0.0-1.0). Higher is more relevant.", "minimum": 0.0, "maximum": 1.0, "example": 0.92 }, "data_type": { "type": "string", "description": "Format of the content field.", "enum": [ "unstructured", "structured" ], "example": "unstructured" }, "source_type": { "type": "string", "description": "Classification of the source.\n\n- `website` - General web page\n- `forum` - Forum or discussion thread\n- `paper` - Academic paper\n- `data` - Structured data source\n- `report` - Report or analysis\n- `health_data` - Healthcare data\n- `clinical_trial` - Clinical trial record\n- `drug_label` - FDA drug label\n- `grants` - Research grant", "enum": [ "website", "forum", "paper", "data", "report", "health_data", "clinical_trial", "drug_label", "grants" ], "example": "website" }, "publication_date": { "type": "string", "description": "Publication date in `YYYY-MM-DD` format, or empty string if unknown.", "example": "2024-06-15" }, "abstract": { "type": "string", "description": "Document-level abstract for academic results when available.", "example": "Clonal hematopoiesis is associated with an increased risk of cardiovascular disease and adverse outcomes." }, "doi": { "type": "string", "description": "DOI identifier (academic results only).", "example": "10.1038/s41586-024-07107-7" }, "citation": { "type": "string", "description": "Citation text (academic results only).", "example": "" }, "citation_count": { "type": "integer", "description": "Number of citations (academic results only).", "example": 42 }, "authors": { "type": "array", "description": "Author names (academic results only).", "items": { "type": "string" }, "example": [ "J. Smith", "A. Chen" ] }, "references": { "type": "string", "description": "References text (academic results only).", "example": "" }, "metadata": { "type": "object", "description": "Additional structured metadata (financial and specialized results only).", "additionalProperties": true } } }, "SearchResponse": { "type": "object", "description": "Search response containing results and metadata.", "required": [ "success", "tx_id", "query", "results", "results_by_source", "total_deduction_dollars", "total_characters" ], "properties": { "success": { "type": "boolean", "description": "Whether the search completed successfully.", "example": true }, "error": { "type": "string", "nullable": true, "description": "Error or warning message. May be non-empty even on successful responses if some sources had issues.", "example": null }, "tx_id": { "type": "string", "description": "Transaction ID for tracking and support.", "example": "tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "query": { "type": "string", "description": "The original query as submitted.", "example": "latest developments in quantum computing" }, "results": { "type": "array", "description": "Search results ordered by relevance.", "items": { "$ref": "#/components/schemas/SearchResult" } }, "results_by_source": { "type": "object", "description": "Count of results broken down by source type.", "properties": { "web": { "type": "integer", "description": "Number of web results.", "example": 5 }, "proprietary": { "type": "integer", "description": "Number of proprietary results.", "example": 3 } }, "example": { "web": 5, "proprietary": 3 } }, "total_deduction_dollars": { "type": "number", "description": "Total cost charged for this search in USD.", "example": 0.0075 }, "total_characters": { "type": "integer", "description": "Sum of all result content lengths in characters.", "example": 45230 }, "warnings": { "type": "array", "description": "Warning messages, if any (e.g. collection resolution warnings). Only present when warnings exist.", "items": { "type": "string" } } } }, "ContentsRequest": { "type": "object", "required": [ "urls" ], "additionalProperties": true, "description": "Content extraction request parameters.", "properties": { "urls": { "type": "array", "description": "URLs to extract content from. Must be valid HTTP/HTTPS URLs. Duplicates are silently removed.", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 50, "example": [ "https://en.wikipedia.org/wiki/Quantum_computing", "https://arxiv.org/abs/2401.00001" ] }, "response_length": { "description": "Maximum character length of extracted content per URL.\n\n- `\"short\"` - 25,000 characters (default)\n- `\"medium\"` - 50,000 characters\n- `\"large\"` - 100,000 characters\n- `\"max\"` - No limit\n- Any positive integer for a custom character limit", "oneOf": [ { "type": "string", "enum": [ "short", "medium", "large", "max" ] }, { "type": "integer", "minimum": 1 } ], "default": "short" }, "max_price_dollars": { "type": "number", "description": "Maximum budget in USD for this request. If estimated cost exceeds this, the request is rejected. Defaults to 2x the maximum possible cost.", "minimum": 0, "exclusiveMinimum": true, "example": 0.05 }, "summary": { "description": "Controls AI-powered content processing. Adds $0.001 per URL when enabled.\n\n- `false` - No AI processing, raw extracted content only (default)\n- `true` - Generate a text summary of each page\n- `\"string\"` - Generate a summary guided by custom instructions (max 500 characters)\n- `{json_schema}` - Extract structured data matching the provided JSON schema", "oneOf": [ { "type": "boolean" }, { "type": "string", "maxLength": 500 }, { "type": "object", "description": "JSON Schema for structured extraction. Supports types: object, array, string, number, integer, boolean." } ], "default": false }, "extract_effort": { "type": "string", "description": "Controls how pages are rendered for extraction.\n\n- `\"auto\"` - Automatically selects the best method per URL (default)\n- `\"normal\"` - HTTP-only extraction, fastest\n- `\"high\"` - Full Chrome rendering, best for JavaScript-heavy pages", "enum": [ "auto", "normal", "high" ], "default": "auto" }, "screenshot": { "type": "boolean", "description": "Capture a screenshot of each page. Screenshot URL returned in `screenshot_url` field of each result.", "default": false }, "async": { "type": "boolean", "description": "Process URLs asynchronously in the background. Returns a `job_id` to poll via `GET /v1/contents/jobs/{job_id}`. Useful for slow, JavaScript-heavy pages.", "default": false }, "webhook_url": { "type": "string", "format": "uri", "description": "HTTPS URL to receive a webhook POST when async processing completes. Only used when `async` is `true`. The webhook payload is signed with HMAC-SHA256.", "example": "https://your-app.com/webhooks/valyu" } } }, "ContentResult": { "type": "object", "description": "Extracted content from a single URL.", "required": [ "url", "status" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The URL that was processed.", "example": "https://en.wikipedia.org/wiki/Quantum_computing" }, "status": { "type": "string", "description": "Processing status for this URL.", "enum": [ "success", "failed" ], "example": "success" }, "title": { "type": "string", "description": "Page title. Present when `status` is `\"success\"`.", "example": "Quantum computing - Wikipedia" }, "content": { "description": "Extracted content. Markdown string when `data_type` is `\"unstructured\"`, JSON object when `data_type` is `\"structured\"`. Present when `status` is `\"success\"`.", "oneOf": [ { "type": "string", "description": "Markdown-formatted content." }, { "type": "object", "description": "Structured data matching the provided JSON schema." } ], "example": "# Quantum computing\n\nQuantum computing is a type of computation..." }, "description": { "type": "string", "description": "Meta description of the page.", "example": "Quantum computing is a type of computation that harnesses quantum mechanical phenomena." }, "source": { "type": "string", "description": "`\"web\"` for web pages, or the dataset id for academic papers served from Valyu's processed index (e.g. `valyu/valyu-arxiv`, `valyu/valyu-pubmed`, `valyu/valyu-biorxiv`, `valyu/valyu-medrxiv`, `valyu/valyu-chemrxiv`).", "example": "web" }, "price": { "type": "number", "description": "Cost in USD for extracting this URL.", "example": 0.001 }, "length": { "type": "integer", "description": "Character count of the `content` field.", "example": 24500 }, "data_type": { "type": "string", "description": "`\"unstructured\"` for text content, `\"structured\"` when JSON schema extraction succeeded.", "enum": [ "unstructured", "structured" ], "example": "unstructured" }, "source_type": { "type": "string", "description": "Classification of the content type. `\"paper\"` for academic papers served from the processed index.", "enum": [ "website", "pdf", "txt", "json", "xml", "sitemap", "csv", "paper" ], "example": "website" }, "publication_date": { "type": "string", "description": "Publication date in `YYYY-MM-DD` format, or empty string if unknown.", "example": "2024-03-15" }, "id": { "type": "string", "description": "Identifier for this result. The URL for web pages, or the bare paper id / DOI for academic papers (e.g. `2506.05440`, `10.26434/chemrxiv-2025-chn4j`).", "example": "https://en.wikipedia.org/wiki/Quantum_computing" }, "image_url": { "type": "object", "description": "Image URLs found on the page, keyed by index.", "additionalProperties": { "type": "string", "format": "uri" }, "example": { "0": "https://upload.wikimedia.org/wikipedia/commons/quantum.png" } }, "screenshot_url": { "type": "string", "format": "uri", "nullable": true, "description": "Screenshot URL if `screenshot` was enabled. `null` otherwise.", "example": null }, "summary": { "description": "AI-generated summary or structured extraction result. Only present when `summary` was enabled in the request.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "summary_success": { "type": "boolean", "description": "Whether AI processing succeeded. Only present when `summary` was enabled." }, "structured_metadata": { "type": "object", "description": "Metadata from structured data extraction. Only present when `data_type` is `\"structured\"`.", "additionalProperties": true }, "error": { "type": "string", "description": "Human-readable failure reason. Only present when `status` is `\"failed\"`. Describes why extraction failed without exposing internal infrastructure.", "example": "Could not extract content from this URL. The page may be unavailable, require sign-in, or block automated access." }, "doi": { "type": "string", "description": "Paper DOI. Present for academic papers served from the processed index.", "example": "10.26434/chemrxiv-2025-chn4j" }, "authors": { "type": "array", "items": { "type": "string" }, "description": "Paper authors. Present for academic papers served from the processed index." }, "citation_count": { "type": "integer", "description": "Citation count. Present for academic papers served from the processed index.", "example": 5 } } }, "ContentsResponse": { "type": "object", "description": "Synchronous content extraction response.", "required": [ "success", "tx_id", "urls_requested", "urls_processed", "urls_failed", "results", "total_cost_dollars", "total_characters" ], "properties": { "success": { "type": "boolean", "description": "Whether the extraction completed successfully.", "example": true }, "error": { "type": "string", "nullable": true, "description": "Error message if some URLs failed. `null` on complete success.", "example": null }, "tx_id": { "type": "string", "description": "Transaction ID for tracking.", "example": "tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "urls_requested": { "type": "integer", "description": "Number of deduplicated URLs submitted.", "example": 3 }, "urls_processed": { "type": "integer", "description": "Number of URLs successfully processed.", "example": 3 }, "urls_failed": { "type": "integer", "description": "Number of URLs that failed processing.", "example": 0 }, "results": { "type": "array", "description": "Extraction results for each URL.", "items": { "$ref": "#/components/schemas/ContentResult" } }, "total_cost_dollars": { "type": "number", "description": "Total cost in USD (only successful URLs are charged).", "example": 0.003 }, "total_characters": { "type": "integer", "description": "Sum of all result content lengths.", "example": 45230 } } }, "ContentsAsyncResponse": { "type": "object", "description": "Response returned when async processing is initiated.", "required": [ "success", "job_id", "status", "urls_total", "poll_url", "tx_id" ], "properties": { "success": { "type": "boolean", "description": "Whether the async job was created successfully.", "example": true }, "job_id": { "type": "string", "description": "Job identifier for polling status.", "example": "cj_a1b2c3d4e5f6g7h8" }, "status": { "type": "string", "description": "Initial job status.", "enum": [ "pending" ], "example": "pending" }, "urls_total": { "type": "integer", "description": "Total number of URLs queued for processing.", "example": 25 }, "poll_url": { "type": "string", "description": "Relative URL to poll for job status.", "example": "/contents/jobs/cj_a1b2c3d4e5f6g7h8" }, "tx_id": { "type": "string", "description": "Transaction ID.", "example": "tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "webhook_secret": { "type": "string", "description": "HMAC-SHA256 secret for verifying webhook payloads. Only present when `webhook_url` was provided.", "example": "a1b2c3d4e5f6...64_hex_characters" } } }, "ContentsJobResponse": { "type": "object", "description": "Async job status and results.", "required": [ "success", "job_id", "status", "urls_total", "urls_processed", "urls_failed" ], "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded.", "example": true }, "job_id": { "type": "string", "description": "Unique identifier for the async job.", "example": "cj_a1b2c3d4e5f6g7h8" }, "status": { "type": "string", "description": "Current job status.\n\n- `pending` - Job created, not yet started\n- `processing` - URLs are being processed\n- `completed` - All URLs processed successfully\n- `partial` - Processing finished with some failures\n- `failed` - All URLs failed", "enum": [ "pending", "processing", "completed", "partial", "failed" ], "example": "completed" }, "urls_total": { "type": "integer", "description": "Total number of URLs to process.", "example": 25 }, "urls_processed": { "type": "integer", "description": "Number of URLs successfully processed so far.", "example": 23 }, "urls_failed": { "type": "integer", "description": "Number of URLs that failed processing.", "example": 2 }, "created_at": { "type": "integer", "description": "Job creation time as Unix timestamp in milliseconds.", "example": 1707000000000 }, "updated_at": { "type": "integer", "description": "Last update time as Unix timestamp in milliseconds.", "example": 1707000060000 }, "current_batch": { "type": "integer", "description": "Current batch being processed. Only present when `status` is `\"processing\"`.", "example": 3 }, "total_batches": { "type": "integer", "description": "Total number of batches. Only present when `status` is `\"processing\"`.", "example": 5 }, "results": { "type": "array", "description": "Extraction results. Only present when `status` is `\"completed\"` or `\"partial\"`.", "items": { "$ref": "#/components/schemas/ContentResult" } }, "actual_cost_dollars": { "type": "number", "description": "Total cost in USD. Only present when processing is complete.", "example": 0.023 }, "error": { "type": "string", "description": "Error message. Only present when `status` is `\"failed\"` or `\"partial\"`." } } }, "AnswerRequest": { "type": "object", "required": [ "query" ], "additionalProperties": false, "description": "Answer API request parameters.", "properties": { "query": { "type": "string", "description": "The question or research query to answer.", "example": "What are the latest FDA-approved treatments for type 2 diabetes?" }, "search_type": { "type": "string", "description": "Controls which data sources are searched.\n\n- `all` - Web and proprietary sources (default)\n- `web` - Web search only\n- `proprietary` - Academic, financial, and premium sources only\n- `news` - News articles only", "enum": [ "all", "web", "proprietary", "news" ], "default": "all" }, "included_sources": { "type": "array", "description": "Sources to include. Accepts domains, URLs, dataset identifiers, or presets (`\"finance\"`, `\"medical\"`).", "items": { "type": "string" }, "example": [ "pubmed.ncbi.nlm.nih.gov" ] }, "excluded_sources": { "type": "array", "description": "Sources to exclude. Same format as `included_sources` except presets are not supported.", "items": { "type": "string" } }, "data_max_price": { "type": "number", "description": "Maximum budget in USD for the search data component. Converted to CPM internally.", "default": 1.0, "minimum": 0, "exclusiveMinimum": true, "example": 1.0 }, "start_date": { "type": "string", "format": "date", "description": "Filter results published on or after this date. Format: `YYYY-MM-DD`.", "example": "2024-01-01" }, "end_date": { "type": "string", "format": "date", "description": "Filter results published on or before this date. Format: `YYYY-MM-DD`.", "example": "2024-12-31" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code for geo-targeted search.", "enum": [ "ALL", "AR", "AU", "AT", "BE", "BR", "CA", "CL", "DK", "FI", "FR", "DE", "HK", "IN", "ID", "IT", "JP", "KR", "MY", "MX", "NL", "NZ", "NO", "CN", "PL", "PT", "PH", "RU", "SA", "ZA", "ES", "SE", "CH", "TW", "TR", "GB", "US" ] }, "fast_mode": { "type": "boolean", "description": "Enable fast mode for lower latency. Uses 3 tool call rounds instead of 2 and higher result counts per query.", "default": false }, "structured_output": { "type": "object", "nullable": true, "description": "JSON Schema defining the desired output structure. When set, the AI returns a JSON object matching this schema instead of free-form text. Max depth 10, max 50 properties, max 5000 characters.", "example": { "type": "object", "properties": { "treatments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "approval_date": { "type": "string" }, "mechanism": { "type": "string" } } } } } } }, "system_instructions": { "type": "string", "nullable": true, "description": "Custom system instructions for the AI. Replaces the default research agent prompt. Max 2000 characters.", "maxLength": 2000, "example": "You are a medical research assistant. Cite all sources." } } }, "SearchConfig": { "type": "object", "description": "Search configuration for DeepResearch tasks.", "properties": { "search_type": { "type": "string", "enum": [ "all", "web", "proprietary" ], "description": "Controls which data sources are searched.", "default": "all" }, "included_sources": { "type": "array", "description": "Sources to include. Max 20 items.", "items": { "type": "string" }, "maxItems": 20 }, "excluded_sources": { "type": "array", "description": "Sources to exclude. Max 20 items.", "items": { "type": "string" }, "maxItems": 20 }, "source_biases": { "type": "object", "description": "Bias values for specific sources to influence ranking (-5 to +5). Applied to every search call during research.", "additionalProperties": { "type": "integer", "minimum": -5, "maximum": 5 } }, "country_code": { "type": "string", "enum": [ "ALL", "AR", "AU", "AT", "BE", "BR", "CA", "CL", "DK", "FI", "FR", "DE", "HK", "IN", "ID", "IT", "JP", "KR", "MY", "MX", "NL", "NZ", "NO", "CN", "PL", "PT", "PH", "RU", "SA", "ZA", "ES", "SE", "CH", "TW", "TR", "GB", "US" ], "description": "Country code for geo-targeted search." }, "start_date": { "type": "string", "format": "date", "description": "Filter results from this date. Format: `YYYY-MM-DD`." }, "end_date": { "type": "string", "format": "date", "description": "Filter results until this date. Format: `YYYY-MM-DD`. Must be >= `start_date`." } } }, "FileAttachment": { "type": "object", "description": "A file to include in the research task.", "required": [ "data", "filename", "mediaType" ], "properties": { "data": { "type": "string", "description": "File content as a data URL. Format: `data:;base64,`.", "example": "data:application/pdf;base64,JVBERi0xLjQK..." }, "filename": { "type": "string", "description": "Original filename.", "example": "research_paper.pdf" }, "mediaType": { "type": "string", "description": "MIME type of the file.", "example": "application/pdf" }, "context": { "type": "string", "description": "Optional context about the file to guide the research agent. Maximum 50,000 characters per file and 100,000 characters combined across all files.", "maxLength": 50000 } } }, "MCPServerConfig": { "type": "object", "description": "MCP (Model Context Protocol) server configuration for tool access during research.", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTP/HTTPS URL of the MCP server.", "example": "https://mcp.example.com/tools" }, "name": { "type": "string", "description": "Display name for the MCP server." }, "tool_prefix": { "type": "string", "description": "Prefix for tool names. Defaults to the server hostname." }, "auth": { "type": "object", "description": "Authentication configuration.", "properties": { "type": { "type": "string", "enum": [ "bearer", "header", "none" ], "description": "Authentication type." }, "token": { "type": "string", "description": "Bearer token (when `type` is `\"bearer\"`)." }, "headers": { "type": "object", "description": "Custom headers (when `type` is `\"header\"`).", "additionalProperties": { "type": "string" } } } }, "allowed_tools": { "type": "array", "description": "Whitelist of tool names to expose. If omitted, all tools are available.", "items": { "type": "string" } } } }, "DeepResearchCreateRequest": { "type": "object", "required": [ "query" ], "additionalProperties": false, "description": "Request to create a DeepResearch task.\n\nA task can be either **freeform** (provide `query`/`input` plus optional `research_strategy`, `report_format`, etc.) or **workflow-driven** (provide `workflow_id` + `workflow_params`). The two modes are mutually exclusive: passing `workflow_id` alongside freeform fields (`query`, `input`, `research_strategy`, `report_format`) returns `400 workflow_and_freeform_mutually_exclusive`. When running a workflow, any `mode`/`deliverables`/`tools` you pass in the body override the template defaults.", "properties": { "query": { "type": "string", "description": "The research query or question. Use `query` (preferred) or `input` (deprecated). Maximum 25,000 characters. Mutually exclusive with `workflow_id`.", "maxLength": 25000, "example": "Comprehensive analysis of CRISPR gene therapy clinical trials in 2024" }, "input": { "type": "string", "deprecated": true, "description": "**Deprecated.** Use `query` instead." }, "workflow_id": { "type": "string", "description": "**Beta.** Slug of a workflow to run instead of a freeform query. When set, the task is resolved from the workflow's prompt template using `workflow_params`. Mutually exclusive with freeform fields (`query`, `input`, `research_strategy`, `report_format`); supplying both returns `400 workflow_and_freeform_mutually_exclusive`. See the [Workflows](#tag/Workflows) endpoints.", "example": "ib-company-profile" }, "workflow_params": { "type": "object", "description": "**Beta.** Values for the workflow's template variables, keyed by variable `key`. Required when `workflow_id` is set. Values must satisfy the workflow's declared variable types and validation rules.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "example": { "company": "NVIDIA (NVDA)" } }, "workflow_version": { "type": "integer", "description": "**Beta.** Pin the run to a specific immutable version of the workflow. Defaults to the workflow's current version when omitted. Only valid with `workflow_id`.", "minimum": 1, "example": 1 }, "mode": { "type": "string", "description": "Research mode controlling depth and cost.\n\n| Mode | Price | Best For | Max Steps |\n| --- | --- | --- | --- |\n| `fast` | $0.10 | Quick queries, batch processing | 10 |\n| `standard` | $0.50 | Balanced research | 15 |\n| `heavy` | $2.50 | Complex topics requiring deep analysis | 15 |\n| `max` | $15.00 | Exhaustive research with maximum quality | 25 |", "enum": [ "fast", "standard", "heavy", "max" ], "default": "standard", "example": "standard" }, "model": { "type": "string", "deprecated": true, "description": "**Deprecated.** Use `mode` instead.", "enum": [ "fast", "standard", "heavy", "max" ] }, "strategy": { "type": "string", "deprecated": true, "description": "**Deprecated.** Use `research_strategy` instead. Natural language strategy to guide the research agent's approach.", "example": "Focus on Phase 3 trials and compare efficacy data across studies" }, "research_strategy": { "type": "string", "description": "Natural language strategy to guide the research phase. Controls how the agent searches, what sources to prioritize, and research methodology. Combined length of `research_strategy` and `report_format` must not exceed 15,000 characters.", "maxLength": 15000, "example": "Focus on Phase 3 trials and compare efficacy data across studies" }, "report_format": { "type": "string", "description": "Natural language instructions for the output format. Has highest priority and overrides default formatting. Controls structure, style, length, and presentation of the final report. Combined length of `research_strategy` and `report_format` must not exceed 15,000 characters.", "maxLength": 15000, "example": "Write a 2-page executive summary with bullet points and a comparison table" }, "search": { "$ref": "#/components/schemas/SearchConfig" }, "urls": { "type": "array", "description": "URLs to include in the research context. Max 10.", "items": { "type": "string", "format": "uri" }, "maxItems": 10, "example": [ "https://clinicaltrials.gov/study/NCT12345678" ] }, "files": { "type": "array", "description": "Files to analyze as part of the research. Max 10.", "items": { "$ref": "#/components/schemas/FileAttachment" }, "maxItems": 10 }, "output_formats": { "type": "array", "description": "Desired output formats. Defaults to `[\"markdown\"]`.\n\n- `\"markdown\"` - Markdown report (default)\n- `\"pdf\"` - PDF document (can combine with `\"markdown\"`)\n- `\"toon\"` - Token-efficient structured output; requires a JSON Schema object to also be supplied\n- JSON Schema object - Structured JSON output\n\nA JSON Schema object cannot be combined with `\"markdown\"` or `\"pdf\"`. `\"toon\"` requires a JSON Schema object.", "items": { "oneOf": [ { "type": "string", "enum": [ "markdown", "pdf", "toon" ] }, { "type": "object", "description": "JSON Schema for structured output." } ] }, "default": [ "markdown" ], "example": [ "markdown", "pdf" ] }, "metadata": { "type": "object", "description": "Arbitrary key-value metadata to attach to the task.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "example": { "project": "drug-discovery", "priority": "high" } }, "mcp_servers": { "type": "array", "description": "MCP servers to provide additional tools during research. Max 5.", "items": { "$ref": "#/components/schemas/MCPServerConfig" }, "maxItems": 5 }, "code_execution": { "type": "boolean", "description": "Deprecated: use tools.code_execution instead. Enable code execution capability.", "default": false, "deprecated": true }, "tools": { "type": "object", "description": "Controls which optional tools the research agent can use. Each tool accepts an object with `enabled` (boolean, default true) and optional `max_calls` (integer, capped at system default).", "properties": { "code_execution": { "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the tool." }, "max_calls": { "type": "integer", "description": "Max invocations per task. Capped at system default (10)." } } } ], "description": "Enable code execution in a sandboxed Python environment. System default max_calls: 10." }, "screenshots": { "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the tool." }, "max_calls": { "type": "integer", "description": "Max invocations per task. Capped at system default (15)." } } } ], "description": "Enable visual screenshot capture of web pages. System default max_calls: 15." }, "browser_use": { "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the tool." }, "max_calls": { "type": "integer", "description": "Max invocations per task. Capped at system default (5)." } } } ], "description": "Enable autonomous browser sessions. System default max_calls: 5." }, "charts": { "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the tool." }, "max_calls": { "type": "integer", "description": "Max invocations per task. Charts default is unlimited; this field is accepted for consistency." } } } ], "description": "Enable chart and graph generation embedded in the final report. Free, no per-call surcharge. Unlimited per task." } } }, "previous_reports": { "type": "array", "description": "DeepResearch task IDs to use as context for this task. Max 3.", "items": { "type": "string" }, "maxItems": 3, "example": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "webhook_url": { "type": "string", "format": "uri", "description": "HTTPS URL to receive a webhook POST when the task completes. Signed with HMAC-SHA256.", "example": "https://your-app.com/webhooks/deepresearch" }, "alert_email": { "oneOf": [ { "type": "string", "format": "email", "description": "Email address to notify on completion." }, { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email", "description": "Email address to notify on completion. Must belong to your organization." }, "custom_url": { "type": "string", "format": "uri", "description": "Custom URL template for the report link in the email. Must contain {id} which gets replaced with the deepresearch task ID.", "example": "https://your-app.com/reports/{id}" } } } ], "description": "Email notification on completion. Pass a string (email address) or an object with email and optional custom_url. The custom_url must contain {id} which gets replaced with the task ID. Email must belong to your organization." }, "deliverables": { "type": "array", "description": "Deliverable files to generate from the research (e.g. Excel reports, presentations). Max 10.", "items": { "description": "A deliverable to generate from the research. Can be a string (natural language description, max 500 chars) or a structured object.", "oneOf": [ { "type": "string", "maxLength": 500, "description": "Natural language description of the deliverable." }, { "type": "object", "required": [ "type", "description" ], "properties": { "type": { "type": "string", "enum": [ "csv", "xlsx", "pptx", "docx", "pdf" ], "description": "File format for the deliverable." }, "description": { "type": "string", "maxLength": 500, "description": "Description of what the deliverable should contain." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Suggested column names for tabular deliverables (csv, xlsx)." }, "schema": { "type": "object", "description": "JSON Schema for structured deliverables." } } } ] }, "maxItems": 10 }, "hitl": { "type": "object", "description": "Human-in-the-loop configuration. Enable checkpoints that pause execution at key decision points. Not available for batch requests.", "properties": { "planning_questions": { "type": "boolean", "description": "Pause before research to ask clarifying questions.", "default": false }, "plan_review": { "type": "boolean", "description": "Pause after planning for user to review the research plan.", "default": false }, "source_review": { "type": "boolean", "description": "Pause after research for user to filter sources by domain.", "default": false }, "outline_review": { "type": "boolean", "description": "Pause after source review for user to review the report outline.", "default": false } } } } }, "DeepResearchCreateResponse": { "type": "object", "description": "Response after creating a DeepResearch task.", "required": [ "deepresearch_id", "status", "mode", "created_at" ], "properties": { "deepresearch_id": { "type": "string", "description": "Unique identifier for the research task.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "status": { "type": "string", "description": "Initial task status. `\"running\"` if started immediately, `\"queued\"` if waiting for capacity.", "enum": [ "running", "queued" ], "example": "running" }, "mode": { "type": "string", "description": "Research mode used for this task.", "enum": [ "fast", "standard", "heavy", "max" ], "example": "standard" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of task creation.", "example": "2024-06-15T10:30:00.000Z" }, "metadata": { "type": "object", "description": "Metadata attached to the task.", "additionalProperties": true }, "public": { "type": "boolean", "description": "Whether the task is publicly accessible.", "example": false }, "webhook_secret": { "type": "string", "description": "HMAC-SHA256 secret for verifying webhook payloads. Only present when `webhook_url` was provided." }, "message": { "type": "string", "description": "Status message. Present when task is queued." } } }, "DeepResearchSource": { "type": "object", "description": "A source used during research.", "properties": { "title": { "type": "string", "description": "Title of the source document.", "example": "CRISPR Gene Therapy: A Comprehensive Review" }, "url": { "type": "string", "format": "uri", "description": "URL of the source.", "example": "https://pubmed.ncbi.nlm.nih.gov/12345678/" }, "snippet": { "type": "string", "description": "Relevant text excerpt from the source." }, "description": { "type": "string", "description": "Brief description or snippet from the source." }, "source": { "type": "string", "description": "Source identifier." }, "price": { "type": "number", "description": "Cost in USD for accessing this source." }, "doi": { "type": "string", "description": "DOI identifier (academic sources)." }, "word_count": { "type": "integer", "description": "Word count of the source document." }, "fragment": { "type": "string", "description": "Optional URL fragment that, when appended to `url`, produces a deep-link to the cited passage on the source page. For HTML sources this is a Scroll-to-Text-Fragment directive (`#:~:text=...`); for PDF sources it uses PDF Open Parameters (`#page=N&search=...`). Build deep-links by concatenating `url + fragment`. Omitted when no reliable highlight target is available — clients should fall back to the canonical `url` in that case.", "example": "#:~:text=Revenue%20grew%2040%25%20to%20%245.2B" } } }, "DeepResearchImage": { "type": "object", "description": "An image generated during research (chart, AI-generated, or screenshot).", "required": [ "image_id", "image_type", "title", "image_url", "created_at" ], "properties": { "image_id": { "type": "string", "description": "Unique image identifier.", "example": "img_a1b2c3d4e5f6" }, "image_type": { "type": "string", "enum": [ "chart", "ai_generated", "screenshot" ], "description": "Type of image.", "example": "chart" }, "title": { "type": "string", "description": "Image title.", "example": "Clinical Trial Phase Distribution" }, "description": { "type": "string", "description": "Image description.", "example": "Bar chart showing distribution of CRISPR trials across phases" }, "image_url": { "type": "string", "format": "uri", "description": "URL to access the image.", "example": "https://storage.valyu.ai/images/img_a1b2c3d4e5f6.png" }, "created_at": { "type": "integer", "description": "Unix timestamp (milliseconds) of image creation.", "example": 1718444520000 }, "source_url": { "type": "string", "format": "uri", "description": "Original web page URL. Only present when `image_type` is `\"screenshot\"`.", "example": "https://example.com/dashboard" }, "captured_at": { "type": "integer", "description": "Unix timestamp (milliseconds) when the screenshot was taken. Only present when `image_type` is `\"screenshot\"`.", "example": 1718444520000 }, "chart_type": { "type": "string", "enum": [ "line", "bar", "area", "pie", "doughnut", "radar", "scatter", "horizontalBar", "heatmap", "boxplot", "stackedBar", "stackedArea", "histogram", "waterfall", "timeline", "bubble" ], "description": "Chart type. Only present when `image_type` is `\"chart\"`.", "example": "bar" }, "x_axis_label": { "type": "string", "description": "X-axis label. Only present for chart images.", "example": "Trial Phase" }, "y_axis_label": { "type": "string", "description": "Y-axis label. Only present for chart images.", "example": "Number of Trials" }, "data_series": { "type": "array", "description": "Chart data series. Only present when `image_type` is `\"chart\"`.", "items": { "type": "object", "required": ["name", "data"], "properties": { "name": { "type": "string", "description": "Series name shown in the legend." }, "data": { "type": "array", "items": { "type": "object", "required": ["x", "y"], "properties": { "x": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "X-axis value (category or numeric)." }, "y": { "type": "number", "description": "Y-axis value." }, "y2": { "type": "number", "description": "End value for `timeline` charts (y = start epoch ms, y2 = end epoch ms)." }, "z": { "type": "number", "description": "Bubble size for `bubble` charts." }, "values": { "type": "array", "items": { "type": "number" }, "description": "Raw data points for `boxplot` charts (library computes quartiles)." } } } }, "line_style": { "type": "string", "enum": ["solid", "dashed", "dotted"], "description": "Line style override for `line`/`area` charts." } } } } } }, "DeepResearchDeliverableResult": { "type": "object", "description": "A generated deliverable file from a DeepResearch task.", "required": [ "id", "request", "type", "status", "title", "url", "s3_key", "created_at" ], "properties": { "id": { "type": "string", "description": "Unique deliverable identifier.", "example": "del_a1b2c3d4e5f6" }, "request": { "type": "string", "description": "Original deliverable request description.", "example": "Extract all company names, founding years, and revenue data into a spreadsheet" }, "type": { "type": "string", "enum": [ "csv", "xlsx", "pptx", "docx", "pdf", "unknown" ], "description": "Deliverable file type.", "example": "xlsx" }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Generation status.", "example": "completed" }, "title": { "type": "string", "description": "Generated filename or title.", "example": "company_data.xlsx" }, "description": { "type": "string", "description": "Description of the deliverable content.", "example": "Spreadsheet containing 25 companies with founding years and revenue data" }, "url": { "type": "string", "format": "uri", "description": "Token-signed URL to download the file.", "example": "https://storage.valyu.ai/deliverables/del_a1b2c3d4e5f6.xlsx?token=..." }, "s3_key": { "type": "string", "description": "S3 storage key.", "example": "deliverables/org_123/del_a1b2c3d4e5f6.xlsx" }, "row_count": { "type": "integer", "description": "Number of rows. Only present for CSV/XLSX.", "example": 25 }, "column_count": { "type": "integer", "description": "Number of columns. Only present for CSV/XLSX.", "example": 5 }, "error": { "type": "string", "description": "Error message. Only present when `status` is `\"failed\"`." }, "created_at": { "type": "integer", "description": "Unix timestamp (milliseconds) of creation.", "example": 1718444640000 } } }, "DeepResearchStatusResponse": { "type": "object", "description": "Full status and results of a DeepResearch task.", "required": [ "deepresearch_id", "status", "query", "mode", "created_at" ], "properties": { "deepresearch_id": { "type": "string", "description": "Unique identifier for the research task.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "status": { "type": "string", "description": "Current task status.\n\n- `queued` - Waiting for capacity\n- `running` - Research in progress\n- `awaiting_input` - HITL checkpoint active, waiting for user response\n- `paused` - HITL checkpoint timed out, state saved, respond anytime to resume\n- `completed` - Research finished successfully\n- `failed` - Research failed\n- `cancelled` - Task was cancelled", "enum": [ "queued", "running", "awaiting_input", "paused", "completed", "failed", "cancelled" ], "example": "completed" }, "query": { "type": "string", "description": "The original research query.", "example": "Comprehensive analysis of CRISPR gene therapy clinical trials" }, "mode": { "type": "string", "description": "Research mode used for this task.", "enum": [ "fast", "standard", "heavy", "max" ], "example": "standard" }, "output_formats": { "type": "array", "description": "Output formats requested for this task.", "items": { "oneOf": [ { "type": "string", "enum": [ "markdown", "pdf", "toon" ] }, { "type": "object" } ] }, "example": [ "markdown", "pdf" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of task creation.", "example": "2024-06-15T10:30:00.000Z" }, "public": { "type": "boolean", "description": "Whether the task results are publicly accessible.", "example": false }, "batch_id": { "type": "string", "description": "Batch ID if this task belongs to a batch." }, "batch_task_id": { "type": "string", "description": "User-provided task ID within a batch." }, "progress": { "type": "object", "description": "Research progress. Present when `status` is `\"running\"`.", "properties": { "current_step": { "type": "integer", "example": 5 }, "total_steps": { "type": "integer", "example": 15 } } }, "output_type": { "type": "string", "description": "Format of the output. Present when `status` is `\"completed\"`.", "enum": [ "markdown", "json", "toon" ], "example": "markdown" }, "output": { "description": "Research output. Markdown string or JSON object depending on `output_type`. Present when `status` is `\"completed\"` (may be partial on `\"failed\"` or `\"cancelled\"`).", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "sources": { "type": "array", "description": "Sources used during research. Present when `status` is `\"completed\"`, `\"failed\"`, or `\"cancelled\"`.", "items": { "$ref": "#/components/schemas/DeepResearchSource" } }, "cost": { "type": "number", "description": "Total cost billed for this task in USD (base mode price + any tool surcharges).", "example": 0.5 }, "cost_breakdown": { "type": "object", "description": "Itemized cost breakdown. Only present when the task has completed.", "properties": { "task": { "type": "number", "description": "Base task price for the selected mode." }, "screenshots": { "type": "number", "description": "Screenshot surcharges ($0.05 per URL captured). Omitted if 0." }, "code_execution": { "type": "number", "description": "Code execution surcharges ($0.10 per execution). Omitted if 0." }, "deliverables": { "type": "number", "description": "Deliverable surcharges ($0.10 per deliverable after the first). Omitted if 0." } }, "required": ["task"] }, "tools": { "type": "object", "description": "Resolved tools configuration for this task.", "properties": { "code_execution": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "max_calls": { "type": "integer" } }, "description": "Code execution configuration." }, "screenshots": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "max_calls": { "type": "integer" } }, "description": "Screenshots configuration." }, "browser_use": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "max_calls": { "type": "integer" } }, "description": "Browser use configuration." }, "charts": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "max_calls": { "type": "integer" } }, "description": "Chart generation configuration." } } }, "completed_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of task completion. Present when `status` is `\"completed\"`.", "example": "2024-06-15T10:35:00.000Z" }, "pdf_url": { "type": "string", "format": "uri", "description": "URL to the generated PDF report. Present when `\"pdf\"` was in `output_formats`." }, "images": { "type": "array", "description": "Images generated during research (charts, AI-generated, screenshots). Present when `status` is `\"completed\"`.", "items": { "$ref": "#/components/schemas/DeepResearchImage" } }, "deliverables": { "type": "array", "description": "Generated deliverable files (CSV, Excel, PowerPoint, Word, PDF). Present when deliverables were requested.", "items": { "$ref": "#/components/schemas/DeepResearchDeliverableResult" } }, "messages": { "type": "array", "description": "Conversation trace of the research agent. Present when `status` is `\"running\"` or `\"completed\"`.", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } } } }, "error": { "type": "string", "description": "Error message. Present when `status` is `\"failed\"`." }, "hitl_config": { "type": "object", "description": "HITL configuration. Present when HITL was enabled on task creation.", "properties": { "planning_questions": { "type": "boolean" }, "plan_review": { "type": "boolean" }, "source_review": { "type": "boolean" }, "outline_review": { "type": "boolean" } } }, "interaction": { "type": "object", "description": "Current HITL checkpoint. Present when status is `awaiting_input` or `paused`.", "properties": { "interaction_id": { "type": "string", "description": "Unique ID for this interaction. Pass this when responding." }, "type": { "type": "string", "description": "Checkpoint type.", "enum": ["planning_questions", "plan_review", "source_review", "outline_review"] }, "data": { "description": "Checkpoint-specific data — shape depends on `type`.", "oneOf": [ { "$ref": "#/components/schemas/HitlPlanningQuestionsData" }, { "$ref": "#/components/schemas/HitlPlanReviewData" }, { "$ref": "#/components/schemas/HitlSourceReviewData" }, { "$ref": "#/components/schemas/HitlOutlineReviewData" } ] }, "created_at": { "type": "integer", "description": "Unix timestamp (ms) when the checkpoint fired." }, "timeout_ms": { "type": "integer", "description": "Timeout duration in milliseconds (default 300000 = 5 minutes)." }, "expected_response": { "type": "object", "description": "Schema hint for the expected response shape.", "additionalProperties": true } } }, "hitl_history": { "type": "array", "description": "History of completed HITL checkpoints. Present after any checkpoint completes.", "items": { "type": "object", "properties": { "interaction_id": { "type": "string" }, "type": { "type": "string", "enum": ["planning_questions", "plan_review", "source_review", "outline_review"] }, "created_at": { "type": "integer", "description": "When the checkpoint fired (ms)." }, "responded_at": { "type": "integer", "description": "When the user responded (ms). Absent if timed out." }, "auto_continued": { "type": "boolean", "description": "True if timed out, false if user responded." }, "response": { "type": "object", "description": "The user's response. Absent if timed out.", "additionalProperties": true } } } } } }, "DeepResearchListItem": { "type": "object", "description": "Summary of a DeepResearch task in list view.", "required": [ "deepresearch_id", "query", "status", "created_at" ], "properties": { "deepresearch_id": { "type": "string", "description": "Unique identifier for the research task.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "query": { "type": "string", "description": "The original research query.", "example": "CRISPR gene therapy clinical trials" }, "status": { "type": "string", "description": "Current task status.", "enum": [ "queued", "running", "completed", "failed", "cancelled" ], "example": "completed" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of task creation.", "example": "2024-06-15T10:30:00.000Z" }, "public": { "type": "boolean", "description": "Whether the task results are publicly accessible.", "example": false } } }, "DeepResearchUpdateRequest": { "type": "object", "required": [ "instruction" ], "additionalProperties": false, "description": "Follow-up instruction to guide a running research task. Can only be sent before the writing phase begins.", "properties": { "instruction": { "type": "string", "description": "Follow-up instruction for the research agent.", "example": "Also compare the safety profiles across all trials" } } }, "DeepResearchUpdateResponse": { "type": "object", "required": [ "success", "message", "deepresearch_id" ], "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded.", "example": true }, "message": { "type": "string", "description": "Human-readable status message.", "example": "Instruction added" }, "deepresearch_id": { "type": "string", "description": "ID of the affected task.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "DeepResearchCancelResponse": { "type": "object", "required": [ "success", "message", "deepresearch_id" ], "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded.", "example": true }, "message": { "type": "string", "description": "Human-readable status message.", "example": "Task cancelled" }, "deepresearch_id": { "type": "string", "description": "ID of the affected task.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "DeepResearchDeleteResponse": { "type": "object", "required": [ "success", "message", "deepresearch_id" ], "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded.", "example": true }, "message": { "type": "string", "description": "Human-readable status message.", "example": "Task deleted successfully" }, "deepresearch_id": { "type": "string", "description": "ID of the affected task.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "DeepResearchTogglePublicRequest": { "type": "object", "required": [ "public" ], "additionalProperties": false, "description": "Request to toggle the public visibility of a DeepResearch task.", "properties": { "public": { "type": "boolean", "description": "Set to `true` to make the task publicly accessible, or `false` to make it private.", "example": true } } }, "DeepResearchTogglePublicResponse": { "type": "object", "required": [ "success", "message", "deepresearch_id", "public" ], "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded.", "example": true }, "message": { "type": "string", "description": "Human-readable status message.", "example": "Public flag updated" }, "deepresearch_id": { "type": "string", "description": "ID of the affected task.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "public": { "type": "boolean", "description": "The updated public visibility status.", "example": true } } }, "BatchCounts": { "type": "object", "description": "Task count breakdown for a batch.", "required": [ "total", "queued", "running", "completed", "failed", "cancelled" ], "properties": { "total": { "type": "integer", "description": "Total number of tasks in the batch.", "example": 10 }, "queued": { "type": "integer", "description": "Tasks waiting to start.", "example": 3 }, "running": { "type": "integer", "description": "Tasks currently executing.", "example": 2 }, "completed": { "type": "integer", "description": "Tasks that finished successfully.", "example": 4 }, "failed": { "type": "integer", "description": "Tasks that encountered errors.", "example": 1 }, "cancelled": { "type": "integer", "description": "Tasks that were cancelled.", "example": 0 } } }, "CreateBatchRequest": { "type": "object", "additionalProperties": false, "description": "Create a new batch for running multiple DeepResearch tasks with shared configuration.", "properties": { "name": { "type": "string", "description": "Optional name for the batch.", "example": "Q4 Earnings Analysis Batch" }, "mode": { "type": "string", "description": "Research mode applied to all tasks in the batch.", "enum": [ "fast", "standard", "heavy", "max" ], "default": "standard" }, "model": { "type": "string", "deprecated": true, "description": "**Deprecated.** Use `mode` instead.", "enum": [ "fast", "standard", "heavy", "max" ] }, "output_formats": { "type": "array", "description": "Output formats applied to all tasks.", "items": { "oneOf": [ { "type": "string", "enum": [ "markdown", "pdf" ] }, { "type": "object" } ] }, "default": [ "markdown" ] }, "search": { "$ref": "#/components/schemas/SearchConfig" }, "webhook_url": { "type": "string", "format": "uri", "description": "HTTPS URL to receive a webhook when all tasks complete." }, "metadata": { "type": "object", "description": "Arbitrary key-value metadata.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } } }, "BatchResponse": { "type": "object", "description": "Batch status and metadata.", "required": [ "batch_id", "status", "mode", "created_at", "counts", "cost" ], "properties": { "batch_id": { "type": "string", "description": "Unique batch identifier.", "example": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "status": { "type": "string", "description": "Batch lifecycle status.\n\n- `open` - Batch created, accepting tasks\n- `processing` - Tasks are running\n- `completed` - All tasks finished successfully\n- `completed_with_errors` - All tasks finished, some failed\n- `cancelled` - Batch was cancelled", "enum": [ "open", "processing", "completed", "completed_with_errors", "cancelled" ], "example": "processing" }, "mode": { "type": "string", "description": "Research mode for all tasks in this batch.", "enum": [ "fast", "standard", "heavy", "max" ], "example": "standard" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of batch creation.", "example": "2024-06-15T10:30:00.000Z" }, "name": { "type": "string", "description": "Human-readable name for the batch.", "example": "Q4 Earnings Analysis Batch" }, "output_formats": { "type": "array", "description": "Output formats configured for all tasks.", "items": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "example": [ "markdown" ] }, "search_params": { "type": "object", "description": "Shared search configuration." }, "counts": { "$ref": "#/components/schemas/BatchCounts" }, "cost": { "type": "number", "description": "Aggregated cost in USD across all tasks.", "example": 5.0 }, "completed_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp. Present when batch is completed." }, "webhook_secret": { "type": "string", "description": "HMAC-SHA256 secret. Only present on creation when `webhook_url` was provided." } } }, "BatchTaskInput": { "type": "object", "required": [ "query" ], "description": "A task to add to a batch.", "properties": { "query": { "type": "string", "description": "The research query. Use `query` (preferred) or `input` (deprecated).", "example": "Analyze Tesla Q4 2024 earnings and forward guidance" }, "input": { "type": "string", "deprecated": true, "description": "**Deprecated.** Use `query` instead." }, "id": { "type": "string", "description": "User-provided task identifier within the batch for your own tracking.", "example": "task-tesla-q4" }, "strategy": { "type": "string", "deprecated": true, "description": "**Deprecated.** Use `research_strategy` instead." }, "research_strategy": { "type": "string", "description": "Natural language strategy to guide the research phase for this task." }, "report_format": { "type": "string", "description": "Natural language instructions for the output format of this task." }, "urls": { "type": "array", "description": "URLs to include in research context.", "items": { "type": "string", "format": "uri" } }, "metadata": { "type": "object", "description": "Arbitrary metadata for this task.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } } }, "AddBatchTasksRequest": { "type": "object", "required": [ "tasks" ], "additionalProperties": false, "description": "Add tasks to an existing batch.", "properties": { "tasks": { "type": "array", "description": "Tasks to add. Max 100 per request.", "items": { "$ref": "#/components/schemas/BatchTaskInput" }, "minItems": 1, "maxItems": 100 } } }, "AddBatchTasksResponse": { "type": "object", "required": [ "batch_id", "added", "tasks", "counts" ], "properties": { "batch_id": { "type": "string", "description": "ID of the batch.", "example": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "added": { "type": "integer", "description": "Number of tasks added.", "example": 5 }, "tasks": { "type": "array", "description": "Created tasks with their assigned IDs.", "items": { "type": "object", "properties": { "task_id": { "type": "string", "description": "User-provided task ID." }, "deepresearch_id": { "type": "string", "description": "System-generated task UUID." }, "status": { "type": "string", "enum": [ "queued" ], "example": "queued" } } } }, "counts": { "$ref": "#/components/schemas/BatchCounts" } } }, "BatchTask": { "type": "object", "description": "A task within a batch. When `include_output=true` is passed to the list tasks endpoint, additional fields (output_type, output, sources, images, pdf_url, deliverables, error, cost) are included.", "required": [ "deepresearch_id", "status", "query", "created_at" ], "properties": { "task_id": { "type": "string", "description": "User-provided task ID within the batch." }, "deepresearch_id": { "type": "string", "description": "Unique ID for the research task.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "status": { "type": "string", "description": "Current task status.", "enum": [ "queued", "running", "completed", "failed", "cancelled" ], "example": "completed" }, "query": { "type": "string", "description": "The research query for this task.", "example": "Analyze Tesla Q4 2024 earnings" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of task creation.", "example": "2024-06-15T10:30:00.000Z" }, "completed_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of task completion. Only present when task is done." }, "output_type": { "type": "string", "enum": ["markdown", "json", "toon"], "description": "Format of the output. Only present when `include_output=true` and task is completed." }, "output": { "description": "Research output. Markdown string, parsed JSON object, or null. Only present when `include_output=true`.", "example": "## Tesla Q4 2025 Earnings Analysis\n\n..." }, "sources": { "type": "array", "description": "Sources cited in the research output. Only present when `include_output=true` and task is completed.", "items": { "type": "object" } }, "images": { "type": "array", "description": "Charts and images generated during research. Only present when `include_output=true` and task produced images.", "items": { "type": "object" } }, "pdf_url": { "type": "string", "description": "URL to the PDF version of the report. Only present when `include_output=true` and PDF output was requested.", "example": "https://api.valyu.ai/v1/deepresearch/tasks/52fafd51/pdf" }, "deliverables": { "type": "array", "description": "Generated deliverables (XLSX, PPTX, DOCX). Only present when `include_output=true` and deliverables were produced.", "items": { "type": "object" } }, "error": { "type": "string", "nullable": true, "description": "Error message. Only present when `include_output=true` for failed tasks.", "example": "Task exceeded maximum execution time" }, "cost": { "type": "number", "description": "Cost of this task in USD. Only present when `include_output=true`.", "example": 1.0 } } }, "BatchTaskListResponse": { "type": "object", "required": [ "batch_id", "tasks", "pagination" ], "properties": { "batch_id": { "type": "string", "description": "ID of the batch these tasks belong to.", "example": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "tasks": { "type": "array", "description": "Array of tasks in the batch.", "items": { "$ref": "#/components/schemas/BatchTask" } }, "pagination": { "description": "Pagination metadata.", "type": "object", "required": [ "count", "has_more" ], "properties": { "count": { "type": "integer", "description": "Number of tasks returned.", "example": 10 }, "last_key": { "type": "string", "nullable": true, "description": "Cursor for the next page. Pass as `last_key` query parameter. `null` if no more results." }, "has_more": { "type": "boolean", "example": false } } } } }, "CancelBatchResponse": { "type": "object", "required": [ "batch_id", "status", "cancelled_count" ], "properties": { "batch_id": { "type": "string", "description": "ID of the cancelled batch.", "example": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "status": { "type": "string", "description": "Batch status after cancellation.", "enum": [ "cancelled" ], "example": "cancelled" }, "cancelled_count": { "type": "integer", "description": "Number of tasks cancelled.", "example": 3 } } }, "BatchUsage": { "type": "object", "description": "Aggregated cost breakdown for a batch.", "properties": { "search_cost": { "type": "number", "description": "Total search operation cost in USD.", "example": 1.5 }, "contents_cost": { "type": "number", "description": "Total content extraction cost in USD.", "example": 0.25 }, "ai_cost": { "type": "number", "description": "Total AI processing cost in USD.", "example": 3.0 }, "total_cost": { "type": "number", "description": "Total cost across all operations in USD.", "example": 4.75 } } }, "Datasource": { "type": "object", "description": "A data source available through Valyu's search API.", "required": [ "id", "name", "description", "category" ], "properties": { "id": { "type": "string", "description": "Unique datasource identifier.", "example": "valyu/valyu-arxiv" }, "name": { "type": "string", "description": "Display name of the datasource.", "example": "arXiv" }, "description": { "type": "string", "description": "What data this source provides.", "example": "Preprints in physics, mathematics, computer science, and more." }, "category": { "type": "string", "description": "Category classification.", "enum": [ "research", "healthcare", "patents", "markets", "company", "economic", "predictions", "transportation", "legal", "politics" ], "example": "research" }, "type": { "type": "string", "description": "Content type (e.g. paper, data, report).", "example": "paper" }, "topics": { "type": "array", "description": "Subject areas covered by this datasource.", "items": { "type": "string" }, "example": [ "physics", "mathematics", "computer science" ] }, "languages": { "type": "array", "description": "Languages supported by this datasource.", "items": { "type": "string" }, "example": [ "en", "es", "fr" ] }, "source": { "type": "string", "description": "Source provider or origin of the datasource.", "example": "pubmed" }, "modality": { "type": "array", "items": { "type": "string" }, "description": "Data modalities available (e.g. text, images, tabular).", "example": [ "text" ] }, "example_queries": { "type": "array", "description": "Example queries optimized for few-shot prompting.", "items": { "type": "string" }, "example": [ "CRISPR gene editing mechanisms", "quantum error correction methods" ] }, "pricing": { "type": "object", "description": "Cost information for this datasource.", "properties": { "cpm": { "type": "number", "description": "Cost per mille (thousand) tokens.", "example": 0.5 } } }, "response_schema": { "type": "object", "description": "JSON Schema describing the response format for results from this source.", "additionalProperties": true }, "update_frequency": { "type": "string", "description": "How often the data is updated (Realtime, Daily, Monthly).", "example": "daily" }, "size": { "type": "integer", "description": "Approximate number of records or documents.", "example": 2500000 }, "coverage": { "type": "object", "description": "Temporal coverage of the data.", "properties": { "start_date": { "type": "string", "format": "date-time", "description": "Earliest data available." }, "end_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest data available. `null` if continuously updated." } } }, "geography": { "type": "object", "description": "Geographic coverage information, if available.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Search capabilities supported by this datasource.", "additionalProperties": true }, "data_source": { "type": "object", "description": "Data provider information.", "properties": { "provider": { "type": "string" }, "license": { "type": "string" } } } } }, "DatasourceCategory": { "type": "object", "description": "A category of data sources.", "required": [ "id", "name", "description" ], "properties": { "id": { "type": "string", "description": "Unique category identifier.", "example": "research" }, "name": { "type": "string", "description": "Display name of the category.", "example": "Research" }, "description": { "type": "string", "description": "What this category covers.", "example": "Academic papers, preprints, and scholarly articles." }, "dataset_count": { "type": "integer", "description": "Number of datasets in this category.", "example": 8 } } }, "DatasourcesResponse": { "type": "object", "required": [ "success", "datasources" ], "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded.", "example": true }, "datasources": { "type": "array", "items": { "$ref": "#/components/schemas/Datasource" }, "description": "List of available datasources." }, "total_count": { "type": "integer", "description": "Total number of datasources returned.", "example": 36 }, "categories": { "type": "object", "description": "Summary of categories with counts.", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "count": { "type": "integer" } } } } } }, "DatasourceCategoriesResponse": { "type": "object", "required": [ "success", "categories" ], "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded.", "example": true }, "categories": { "type": "array", "description": "Array of available datasource categories.", "items": { "$ref": "#/components/schemas/DatasourceCategory" } } } }, "DatasourceSearchResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "query": { "type": "string", "description": "The query as interpreted." }, "search_mode": { "type": "string", "enum": [ "semantic", "lexical" ], "description": "`semantic` when embedding-based ranking was used; `lexical` when the full-text fallback served the request." }, "total_count": { "type": "integer" }, "results": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Datasource" }, { "type": "object", "properties": { "relevance_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Ranking score, best-first." } } } ] } } } }, "HitlPlanningQuestionsData": { "type": "object", "title": "Planning Questions Data", "description": "Interaction data for the `planning_questions` checkpoint. Contains clarifying questions the agent wants answered before starting research.", "required": ["questions"], "properties": { "questions": { "type": "array", "description": "List of clarifying questions.", "items": { "type": "object", "required": ["question"], "properties": { "question": { "type": "string", "description": "The question text.", "example": "What geographic regions should the research focus on?" }, "context": { "type": "string", "description": "Optional context explaining why this question matters.", "example": "The query mentions global markets — narrowing scope improves depth" } } } } } }, "HitlPlanReviewData": { "type": "object", "title": "Plan Review Data", "description": "Interaction data for the `plan_review` checkpoint. Contains the research plan for user approval.", "required": ["plan"], "properties": { "plan": { "type": "string", "description": "The proposed research plan.", "example": "I'll research this topic by first examining market size data, then analyzing the competitive landscape..." }, "estimated_steps": { "type": "integer", "description": "Estimated number of research steps.", "example": 15 }, "research_areas": { "type": "array", "description": "Key areas the research will cover.", "items": { "type": "string" }, "example": ["Market size analysis", "Competitive landscape", "Regulatory environment"] } } }, "HitlSourceReviewData": { "type": "object", "title": "Source Review Data", "description": "Interaction data for the `source_review` checkpoint. Contains sources grouped by domain for user filtering.", "required": ["domains", "total_sources"], "properties": { "domains": { "type": "array", "description": "Sources grouped by domain.", "items": { "type": "object", "required": ["domain", "source_count", "avg_relevance_score", "sources", "ai_recommendation"], "properties": { "domain": { "type": "string", "description": "Domain name.", "example": "sec.gov" }, "source_count": { "type": "integer", "description": "Number of sources from this domain.", "example": 8 }, "avg_relevance_score": { "type": "number", "description": "Average relevance score (0-1).", "example": 0.87 }, "sources": { "type": "array", "description": "Individual sources from this domain.", "items": { "type": "object", "properties": { "source_id": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "relevance_score": { "type": "number" } } } }, "ai_recommendation": { "type": "string", "description": "AI's recommendation for this domain.", "enum": ["include", "exclude"], "example": "include" } } } }, "total_sources": { "type": "integer", "description": "Total number of sources across all domains.", "example": 42 } } }, "HitlOutlineReviewData": { "type": "object", "title": "Outline Review Data", "description": "Interaction data for the `outline_review` checkpoint. Contains the report outline for user approval.", "required": ["outline", "sections"], "properties": { "outline": { "type": "string", "description": "The full outline as text.", "example": "1. Introduction\n2. Market Analysis\n3. Competitive Landscape\n4. Conclusion" }, "sections": { "type": "array", "description": "Structured list of sections.", "items": { "type": "object", "required": ["title", "description"], "properties": { "title": { "type": "string", "description": "Section title.", "example": "Market Analysis" }, "description": { "type": "string", "description": "What this section covers.", "example": "Detailed market size and growth analysis" }, "estimated_length": { "type": "string", "description": "Expected length of this section.", "enum": ["short", "medium", "long"], "example": "long" } } } } } }, "HitlPlanningQuestionsResponse": { "type": "object", "title": "Planning Questions Response", "description": "Response shape for the `planning_questions` checkpoint. Provide answers to each clarifying question.", "required": ["answers"], "properties": { "answers": { "type": "array", "description": "Answers to each question.", "items": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string", "description": "The original question text.", "example": "What geographic regions should the research focus on?" }, "answer": { "type": "string", "description": "Your answer.", "example": "North America and EU" } } } } } }, "HitlPlanReviewResponse": { "type": "object", "title": "Plan Review Response", "description": "Response shape for the `plan_review` checkpoint. Approve the plan or request modifications.", "required": ["approved"], "properties": { "approved": { "type": "boolean", "description": "Whether to approve the plan.", "example": true }, "modifications": { "type": "string", "description": "Free-text guidance for the model. Only used when `approved` is `false`.", "example": "Focus more on battery supply chains and less on historical context" } } }, "HitlSourceReviewResponse": { "type": "object", "title": "Source Review Response", "description": "Response shape for the `source_review` checkpoint. Specify which domains to include or exclude. Domains not listed in either array fall back to the AI recommendation.", "required": ["included_domains", "excluded_domains"], "properties": { "included_domains": { "type": "array", "description": "Domains to include. Pass empty `[]` to accept all AI recommendations.", "items": { "type": "string" }, "example": ["sec.gov", "plos.org"] }, "excluded_domains": { "type": "array", "description": "Domains to exclude. Pass empty `[]` to not exclude any.", "items": { "type": "string" }, "example": ["example.com"] } } }, "HitlOutlineReviewResponse": { "type": "object", "title": "Outline Review Response", "description": "Response shape for the `outline_review` checkpoint. Approve the outline or request modifications.", "required": ["approved"], "properties": { "approved": { "type": "boolean", "description": "Whether to approve the outline.", "example": true }, "modifications": { "type": "string", "description": "Free-text guidance for the model. Only used when `approved` is `false`.", "example": "Add a section on regulatory risks between Market Analysis and Competitive Landscape" } } }, "WorkflowMode": { "type": "string", "description": "Recommended DeepResearch mode for a workflow. Maps directly to the DeepResearch `mode` parameter.", "enum": [ "fast", "standard", "heavy", "max" ], "example": "heavy" }, "WorkflowVariableType": { "type": "string", "description": "Input type for a workflow template variable. Controls how the variable is rendered and validated.", "enum": [ "text", "textarea", "number", "date", "enum" ], "example": "text" }, "WorkflowVariable": { "type": "object", "description": "A typed variable referenced by `{key}` placeholders in the workflow prompt template.", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "description": "Unique key for the variable. Used as the `{key}` placeholder in the template and as the field name in `workflow_params`.", "example": "company" }, "label": { "type": "string", "description": "Human-readable label for the variable.", "example": "Company name" }, "type": { "$ref": "#/components/schemas/WorkflowVariableType" }, "required": { "type": "boolean", "description": "Whether a value must be supplied for this variable.", "default": false }, "placeholder": { "type": "string", "description": "Placeholder text shown in the input field.", "example": "NVIDIA (NVDA)" }, "help": { "type": "string", "description": "Help text explaining what to enter.", "example": "The company you want to profile." }, "examples": { "type": "array", "description": "Example values for the variable.", "items": { "type": "string" }, "example": ["NVIDIA (NVDA)", "Microsoft (MSFT)"] }, "validation": { "type": "object", "description": "Validation rules applied to the variable's value.", "properties": { "min_length": { "type": "integer", "description": "Minimum string length.", "minimum": 0 }, "max_length": { "type": "integer", "description": "Maximum string length.", "minimum": 1 }, "pattern": { "type": "string", "description": "Regular expression the value must match." }, "enum": { "type": "array", "description": "Allowed values when `type` is `enum`.", "items": { "type": "string" } } } } } }, "WorkflowDeliverable": { "type": "object", "description": "A deliverable file the workflow produces.", "required": [ "type", "description" ], "properties": { "type": { "type": "string", "description": "File format for the deliverable.", "enum": [ "csv", "xlsx", "pptx", "docx", "pdf" ], "example": "xlsx" }, "description": { "type": "string", "description": "What the deliverable should contain.", "example": "A model summary tab with revenue, margins, and key ratios." } } }, "WorkflowTools": { "type": "object", "description": "Optional tools the workflow's research agent may use.", "properties": { "code_execution": { "type": "boolean", "description": "Enable code execution in a sandboxed environment." }, "screenshots": { "type": "boolean", "description": "Enable visual screenshot capture of web pages." }, "browser_use": { "type": "boolean", "description": "Enable autonomous browser sessions." }, "charts": { "type": "boolean", "description": "Enable chart and graph generation in the report." } } }, "WorkflowOutputFormats": { "type": "array", "description": "Output formats the workflow produces. Items are the strings `\"markdown\"`, `\"pdf\"`, or `\"toon\"`, and/or a single JSON Schema object for structured output. Rules: at most one JSON Schema object; a JSON Schema object cannot be combined with `\"markdown\"` or `\"pdf\"`; `\"toon\"` requires a JSON Schema object. An invalid combination returns `400 invalid_output_formats`.\n\nAt run time, a task created with `workflow_id` inherits the workflow's `output_formats` when the request does not pass its own; a request-level `output_formats` always wins.", "items": { "oneOf": [ { "type": "string", "enum": [ "markdown", "pdf", "toon" ] }, { "type": "object", "description": "JSON Schema for structured output." } ] }, "example": [ { "type": "object", "properties": { "base_case": { "type": "string" }, "bull_case": { "type": "string" }, "bear_case": { "type": "string" }, "confidence": { "type": "number" } } }, "toon" ] }, "Workflow": { "type": "object", "description": "A workflow: templated, versioned DeepResearch. Valyu-curated workflows (`is_valyu: true`) are read-only.\n\nList rows carry the discovery and template fields below. When fetching a single workflow (`GET /v1/workflows/{slug}`), creating, or updating, the response also includes the resolved version body - `prompt`, `strategy`, `report_format`, `tools`, `changelog`, and `output_formats`. On list, those version-body fields are included only when `?expand=true`.", "required": [ "slug", "title", "version" ], "properties": { "slug": { "type": "string", "description": "Unique slug identifying the workflow within its scope. Used as `workflow_id` when running.", "example": "ib-company-profile" }, "version": { "type": "integer", "description": "The current (floating) published version number.", "minimum": 1, "example": 1 }, "vertical": { "type": "string", "nullable": true, "description": "Vertical the workflow targets (e.g. `investment-banking`, `private-equity`, `hedge-funds`, `consulting`, `life-sciences`, `legal-regulatory`, `sales-intelligence`, `supply-chain`).", "example": "investment-banking" }, "tags": { "type": "array", "description": "Tags for discovery. Up to 20.", "items": { "type": "string" }, "maxItems": 20, "example": ["company-profile", "equities"] }, "title": { "type": "string", "description": "Display title.", "example": "Company Profile" }, "subtitle": { "type": "string", "nullable": true, "description": "Short subtitle.", "example": "One-page profile of a public company." }, "description": { "type": "string", "nullable": true, "description": "Longer description of what the workflow does.", "example": "Builds a company profile covering business, financials, and recent developments." }, "popular": { "type": "boolean", "description": "Whether the workflow is flagged as popular.", "example": true }, "recommended_mode": { "$ref": "#/components/schemas/WorkflowMode" }, "estimated_time": { "type": "string", "nullable": true, "description": "Human-readable estimate of how long a run takes.", "example": "10-20 min" }, "is_valyu": { "type": "boolean", "description": "Whether this is a Valyu-curated workflow (read-only to users).", "example": true }, "owner_org_id": { "type": "string", "nullable": true, "description": "Organization that owns the workflow. `null` for Valyu-curated workflows.", "example": null }, "variables": { "type": "array", "description": "Typed variables referenced by the prompt template. Up to 50.", "items": { "$ref": "#/components/schemas/WorkflowVariable" }, "maxItems": 50 }, "deliverables": { "type": "array", "description": "Deliverables the workflow produces. Up to 20.", "items": { "$ref": "#/components/schemas/WorkflowDeliverable" }, "maxItems": 20 }, "created_at": { "type": "string", "format": "date-time", "description": "When the workflow was created.", "example": "2026-01-10T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the workflow's current version was last published.", "example": "2026-01-15T09:30:00Z" }, "prompt": { "type": "string", "description": "Prompt template with `{key}` placeholders. Included on detail (get/create/update) and on list with `?expand=true`.", "example": "Build a company profile for {company} covering its business, financials, and recent developments." }, "strategy": { "type": "string", "nullable": true, "description": "Research strategy. Maps to DeepResearch `research_strategy`. Included on detail and on list with `?expand=true`." }, "report_format": { "type": "string", "nullable": true, "description": "Report format instructions. Maps to DeepResearch `report_format`. Included on detail and on list with `?expand=true`." }, "tools": { "$ref": "#/components/schemas/WorkflowTools" }, "changelog": { "type": "string", "nullable": true, "description": "Changelog for the current version. Included on detail and on list with `?expand=true`." }, "output_formats": { "$ref": "#/components/schemas/WorkflowOutputFormats" } } }, "WorkflowResponse": { "description": "A single workflow returned as a flat object: the list-row fields plus the resolved version body (`prompt`, `strategy`, `report_format`, `tools`, `changelog`, `output_formats`). Returned by get, create (`201`), and update.", "$ref": "#/components/schemas/Workflow" }, "WorkflowListResponse": { "type": "object", "description": "List of workflows.", "required": [ "workflows", "total" ], "properties": { "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } }, "total": { "type": "integer", "description": "Total number of workflows matching the filter.", "example": 44 }, "next_cursor": { "type": "string", "nullable": true, "description": "Pagination cursor for the next page, or `null` when there are no more results.", "example": null }, "verticals": { "type": "array", "description": "Distinct verticals present across the curated catalog.", "items": { "type": "string" }, "example": [ "consulting", "private-equity", "life-sciences", "investment-banking", "hedge-funds", "legal-regulatory", "sales-intelligence", "supply-chain" ] } } }, "WorkflowVersionListResponse": { "type": "object", "description": "A workflow's version history, newest first.", "required": [ "slug", "versions" ], "properties": { "slug": { "type": "string", "example": "ib-company-profile" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVersionSummary" } } } }, "WorkflowVersionSummary": { "type": "object", "description": "A row in a workflow's version history.", "required": [ "version" ], "properties": { "version": { "type": "integer", "minimum": 1, "example": 2 }, "recommended_mode": { "$ref": "#/components/schemas/WorkflowMode" }, "estimated_time": { "type": "string", "nullable": true, "example": "10-20 min" }, "changelog": { "type": "string", "nullable": true, "example": "Added a competitive landscape section." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-15T09:30:00Z" }, "is_current": { "type": "boolean", "example": true } } }, "WorkflowPreviewRequest": { "type": "object", "description": "Resolve a workflow template against supplied parameters without running it.", "properties": { "workflow_params": { "type": "object", "description": "Values for the workflow's template variables, keyed by variable `key`.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "example": { "company": "NVIDIA (NVDA)" } }, "workflow_version": { "type": "integer", "description": "Version to preview. Defaults to the current version.", "minimum": 1, "example": 1 } } }, "WorkflowPreviewResponse": { "type": "object", "description": "The resolved configuration a run with these parameters would use.", "required": [ "workflow", "resolved" ], "properties": { "workflow": { "type": "object", "description": "Which workflow and version were resolved.", "properties": { "slug": { "type": "string", "example": "ib-company-profile" }, "version": { "type": "integer", "minimum": 1, "example": 1 } } }, "resolved": { "type": "object", "description": "The resolved DeepResearch configuration.", "properties": { "input": { "type": "string", "description": "The prompt template with all `{key}` placeholders substituted.", "example": "Build a company profile for NVIDIA (NVDA) covering its business, financials, and recent developments." }, "research_strategy": { "type": "string", "nullable": true, "description": "Resolved research strategy." }, "report_format": { "type": "string", "nullable": true, "description": "Resolved report format." }, "deliverables": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowDeliverable" } }, "mode": { "$ref": "#/components/schemas/WorkflowMode" }, "tools": { "$ref": "#/components/schemas/WorkflowTools" }, "output_formats": { "$ref": "#/components/schemas/WorkflowOutputFormats" } } }, "estimated_credits": { "type": "number", "nullable": true, "description": "Estimated credit cost of a run, when available.", "example": null } } }, "WorkflowVersionInput": { "type": "object", "description": "A workflow version body. Supplied as `version` when creating a workflow or publishing a new version on update.", "required": [ "prompt", "strategy", "report_format" ], "properties": { "prompt": { "type": "string", "description": "Prompt template with `{key}` placeholders. Up to 64 KB.", "example": "Build a company profile for {company} covering its business, financials, and recent developments." }, "strategy": { "type": "string", "description": "Research strategy. Maps to DeepResearch `research_strategy`. Up to 64 KB.", "example": "Prioritise the latest 10-K/10-Q, investor relations materials, and reputable news." }, "report_format": { "type": "string", "description": "Report format instructions. Maps to DeepResearch `report_format`. Up to 64 KB.", "example": "A one-page profile with business overview, key financials, and recent developments." }, "variables": { "type": "array", "description": "Typed template variables. Up to 50.", "items": { "$ref": "#/components/schemas/WorkflowVariable" }, "maxItems": 50 }, "deliverables": { "type": "array", "description": "Deliverables produced by the workflow. Up to 20.", "items": { "$ref": "#/components/schemas/WorkflowDeliverable" }, "maxItems": 20 }, "tools": { "$ref": "#/components/schemas/WorkflowTools" }, "recommended_mode": { "$ref": "#/components/schemas/WorkflowMode" }, "estimated_time": { "type": "string", "example": "10-20 min" }, "output_formats": { "$ref": "#/components/schemas/WorkflowOutputFormats" }, "changelog": { "type": "string", "description": "Notes describing what changed. Required when publishing a new version on update.", "example": "Added a competitive landscape section." } } }, "WorkflowCreateRequest": { "type": "object", "description": "Create an organization workflow. The authenticated org owns the workflow. Default org quota is 100 workflows. The first version is supplied as the nested `version` object.", "required": [ "slug", "title", "version" ], "properties": { "slug": { "type": "string", "description": "Unique slug within your org.", "example": "quarterly-company-profile" }, "title": { "type": "string", "example": "Quarterly Company Profile" }, "subtitle": { "type": "string", "example": "One-page profile of a public company." }, "description": { "type": "string", "example": "Builds a company profile covering business, financials, and recent developments." }, "vertical": { "type": "string", "example": "investment-banking" }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "example": ["company-profile", "equities"] }, "icon": { "type": "string", "example": "building" }, "version": { "description": "The workflow's first version body.", "$ref": "#/components/schemas/WorkflowVersionInput" } } }, "WorkflowUpdateRequest": { "type": "object", "description": "Edit an organization workflow. Metadata fields (title, subtitle, etc.) update in place. Supply a `version` object to publish a new immutable version - it requires a `changelog`. Valyu-curated workflows cannot be edited (`cannot_edit_valyu_workflow`).", "properties": { "title": { "type": "string" }, "subtitle": { "type": "string" }, "description": { "type": "string" }, "vertical": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "icon": { "type": "string" }, "version": { "description": "A new version body to publish. Requires `changelog` (`changelog_required` otherwise).", "$ref": "#/components/schemas/WorkflowVersionInput" }, "set_current": { "type": "boolean", "description": "When publishing a new version, whether to point the workflow's current (floating) version at it.", "example": true } } }, "WorkflowDeleteResponse": { "type": "object", "description": "Confirmation of a soft delete.", "required": [ "slug", "deleted_at" ], "properties": { "slug": { "type": "string", "example": "quarterly-company-profile" }, "deleted_at": { "type": "string", "format": "date-time", "description": "When the workflow was soft-deleted.", "example": "2026-01-20T16:45:00Z" } } }, "WorkflowError": { "type": "object", "description": "Workflow error response. `error` is a machine-readable code; `message` is human-readable text.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Machine-readable error code.", "example": "invalid_output_formats" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "output_formats may contain at most one JSON schema, which cannot be combined with markdown or pdf." } } } }, "responses": { "BadRequest": { "description": "The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "summary": "Invalid parameters", "value": { "success": false, "error": "Invalid search_type. Must be 'all', 'web', 'proprietary', or 'news'" } } } } } }, "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "summary": "Invalid API key", "value": { "success": false, "error": "Invalid API key" } } } } } }, "PaymentRequired": { "description": "Insufficient credits or monthly limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "summary": "Insufficient credits", "value": { "success": false, "error": "Insufficient credits. Please top up your account at platform.valyu.ai" } } } } } }, "Forbidden": { "description": "The API key does not have permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "summary": "Permission denied", "value": { "success": false, "error": "API key does not have inference permission" } } } } } }, "NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "summary": "Resource not found", "value": { "success": false, "error": "Task not found" } } } } } }, "RateLimited": { "description": "Too many requests. Slow down and retry after the indicated period.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the rate limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "summary": "Rate limit exceeded", "value": { "success": false, "error": "Rate limit exceeded. Please retry after the Retry-After period." } } } } } }, "InternalServerError": { "description": "An unexpected error occurred on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "summary": "Internal error", "value": { "success": false, "error": "Internal server error. Please try again later." } } } } } }, "WorkflowBadRequest": { "description": "The workflow request was invalid. The `error` field carries a machine-readable code and `message` a human-readable explanation.\n\nCommon codes:\n- `changelog_required` - a changelog is required when publishing a new version\n- `unreferenced_template_vars` - a declared variable is not used in the prompt template, or the template references an unknown variable\n- `invalid_output_formats` - `output_formats` contained more than one JSON schema, mixed a schema with `markdown`/`pdf`, or used `toon` without a schema\n- `field_too_long` - a text field exceeds its limit (64 KB)\n- `too_many_variables` - more than 50 variables\n- `too_many_deliverables` - more than 20 deliverables\n- `workflow_and_freeform_mutually_exclusive` - workflow and freeform fields were both supplied (on the DeepResearch create endpoint)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowError" }, "examples": { "changelog_required": { "summary": "Changelog required", "value": { "error": "changelog_required", "message": "A changelog is required when publishing a new version." } }, "unreferenced_template_vars": { "summary": "Unreferenced template variable", "value": { "error": "unreferenced_template_vars", "message": "A declared variable is not used in the prompt template, or the template references an unknown variable." } }, "invalid_output_formats": { "summary": "Invalid output_formats", "value": { "error": "invalid_output_formats", "message": "output_formats may contain at most one JSON schema, which cannot be combined with markdown or pdf; toon requires a schema." } } } } } }, "WorkflowForbidden": { "description": "The operation is not permitted on this workflow.\n\nCommon codes:\n- `cannot_edit_valyu_workflow` - curated Valyu workflows are read-only\n- `cannot_delete_valyu_workflow` - curated Valyu workflows cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowError" }, "examples": { "cannot_edit_valyu_workflow": { "summary": "Cannot edit a curated workflow", "value": { "error": "cannot_edit_valyu_workflow", "message": "Valyu-curated workflows are read-only." } } } } } }, "WorkflowNotFound": { "description": "The workflow or version was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowError" }, "examples": { "workflow_not_found": { "summary": "Workflow not found", "value": { "error": "workflow_not_found", "message": "No workflow matches that slug." } } } } } }, "WorkflowConflict": { "description": "The workflow could not be created due to a conflict.\n\nCommon codes:\n- `workflow_quota_exceeded` - your organization has reached its workflow quota (default 100)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowError" }, "examples": { "workflow_quota_exceeded": { "summary": "Workflow quota exceeded", "value": { "error": "workflow_quota_exceeded", "message": "Your organization has reached its workflow quota." } } } } } } } } }