---
title: "Share a project"
method: POST
path: "/projects/{projectId}/shares"
tags: ["Projects"]
---

# Share a project

`POST /projects/{projectId}/shares`

## Request

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

Shares the project read-only with an email address. Owner-only.

If the email has an Elicit account, they get read access immediately and `status` is `registered`. Otherwise a pending invitation is created and `status` is `invited`; inviting people without an account requires that your plan allows it.

An email that already has edit access keeps it: nothing is downgraded, and the response reports their `role` as `writer`. Repeating a share is safe, including for a recipient whose organization also has edit access to the project.

A `400` means the request can't produce a share: `self_share` for your own address, `already_has_org_access` when the recipient's organization already has edit access to the project so a read-only share would do nothing. A `403` means the share is not allowed: `cap_exceeded` when the project has reached its recipient limit, `gate_denied` when your plan cannot invite people without an Elicit account.

### Example

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

## Path parameters

- `projectId` string, uuid, required: The project ID (UUID) from `GET /projects` or `POST /projects`

## Request body

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

## Response `201`

The share that now exists.

- CreateProjectShareResponse
  - `projectId` string, uuid, required: The project ID (UUID) from `GET /projects` or `POST /projects`
  - `share` ProjectShare, required
    - `email` string, required: Email address the project is shared with.
    - `status` 'registered' | 'invited', required: "registered" when the recipient already has an Elicit account and can read the project now; "invited" when a pending invitation was created for an email without an account.
    - `role` 'reader' | 'writer', required: The recipient's effective access level — the strongest of their own share and any organization-wide share that currently reaches them. This endpoint creates `reader` shares; `writer` means edit access was granted in the Elicit web interface.
  - `url` string, required: URL to open this project in the Elicit web interface.

## Other responses

- `400`: The request cannot produce a share.
- `401`: Authentication failed. The API key is missing, invalid, revoked, or expired.
- `403`: API access is unavailable, the project's recipient limit was reached, or the plan cannot invite people without an Elicit account.
- `404`: The project does not exist, or is not visible to you at the access this call needs.
- `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/projects/:projectId/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)