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

# Share a session

`POST /sessions/{sessionId}/shares`

Share a session read-only with another person by email. Works for every session type — reports, systematic reviews, and Research Agent sessions. Sessions are shared read-only: the recipient can view the session but cannot modify, resume, stop, or re-share it (agent sessions are read-only by design; report and systematic-review shares are read-only through the API).

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 — Access level of the share. Sessions are always shared read-only.
  - `url` string, required — URL to view and continue the session in the Elicit web interface.

## 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` — Session not found. The session ID is invalid or belongs to a different user (or, for an agent session, the Research Agent API is not enabled for this account).
- `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 after a short delay.

---

[API](https://skmtc.dev/elicit/apis/elicit-api.md) · [All operations](https://skmtc.dev/elicit/apis/elicit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/elicit/elicit-api/revisions/2b42624536e5/schema)