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

# API overview

> Spec, base URL, errors and versioning for the Private Clubs API

Private Clubs has a read-only REST API over its directory. A live OpenAPI spec describes it.

## Spec URL

```text theme={"system"}
https://www.theprivateclubs.com/openapi.json
```

Base URL:

```text theme={"system"}
https://www.theprivateclubs.com
```

The spec follows OpenAPI 3.0.0 and is at version 1.2.0. It describes more paths than these docs cover. Build on the one endpoint below.

## Endpoint

The supported endpoint is `GET /api/v1/clubs`. It searches the directory by type, place, name and waitlist status, with paging. The [API quickstart](/api) walks through each filter, and the [Search clubs](/api-reference/clubs/search-clubs) page, generated from the spec, lists each parameter and response field the spec describes.

Any other path under `/api/v1/`, such as `/api/v1/foo`, returns a 404 with code `not_found`:

```json theme={"system"}
{
  "type": "https://www.theprivateclubs.com/problems/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "This /api/v1 path does not exist.",
  "code": "not_found",
  "hint": "Use GET /api/v1/clubs or read https://www.theprivateclubs.com/openapi.json",
  "instance": "/api/v1"
}
```

## Call it from your server

The API sends no CORS headers, so a browser page on another origin cannot read its responses. Call it from your server, a serverless function or a script. The MCP server at `https://www.theprivateclubs.com/api/mcp` allows any origin.

## Errors

Errors follow RFC 9457 and use the `application/problem+json` content type. Every error body has these fields:

| Field | What it holds |
| - | - |
| `type` | A URL that names the problem, `https://www.theprivateclubs.com/problems/{code}`. It opens a page that explains the code. |
| `title` | A short summary of the problem. |
| `status` | The HTTP status code. |
| `detail` | What went wrong with this request. |
| `code` | A stable code to branch on. |
| `hint` | How to fix the request. |
| `instance` | The path you called. For an unknown `/api/v1` path, it is `/api/v1`. |

The codes:

| Code | Status | When |
| - | - | - |
| `invalid_page` | 400 | `page` is not a whole number from 1, such as `abc`, `0` or `-1`. An empty `page=` counts as not sent. |
| `invalid_limit` | 400 | `limit` is not a whole number from 1, such as `abc` or `0`. An empty `limit=` counts as not sent. |
| `not_found` | 404 | The `/api/v1` path does not exist. |
| `clubs_unavailable` | 500 | The directory could not be read. |

[https://www.theprivateclubs.com/problems](https://www.theprivateclubs.com/problems) lists every code, and each code has its own page, such as `/problems/invalid_page`.

Retry `clubs_unavailable` after a short wait. If it keeps failing, email [support@theprivateclubs.com](mailto:support@theprivateclubs.com), as its `hint` says. A page past the last one is not an error: it answers 200 with an empty `clubs` array. The [quickstart](/api#4-page-through-results) shows when to stop.

## Response headers

`GET /api/v1/clubs` sends these headers on every response:

| Header | What it holds |
| - | - |
| `X-Request-Id` | A new ID for each request: `req_` followed by 16 hex characters, such as `req_0123456789abcdef`. |
| `RateLimit` and `RateLimit-Policy` | The advertised rate limit policy. See [Pricing and limits](/api/usage-limits#rate-limit-headers). |

Successful responses also carry `X-Total-Clubs` (the same number as `total`), `X-Data-Source: Private Clubs` and `Cache-Control: private, no-store`.

## Versioning

The current version is v1, in the URL path. The spec states the policy:

> Breaking changes ship under a new /api/vN path. Deprecated versions send Deprecation and Sunset headers for at least 90 days.

## What you can do with the spec

* Generate a typed client for your language.
* Import it into an API tool such as Postman or Insomnia.
* Give it to an AI agent that writes code against the API.

Download it with:

```bash theme={"system"}
curl -o clubs-openapi.json https://www.theprivateclubs.com/openapi.json
```

Next: [Authentication and fees](/api/authentication), [Pricing and limits](/api/usage-limits) and the [club object](/reference/club-object).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.