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

# Pharen Hub REST API reference: base URL and authentication

> Get started with the Pharen Hub REST API: base URL, Bearer token authentication, scopes, rate limits, and the interactive Mintlify playground.

The Pharen REST API lets trusted backend services, sync jobs, and internal tools work with your Pharen Hub workspace. The API reference uses Mintlify's interactive playground, so you can inspect request parameters, generate code examples, and try scoped API-key calls from the docs.

## Base URL

All API requests are made to the following base URL:

```bash theme={null}
https://pharen.app/api
```

Every endpoint in this reference is relative to this base. For example, the full URL for listing calendar events is `https://pharen.app/api/calendar/events/`.

Each endpoint page has a **Try it** panel. Set **Authorization** to your Bearer token, then use the **baseUrl** field in the request URL bar to choose the server you want to test.

For local testing, replace the default `https://pharen.app` value with `http://localhost:8000`. Include `http://` or `https://` so the playground can build a valid URL. Playground requests are sent directly from your browser, so your local backend must be running and allow requests from the docs site.

## Authentication

Create a scoped API key in **Settings -> API Keys**, then send it as a Bearer token:

```bash theme={null}
Authorization: Bearer phk_...
```

If your client cannot set an `Authorization` header, send the same key through `X-API-Key`.

<CardGroup cols={2}>
  <Card title="Create and scope keys" icon="key" href="/api-reference/api-keys">
    Learn how API key scopes, team targets, expiration, and rotation work.
  </Card>

  <Card title="List calendar events" icon="calendar" href="/api-reference/calendar/list-events">
    Try a read-only API-key request in the interactive playground.
  </Card>
</CardGroup>

## Request format

The API accepts JSON-encoded request bodies. For any request that includes a body (`POST`, `PUT`), you must set the `Content-Type` header to `application/json`.

```bash theme={null}
Content-Type: application/json
```

All path and query parameters should be URL-encoded where applicable.

## Response format

Every response from the API is JSON-encoded. Successful responses return the requested resource object or a list of resource objects. The `Content-Type` of all responses is `application/json`.

A typical single-resource response looks like this:

```json theme={null}
{
    "id": "2de9d72d-9077-4cb6-9836-5fc821cf1b71",
    "title": "Quarterly planning",
    "starts_at": "2026-07-03T09:00:00Z",
    "ends_at": "2026-07-03T10:00:00Z"
  }
```

List responses return an array of resource objects alongside pagination metadata:

```json theme={null}
{
  "data": [...],
  "total": 42,
  "page": 1,
  "per_page": 20
}
```

## HTTP status codes

The API uses standard HTTP status codes to communicate the outcome of every request.

| Code                        | Meaning                                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| `200 OK`                    | The request succeeded and the response body contains the result.                               |
| `201 Created`               | A new resource was created successfully. The response body contains the new resource.          |
| `204 No Content`            | The request succeeded and there is no response body (e.g., after a deletion).                  |
| `400 Bad Request`           | The request was malformed or missing required parameters. Check the error message for details. |
| `401 Unauthorized`          | The request did not include valid authentication credentials.                                  |
| `403 Forbidden`             | Your API key is valid but does not have permission to perform this action.                     |
| `404 Not Found`             | The requested resource does not exist or has been deleted.                                     |
| `422 Unprocessable Entity`  | The request was well-formed but contained semantic validation errors.                          |
| `500 Internal Server Error` | Something went wrong on Pharen's servers. If this persists, contact support.                   |

## Error objects

When a request fails (4xx or 5xx), the response body contains a structured error object to help you diagnose the problem:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The 'title' field is required.",
    "details": {
      "field": "title"
    }
  }
}
```

| Field           | Description                                                                        |
| --------------- | ---------------------------------------------------------------------------------- |
| `error.code`    | A machine-readable string identifying the error type.                              |
| `error.message` | A human-readable explanation of what went wrong.                                   |
| `error.details` | An optional object with additional context, such as which field failed validation. |

## Rate limiting

To ensure fair usage and platform stability, the API enforces rate limits on all endpoints. By default, your API key is limited to **1,000 requests per minute**.

When you exceed the rate limit, the API returns a `429 Too Many Requests` response. The response includes the following headers to help you manage your request cadence:

| Header                  | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| `X-RateLimit-Limit`     | The maximum number of requests allowed per minute.      |
| `X-RateLimit-Remaining` | The number of requests remaining in the current window. |
| `X-RateLimit-Reset`     | The Unix timestamp at which the current window resets.  |

<Warning>
  Implement exponential backoff in your integration when you receive `429` responses. Continuing to send requests at a high rate after being rate-limited may result in temporary suspension of your API key.
</Warning>

## Make your first request

Here's a minimal example that authenticates and retrieves calendar events:

```bash theme={null}
curl https://pharen.app/api/calendar/events/ \
  --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json"
```

Replace `YOUR_API_KEY` with the key you generate in the [Pharen Hub dashboard](https://pharen.app/settings/api). See [Authentication](/api-reference/authentication) and [API keys](/api-reference/api-keys) for the full setup flow.