> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Shared Store

> Create a shared store in your organization.

This page documents its request, success response, and error response fields in full.

Organizations can have up to 10 shared stores.

## Request

### Headers

| Header          | Type   | Required | Allowed value and meaning                                                               |
| --------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `Authorization` | string | Yes      | `Bearer <Mosaic API key>`. The key determines the organization that owns the new store. |
| `Content-Type`  | string | Yes      | `application/json`.                                                                     |

This endpoint has no path or query parameters.

```bash theme={null}
curl -X POST "https://api.mosaic.so/shared-stores" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Talent","source_type":"manual"}'
```

### JSON body

| Field         | Type   | Required | Description                                                                                |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `name`        | string | Yes      | Any non-empty display name. Surrounding whitespace is removed before storage and response. |
| `source_type` | string | No       | Any non-empty source label. Defaults to `manual`; this field is not an enum.               |

## Response

### `200 OK`

```json theme={null}
{
  "store": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Talent",
    "source_type": "manual",
    "created_at": "2026-08-03T20:00:00Z",
    "updated_at": "2026-08-03T20:00:00Z"
  }
}
```

The generated `id` is the `{store_id}` used by all other endpoints.

| Field               | Type            | Meaning and possible values                                                                                                 |
| ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `store`             | object          | The newly created shared store. The object always contains every field listed below.                                        |
| `store.id`          | UUID string     | Mosaic-generated permanent identifier. Pass this exact value as `{store_id}` in all other store and entry endpoints.        |
| `store.name`        | string          | Trimmed store name accepted from the request. Always non-empty.                                                             |
| `store.source_type` | string          | Trimmed source label accepted from the request, or `manual` when omitted. May be any non-empty string; this is not an enum. |
| `store.created_at`  | ISO 8601 string | UTC timestamp when the store was created.                                                                                   |
| `store.updated_at`  | ISO 8601 string | UTC timestamp when the store was last changed. On creation, this normally equals `store.created_at`.                        |

## Error responses

### `409 Conflict` — organization limit

```json theme={null}
{
  "error": "An organization may have at most 10 shared stores",
  "code": "shared_store_limit_reached",
  "limit": 10
}
```

| Status                      | Payload                                                                  | Possible value                                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | `{ "error": "name is required" }`                                        | `name` is missing, empty, or only whitespace.                                                                                               |
| `401 Unauthorized`          | `{ "detail": string }`                                                   | `detail` is exactly `Authorization header must start with Bearer`, `invalid_api_key`, or `API key must be associated with an organization`. |
| `403 Forbidden`             | `{ "detail": "api_access_required" }`                                    | API access is unavailable for the organization.                                                                                             |
| `409 Conflict`              | `{ "error": string, "code": "shared_store_limit_reached", "limit": 10 }` | The organization already has 10 stores.                                                                                                     |
| `500 Internal Server Error` | `{ "error": "Failed to create shared store" }`                           | The store could not be created.                                                                                                             |