---
title: "Share a session"
method: POST
path: "/sessions/{sessionId}/shares"
tags: ["Sessions"]
---

# Share a session

`POST /sessions/{sessionId}/shares`

## Request

- Base URL: `https://elicit.com/api/v2`
- URL: `https://elicit.com/api/v2/sessions/{sessionId}/shares`
- Auth: HTTP bearer

Grant read-only access to a session by email. Works for every session type — reports, systematic reviews, and Research Agent sessions. New recipients can view the session; this grant does not let them modify, resume, stop, or re-share it.

Existing editor or reviewer permissions on reports and systematic reviews are preserved, not downgraded. The returned `share.role: "reader"` describes this API's read-only grant, not the recipient's full effective permissions. Inspect or change higher-permission roles in the web interface; they are not returned by the list-shares endpoint. **Revoking the email with DELETE still removes its direct share, including an existing editor or reviewer grant.**

If the email belongs to an existing Elicit account the share takes effect immediately (`status: "registered"`). Otherwise a pending invitation is created and an email is sent (`status: "invited"`); the share activates when they create an account.

Only the session owner can manage shares. A recipient of a shared **agent** session sees it in `GET /api/v2/sessions` with `role: "shared"`; a recipient of a shared **report** or **systematic review** opens it via the returned web-app `url` — it will **not** appear in their `GET /api/v2/sessions` list, which stays owner-only for review sessions.

### Example

```bash
curl -X POST https://elicit.com/api/v2/sessions/{sessionId}/shares \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email":"colleague@example.com"}'
```

## Path parameters

- `sessionId` string, uuid, required: The session ID (UUID) returned by the create endpoints and `GET /sessions`

## Request body

- object
  - `email` string, email, required: Email address to share the session with, as a read-only recipient.

## Response `201`

The session was shared with the recipient.

- CreateSessionShareResponse
  - `sessionId` string, required: Unique identifier for the session.
  - `share` SessionShare, required
    - `email` string, required: Email address the session is shared with.
    - `status` 'registered' | 'invited', required: "registered" when the recipient already has an Elicit account and can read the session now; "invited" when a pending invitation was created for an email without an account.
    - `role` 'reader', required: Read-only access requested through this API. Creating a share preserves any existing editor/reviewer permissions, so this field is not a complete description of effective access.
  - `url` string, required: URL to view the session in the Elicit web interface. Available actions depend on your permissions.

## Other responses

- `400`: Invalid request. The email is missing/malformed, or it is the caller's own address (you cannot share a session with yourself).
- `401`: Authentication failed. The API key is missing, invalid, revoked, or expired.
- `403`: The share could not be created: the session's recipient cap was reached, or inviting people without an Elicit account is not available on this account.
- `404`: The session does not exist or is not accessible to you for this operation.
- `429`: Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.
- `500`: An unexpected error occurred. Retry reads with backoff; before retrying a write, check whether it took effect. See Error Handling for retry guidance.

## Changes

- **2026-10-16** `22847bf7e65d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/changes/sessions/:sessionId/shares/post.md)

---

[API](https://skmtc.dev/elicitlabs/apis/elicit-labs-api.md) - [All operations](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/revisions/cbbe29509d04?raw)