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

# Projects

# Projects

A **project** is a named container for content inside a workspace —
typically one personal-brand profile or one company page. Notes, posts,
sources, and queue slots all attach to a project.

The v1 API exposes a paginated list of the workspace's projects and a
single-project read. Both are read-only in v1; mutating projects
(creation, archive, pause) is dashboard-only.

***

## `GET /v1/projects`

List the projects the authenticated workspace owns, ordered by creation
time descending.

```bash theme={null}
curl -i 'https://api.scripe.io/v1/projects?limit=50' \
  -H "Authorization: Bearer scripe_sk_live_…" \
  -H "Scripe-Api-Version: 2026-08-01"
```

### Query parameters

| Name     | Type    | Default | Notes                                                                                   |
| -------- | ------- | ------- | --------------------------------------------------------------------------------------- |
| `limit`  | integer | 50      | Page size. Clamped to 1…200; out of range → `400 bad_pagination`.                       |
| `cursor` | string  | —       | Opaque cursor from a previous response. See [conventions](./conventions.md#pagination). |

### Response

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "proj_01J9ZA…",
      "name": "Personal Brand",
      "type": "PERSONAL_BRAND",
      "status": "ACTIVE",
      "url": "https://www.linkedin.com/in/example",
      "createdAt": "2026-05-15T08:21:00.000Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJjcmVhdGVkQXQiOiIyMDI2L…",
    "has_more": true
  }
}
```

### Field reference

| Path        | Type              | Notes                                                                                                  |
| ----------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
| `id`        | string (`proj_*`) | Stable identifier. Use it everywhere else in the API.                                                  |
| `name`      | string            | Display name set in the dashboard. May contain emoji.                                                  |
| `type`      | string            | `PERSONAL_BRAND` \| `COMPANY_PAGE`. More may land in additive minor releases.                          |
| `status`    | string            | `ACTIVE` \| `PAUSED` \| `ARCHIVED` \| `ERROR`. Filter clients should treat unknown values as `ACTIVE`. |
| `url`       | string \| null    | The LinkedIn URL the project represents, if connected.                                                 |
| `createdAt` | string (ISO 8601) | UTC, millisecond precision.                                                                            |

Internal fields like the workspace's owner user id, billing customer id,
and onboarding flags are intentionally **not** in this response. If you
need them, use the dashboard.

***

## `GET /v1/projects/{projectId}`

Single project read. Returns the same shape as above, wrapped in a `data`
field for symmetry with future write endpoints.

```bash theme={null}
curl -i https://api.scripe.io/v1/projects/proj_01J9ZA… \
  -H "Authorization: Bearer scripe_sk_live_…" \
  -H "Scripe-Api-Version: 2026-08-01"
```

### Response

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": "proj_01J9ZA…",
    "name": "Personal Brand",
    "type": "PERSONAL_BRAND",
    "status": "ACTIVE",
    "url": "https://www.linkedin.com/in/example",
    "createdAt": "2026-05-15T08:21:00.000Z"
  }
}
```

### Errors

| Status | Code                                                             | When                                                                                                                                                     |
| ------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `bad_cursor`, `bad_pagination`                                   | Cursor invalid / out-of-range limit. List endpoint only.                                                                                                 |
| 401    | `unauthenticated`, `invalid_token`, `key_revoked`, `key_expired` |                                                                                                                                                          |
| 403    | `plan_not_eligible`                                              |                                                                                                                                                          |
| 404    | `not_found`                                                      | Unknown project id, OR a project that exists but belongs to another workspace. We do not distinguish — see [conventions](./conventions.md#resource-ids). |
| 429    | `rate_limited`                                                   |                                                                                                                                                          |

***

## Cross-workspace isolation

Every project read is scoped by the API key's workspace. A request for
`proj_<other-workspace>` returns `404 not_found` — never a 403, so
attackers cannot enumerate which project ids exist outside their
workspace.

The same isolation applies to the list endpoint: you only see your own
workspace's projects, and the pagination cursor is bound to that filter.
You cannot inflate the result set by replaying another workspace's
cursor — the embedded `(createdAt, id)` keyset is workspace-agnostic, so
it just no-ops against your own data.

***

## What's NOT here (yet)

* **Filtering by status / type.** v1 returns all projects, regardless of
  status. Filter client-side. A `?status=` parameter will land in v1.1
  if there's demand.
* **Project metrics.** Engagement and analytics live behind the
  dashboard for now. Aggregated metrics endpoints are queued for
  Phase 4.
* **Write endpoints.** Creating, pausing, or archiving a project is
  dashboard-only in v1.