Pharen Hub REST API reference: base URL and authentication

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:

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:

Authorization: Bearer phk_...

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

Create and scope keys

Learn how API key scopes, team targets, expiration, and rotation work.

List calendar events

Try a read-only API-key request in the interactive playground.

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.

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:

{
    "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:

{
  "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:

{
  "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.

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.

Make your first request

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

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. See Authentication and API keys for the full setup flow.

Overview

Calendar

Lists

Docs

Workflows

Agents

Pharen Hub REST API reference: base URL and authentication

Base URL

Authentication

Create and scope keys

List calendar events

Request format

Response format

HTTP status codes

Error objects

Rate limiting

Make your first request

​Base URL

​Authentication

Create and scope keys

List calendar events

​Request format

​Response format

​HTTP status codes

​Error objects

​Rate limiting

​Make your first request

Base URL

Authentication

Request format

Response format

HTTP status codes

Error objects

Rate limiting

Make your first request