> For the complete documentation index, see [llms.txt](https://developers.memberspace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.memberspace.com/admin-api/overview.md).

# Overview

The MemberSpace **Admin API** gives you programmatic, read-only access to your site's data for analytics, reporting, and custom workflows.

{% hint style="info" %}
*Access to the API is limited to customers on higher tier paid plans and currently in beta. If you would like to request access please email **<support@memberspace.com>**.*&#x20;
{% endhint %}

### Base URL

```http
https://api.memberspace.com/admin/v1
```

All endpoints are relative to this base. The version (`v1`) is part of the path; breaking changes ship under a new version.

### Authentication

The API uses bearer-token authentication. Generate an API key in your MemberSpace admin backend, where you can scope it to the data it's allowed to read.

Keys are opaque and prefixed with `ms_admin_`. Send the key on every request:

```http
Authorization: Bearer ms_admin_...
```

A request with a missing, unknown, revoked, or expired key returns `401` with an `accessDenied` error. Treat keys like passwords — store them server-side and never expose them in client-side code.

### Scopes

Each key is limited to the scopes you grant it when you create it. A request that needs a scope the key doesn't have returns `404` (see Errors). Current read scopes:

| Scope                | Grants                       |
| -------------------- | ---------------------------- |
| `read.plans`         | Read access to plans         |
| `read.members`       | Read access to members       |
| `read.content_views` | Read access to content views |

### Pagination

List endpoints use forward-only, cursor-based pagination via HTTP headers.

**Request Headers**

| Header          | Description                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Cursor`      | Where to start. Omit for the first page; otherwise pass the previous response's `X-Next-Cursor`. Cursors are opaque — don't parse or construct them. |
| `X-Items-After` | Page size, 1–100 (default 25).                                                                                                                       |

**Response Headers**

| Header                   | Description                                                                 |
| ------------------------ | --------------------------------------------------------------------------- |
| `X-Has-More-Items-After` | `true` if more results follow this page.                                    |
| `X-Next-Cursor`          | Cursor for the next page. Omitted when `X-Has-More-Items-After` is `false`. |

To page through a collection: make the first request without `X-Cursor`, then keep passing the returned `X-Next-Cursor` until `X-Has-More-Items-After` is `false`.

### Responses

Resources are returned as flat JSON with `camelCase` keys. List endpoints return a JSON **array** of objects (there is no envelope or `meta` wrapper); null fields are omitted rather than returned as `null`.

### Errors

The API uses standard HTTP status codes — `2xx` for success, `4xx` for client errors. Error responses always have an `errors` key containing an **array** of error objects:

```json
{
  "errors": [
    {
      "path": "base",
      "code": "accessDenied",
      "message": "Access denied."
    }
  ]
}
```

| Field     | Description                                                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `path`    | `base` for errors not tied to a specific field; otherwise the dotted path of the offending field (e.g. `community.isEnabled`). |
| `code`    | Machine-readable error code — branch on this, not on `message`.                                                                |
| `message` | Human-readable description.                                                                                                    |

Common statuses and codes:

| Status | Code            | Meaning                                                             |
| ------ | --------------- | ------------------------------------------------------------------- |
| `400`  | `invalidCursor` | The `X-Cursor` value is malformed                                   |
| `401`  | `accessDenied`  | Missing, invalid, or unknown API key                                |
| `404`  | `notFound`      | The resource doesn't exist, or the key lacks the scope to access it |
| `429`  | `rateLimited`   | Too many requests — see the `Retry-After` header                    |

### Rate Limits

When you exceed the rate limit, the API returns `429` with a `rateLimited` error and a `Retry-After` header indicating how many seconds to wait before retrying. Back off for at least that long.

### Support

Questions or feedback during beta? Email **<support@memberspace.com>**.