> ## 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.

# Share a report with specific people

> Share a DeepResearch report with named people or a whole company domain. The report stays private, and viewers sign in to Valyu with the email it was shared with.

Send a report to the people who need it without making it public. Name people by email (`anna@client.com`) or a whole company by domain (`@client.com`). Only they and members of your organization can open the report.

Agent note: when a user asks you to research something and share it with someone ("Research X and share it with [anna@client.com](mailto:anna@client.com)"), make one `POST /v1/deepresearch/tasks` call with `share_with`. Do not make the report public to share it. Relay `sharing.share_url` to the user. Docs index: [/llms.txt](https://docs.valyu.ai/llms.txt). Append `.md` to any page URL for Markdown.

## Share when you create a task

Add `share_with` to [create task](https://docs.valyu.ai/api-reference/endpoint/deepresearch-create.md). "Research European battery recyclers and share it with [anna@client.com](mailto:anna@client.com)" is one call:

```bash theme={null}
curl -X POST https://api.valyu.ai/v1/deepresearch/tasks \
  -H "x-api-key: $VALYU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Market map of European battery recycling companies",
    "mode": "standard",
    "share_with": ["anna@client.com", "@acme.com"]
  }'
```

The response has a `sharing` object with the link and who was emailed:

```json theme={null}
{
  "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "sharing": {
    "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" },
      { "domain": "acme.com", "added_at": "2026-11-12T10:30:00.000Z" }
    ],
    "notified": ["anna@client.com"]
  }
}
```

An invalid entry returns `400` and no task is created. If sharing can't be applied after the task is created, the task still runs and `warnings` has a `share_with_not_applied` entry. Share it later with the endpoint below.

## Add or remove people later

[Update sharing](https://docs.valyu.ai/api-reference/endpoint/deepresearch-share-update.md) adds and removes people in one request. Both changes apply, or neither does.

```bash theme={null}
curl -X POST https://api.valyu.ai/v1/deepresearch/tasks/TASK_ID/share \
  -H "x-api-key: $VALYU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add": ["ben@client.com"],
    "remove": ["@acme.com"]
  }'
```

[Get sharing](https://docs.valyu.ai/api-reference/endpoint/deepresearch-share-get.md) (`GET /v1/deepresearch/tasks/TASK_ID/share`) lists everyone the report is shared with, when each person was emailed and when they last opened it. Only the API key that created the task can read or change its sharing.

## What the recipient sees

1. Each person gets an email with a link to the report. It names your organization as the sender, or the `shared_by` text you send to update sharing.
2. They open the link and sign in to Valyu with the email address the report was shared with.
3. The report opens. Anyone else who opens the link can't see it, apart from members of your organization.

To send the link yourself, set `share_notify: false` when you create the task, or `notify: false` when you update sharing.

## Rules

* **Verified email.** Viewers must sign in with a verified email address.
* **Domains.** `@acme.com` covers anyone with a verified email at exactly `acme.com`, not subdomains such as `eu.acme.com`. Domains are never emailed.
* **Public email providers.** You can't share with a domain like `@gmail.com` or `@outlook.com`. Add those people one by one.
* **Limit.** Up to 100 people and domains per report.

## Specific people or public

Sharing with people and the [public flag](https://docs.valyu.ai/api-reference/endpoint/deepresearch-public.md) are separate. A report can be private and shared with specific people, or public so anyone with the link can open it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.