> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.athenaintel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.athenaintel.com/_mcp/server.

# Share an asset with users

POST https://api.athenaintel.com/api/v0/assets/{asset_id}/share
Content-Type: application/json

Share an asset with specific users by email. Only users who have edit access to the asset can share it. You can share with individual users (granting 'view' or 'edit' permission). Sharing with a user who does not have an account will result in an error for that recipient, but other recipients will still be processed.

Reference: https://docs.athenaintel.com/api-reference/assets/share

## Authentication

- `X-API-KEY` header (required) — API Key authentication via header

## Request

### Path parameters

- `asset_id` (string, required) — Unique identifier of the asset to share

### Body (application/json)

This endpoint expects a ShareAssetRequestIn.

- `recipients` (list of ShareRecipient, required) — List of users to share the asset with. Each entry specifies an email address and the permission level to grant.
- `include_folder_contents` (boolean, optional, nullable) — Controls child-sharing when sharing a container asset (folder, collection, or project). true: also share the container's children owned by the current user. false: container only, skip children. null (default): folders share all accessible children; collections and projects are container-only (their cascade is opt-in via true).
- `message` (string, optional, nullable) — Optional personal message to include in the notification email (max 2000 characters)
- `notify` (boolean, optional, default: true) — Whether to notify recipients (email, plus a Slack DM when their workspace has Athena for Slack)

## Response

### 200

Asset sharing processed successfully

- `asset_id` (string, required) — ID of the shared asset
- `recipients_result` (list of ShareRecipientResultOut, required) — Results for each recipient that was shared with

## Errors

### 400 Bad Request Error

External viewer sent too many recipients

- `any`

### 403 Forbidden Error

Forbidden - caller does not have edit access to the asset

- `message` (string, required)

### 404 Not Found Error

Asset not found

- `message` (string, required)

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

### 429 Too Many Requests Error

External viewer share budget exhausted

- `any`

### 503 Service Unavailable Error

External viewer share budget unenforceable

- `any`

## Types

### ShareRecipient

A single recipient for asset sharing.

- `email` (string, required) — Email address of the user to share with
- `permission` (enum, optional) — Permission level to grant: 'view' or 'edit'
  - Allowed values: `view`, `edit`

### ShareRecipientResultOut

Result for a single share recipient.

- `email` (string, required) — Email address of the recipient
- `permission` (string, required) — Permission level granted ('view' or 'edit')
- `success` (boolean, required) — Whether sharing was successful for this recipient
- `error` (string, optional, nullable) — Error message if sharing failed for this recipient

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `ctx` (ValidationErrorCtx, optional)
- `input` (any, optional)

### ValidationErrorLocItems

- string
- integer

### ValidationErrorCtx

## Examples

**Request**

```json
{
  "recipients": [
    {
      "email": "colleague@example.com",
      "permission": "edit"
    },
    {
      "email": "reviewer@example.com",
      "permission": "view"
    }
  ],
  "message": "Here's the document we discussed.",
  "notify": true
}
```

**Response**

```json
{
  "asset_id": "asset_92492920-d118-42d3-95b4-00eccfe0754f",
  "recipients_result": [
    {
      "email": "colleague@example.com",
      "permission": "edit",
      "success": true
    }
  ]
}
```

**SDK Code**

```python assets_share_example
import requests

url = "https://api.athenaintel.com/api/v0/assets/asset_id/share"

payload = {
    "recipients": [
        {
            "email": "colleague@example.com",
            "permission": "edit"
        },
        {
            "email": "reviewer@example.com",
            "permission": "view"
        }
    ],
    "message": "Here's the document we discussed.",
    "notify": True
}
headers = {
    "X-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript assets_share_example
const url = 'https://api.athenaintel.com/api/v0/assets/asset_id/share';
const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"recipients":[{"email":"colleague@example.com","permission":"edit"},{"email":"reviewer@example.com","permission":"view"}],"message":"Here\'s the document we discussed.","notify":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go assets_share_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.athenaintel.com/api/v0/assets/asset_id/share"

	payload := strings.NewReader("{\n  \"recipients\": [\n    {\n      \"email\": \"colleague@example.com\",\n      \"permission\": \"edit\"\n    },\n    {\n      \"email\": \"reviewer@example.com\",\n      \"permission\": \"view\"\n    }\n  ],\n  \"message\": \"Here's the document we discussed.\",\n  \"notify\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby assets_share_example
require 'uri'
require 'net/http'

url = URI("https://api.athenaintel.com/api/v0/assets/asset_id/share")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"recipients\": [\n    {\n      \"email\": \"colleague@example.com\",\n      \"permission\": \"edit\"\n    },\n    {\n      \"email\": \"reviewer@example.com\",\n      \"permission\": \"view\"\n    }\n  ],\n  \"message\": \"Here's the document we discussed.\",\n  \"notify\": true\n}"

response = http.request(request)
puts response.read_body
```

```java assets_share_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.athenaintel.com/api/v0/assets/asset_id/share")
  .header("X-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"recipients\": [\n    {\n      \"email\": \"colleague@example.com\",\n      \"permission\": \"edit\"\n    },\n    {\n      \"email\": \"reviewer@example.com\",\n      \"permission\": \"view\"\n    }\n  ],\n  \"message\": \"Here's the document we discussed.\",\n  \"notify\": true\n}")
  .asString();
```

```php assets_share_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.athenaintel.com/api/v0/assets/asset_id/share', [
  'body' => '{
  "recipients": [
    {
      "email": "colleague@example.com",
      "permission": "edit"
    },
    {
      "email": "reviewer@example.com",
      "permission": "view"
    }
  ],
  "message": "Here\'s the document we discussed.",
  "notify": true
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp assets_share_example
using RestSharp;

var client = new RestClient("https://api.athenaintel.com/api/v0/assets/asset_id/share");
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"recipients\": [\n    {\n      \"email\": \"colleague@example.com\",\n      \"permission\": \"edit\"\n    },\n    {\n      \"email\": \"reviewer@example.com\",\n      \"permission\": \"view\"\n    }\n  ],\n  \"message\": \"Here's the document we discussed.\",\n  \"notify\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift assets_share_example
import Foundation

let headers = [
  "X-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "recipients": [
    [
      "email": "colleague@example.com",
      "permission": "edit"
    ],
    [
      "email": "reviewer@example.com",
      "permission": "view"
    ]
  ],
  "message": "Here's the document we discussed.",
  "notify": true
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.athenaintel.com/api/v0/assets/asset_id/share")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```