> ## 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. # Update Sharing > Reference for sharing a DeepResearch report with specific people via POST /v1/deepresearch/tasks/\{id\}/share. Add or remove the people (`name@company.com`) and company domains (`@company.com`) who can open a report. The report stays private: viewers sign in to Valyu with an email it is shared with. Additions and removals apply together or not at all. Each person you add is emailed a link unless you send `"notify": false`. Domains are never emailed. Only the API key that created the task can change its sharing. See [share a report with specific people](https://docs.valyu.ai/guides/deepresearch-sharing.md) for the rules. ## OpenAPI ````yaml POST /v1/deepresearch/tasks/{id}/share 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 Pay per use in credits. One credit balance covers every API. - **Search**: priced per result returned. Web and news results use 0.1 credits each (100 per 1,000 results). arXiv, PubMed, bioRxiv and medRxiv use 0.05 credits each (50 per 1,000). Other datasets have their own price per 1,000 results, listed in `GET /v1/datasources` (`pricing.cpm`). - **Contents**: 0.2 credits per successfully extracted URL. Any AI processing (a text summary or structured extraction through `summary`) brings the price to 0.6 credits per URL in total, the same for both. Failed URLs are free. - **Answer**: no per-request fee. You pay for the search, content extraction and AI processing each answer uses, reported in `cost.total_deduction_dollars`. - **DeepResearch**: fixed price per task by mode: instant 8 credits, fast 25, standard 100, heavy 500, max 2,500, plus tool add-ons. Every plan includes web search and open academic sources. Paid plans unlock specialist sources such as SEC filings, clinical trials, patents and genomics. See [pricing](https://docs.valyu.ai/pricing) for plans and free credits. ## Rate limits Limits apply per organisation: 10 requests per second with bursts up to 20, and 86,400 requests per day by default. Enterprise plans can raise them. A request over the limit is currently rejected with `403 Forbidden` and the body `{"error": "Forbidden", "message": "Access denied - API key is invalid, disabled, or revoked"}`. If a key that otherwise works starts receiving 403 under load, reduce concurrency and retry with exponential backoff. ## SDKs - [Python SDK](https://pypi.org/project/valyu/) - `pip install valyu` - [TypeScript SDK](https://www.npmjs.com/package/valyu-js) - `npm install valyu-js` 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/deepresearch/tasks/{id}/share: post: tags: - DeepResearch summary: Share a task with specific people description: >- Add or remove people and company domains who can open a DeepResearch report. The report stays private: only the people and domains it is shared with, and members of your organization, can open it after signing in to Valyu with a verified email address. Additions and removals apply together or not at all. Each person you add is emailed a link unless `notify` is `false`; domains are never emailed. A report can be shared with up to 100 people and domains. Only the API key that created the task can call this endpoint. Sharing is independent of the `public` flag set with [Toggle public access](https://docs.valyu.ai/api-reference/endpoint/deepresearch-public). operationId: updateDeepResearchSharing parameters: - name: id in: path required: true schema: type: string description: DeepResearch task ID. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeepResearchShareUpdateRequest' examples: add: summary: Share with a person value: add: - ben@client.com add_and_remove: summary: Add a person and remove a domain value: add: - ben@client.com remove: - '@acme.com' shared_by: Maya at Northwind Capital add_quietly: summary: Share with a domain without sending email value: add: - '@client.com' notify: false responses: '200': description: Sharing updated. content: application/json: schema: $ref: '#/components/schemas/DeepResearchShareUpdateResponse' examples: updated: summary: Person added and domain removed value: deepresearch_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 public: false share_url: >- https://platform.valyu.ai/share/a1b2c3d4-e5f6-7890-abcd-ef1234567890 shared_with: - email: anna@client.com added_at: '2026-11-12T10:30:00.000Z' notified_at: '2026-11-12T10:30:01.000Z' last_viewed_at: '2026-11-12T14:05:00.000Z' - email: ben@client.com added_at: '2026-11-12T15:00:00.000Z' notified_at: '2026-11-12T15:00:01.000Z' notified: - ben@client.com '400': description: >- Invalid request: an invalid email address or domain, a public email provider shared as a domain, an unknown field, or neither `add` nor `remove` names anyone. Nothing is changed. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- The API key did not create this task, or the key is disabled or lacks permission. Only the API key that created the task can view or change who it is shared with. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_owner: summary: Key did not create the task value: error: Only the task owner can share it code: task.not_owner '404': $ref: '#/components/responses/NotFound' '429': description: >- Too many reports were shared in the last 24 hours. Nothing is changed. Try again later. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' components: schemas: DeepResearchShareUpdateRequest: type: object additionalProperties: false description: >- People or company domains to add to or remove from a report. At least one of `add` or `remove` must name someone. Additions and removals apply together or not at all. properties: add: type: array description: >- Email addresses (`name@company.com`) or company domains (`@company.com`) to share the report with. Public email providers can't be added as a domain. items: type: string example: - ben@client.com remove: type: array description: >- Email addresses or company domains to stop sharing the report with, in the same format as `add`. items: type: string example: - '@acme.com' notify: type: boolean description: >- Email each person in `add` a link to the report. Domains are never emailed. default: true shared_by: type: string maxLength: 80 description: >- How the email names the sender. Defaults to your organization's name. example: Maya at Northwind Capital DeepResearchShareUpdateResponse: type: object description: Who a DeepResearch report is shared with after the change. required: - deepresearch_id - public - share_url - shared_with - notified properties: deepresearch_id: type: string description: ID of the task. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 public: type: boolean description: >- Whether anyone with the link can open the report. Set with [Toggle public access](https://docs.valyu.ai/api-reference/endpoint/deepresearch-public). Independent of `shared_with`. example: false share_url: type: string format: uri description: Link to the report. example: https://platform.valyu.ai/share/a1b2c3d4-e5f6-7890-abcd-ef1234567890 shared_with: type: array description: People and domains the report is shared with. items: $ref: '#/components/schemas/DeepResearchShareEntry' notified: type: array description: Email addresses that were sent a link in this request. items: type: string format: email example: - ben@client.com Error: type: object description: >- Error response. Every error body has `error`. Search, Contents, Answer and Datasources errors usually also carry `success: false`. Errors returned before a request reaches the endpoint (missing, invalid or disabled keys, rate limits) and DeepResearch errors have no `success` field. Some errors add a machine-readable `code` and a `recovery` object. required: - error properties: success: type: boolean description: '`false` when present.' example: false error: type: string description: >- Error message, or a machine-readable code for some errors (for example `invalid_scope_policy`, or `rate_limited` on a `429`). example: Invalid request parameters message: type: string description: >- Human-readable detail. Present on errors returned before the request reaches the endpoint. code: type: string description: >- Stable machine-readable error code, when available. Branch on this rather than on the message text. example: insufficient_credits recovery: type: object description: Links or details that help resolve the error, when available. additionalProperties: true transaction_id: type: string description: Transaction ID for support, when available. DeepResearchShareEntry: type: object description: >- One person or company domain the report is shared with. Each entry has either `email` or `domain`. required: - added_at properties: email: type: string format: email description: Email address of a person the report is shared with. example: anna@client.com domain: type: string description: >- Company domain the report is shared with, without the leading `@`. Covers anyone with a verified email at exactly this domain. example: acme.com added_at: type: string format: date-time description: When the person or domain was added. example: '2026-11-12T10:30:00.000Z' notified_at: type: string format: date-time description: >- When the person was last emailed a link. Absent if they were never emailed. Domains are never emailed. example: '2026-11-12T10:30:01.000Z' last_viewed_at: type: string format: date-time description: >- When the person last opened the report. Absent if they haven't opened it. example: '2026-11-12T14:05:00.000Z' responses: Unauthorized: description: Missing or invalid API key. Send your key in the `X-API-Key` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_or_invalid: summary: Missing or invalid API key value: error: Unauthorized message: API key is missing or invalid invalid_key: summary: Invalid API key (endpoint response) value: success: false error: Invalid API key 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 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). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.