> ## Documentation Index > Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Workflow > Reference for creating a custom org Workflow template via POST /v1/workflows. ## OpenAPI ````yaml POST /v1/workflows 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. ## Products | Product | Endpoint | Description | | --- | --- | --- | | **Search** | `POST /v1/search` | Multi-source search across web and proprietary datasets | | **Contents** | `POST /v1/contents` | Extract clean, structured content from URLs | | **Answer** | `POST /v1/answer` | AI-powered answers with real-time search | | **DeepResearch** | `POST /v1/deepresearch/tasks` | Async research agents for comprehensive analysis | | **Workflows** (Beta) | `GET /v1/workflows` | Templated, versioned DeepResearch for repeatable knowledge work | | **Datasources** | `GET /v1/datasources` | Discover available data sources and their schemas | ## Authentication All 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). ``` X-API-Key: your_api_key_here ``` ## Pricing Valyu uses transparent, pay-per-use pricing. Credits are shared across every API. - **Search**: CPM-based (cost per mille tokens retrieved) - **Contents**: $0.001 per URL extracted, +$0.001 with AI features - **Answer**: $0.10 per request + variable search and AI costs - **DeepResearch**: Fixed per-task pricing by mode ($0.10 - $15.00) All 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. ## SDKs - [Python SDK](https://pypi.org/project/valyu/) - `pip install valyu` - [TypeScript SDK](https://www.npmjs.com/package/valyu) - `npm install valyu` 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 externalDocs: description: Complete API Documentation url: https://docs.valyu.ai paths: /v1/workflows: post: tags: - Workflows 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. operationId: createWorkflow 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' components: schemas: 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: $ref: '#/components/schemas/WorkflowVersionInput' description: The workflow's first version body. WorkflowResponse: $ref: '#/components/schemas/Workflow' 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. 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. Workflow: type: object description: >- A workflow: templated, versioned DeepResearch. Valyu-curated workflows (`is_valyu: true`) are read-only. List 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' 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. 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 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. WorkflowMode: type: string description: >- Recommended DeepResearch mode for a workflow. Maps directly to the DeepResearch `mode` parameter. enum: - fast - standard - heavy - max example: heavy 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`. At 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 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 responses: WorkflowBadRequest: description: >- The workflow request was invalid. The `error` field carries a machine-readable code and `message` a human-readable explanation. Common codes: - `changelog_required` - a changelog is required when publishing a new version - `unreferenced_template_vars` - a declared variable is not used in the prompt template, or the template references an unknown variable - `invalid_output_formats` - `output_formats` contained more than one JSON schema, mixed a schema with `markdown`/`pdf`, or used `toon` without a schema - `field_too_long` - a text field exceeds its limit (64 KB) - `too_many_variables` - more than 50 variables - `too_many_deliverables` - more than 20 deliverables - `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. 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 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 WorkflowConflict: description: >- The workflow could not be created due to a conflict. Common codes: - `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. 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. 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). ````