Skip to main content
The Pharen REST API gives you programmatic access to every resource in your Pharen Hub workspace. Whether you’re building internal tooling, automating content workflows, or integrating Pharen into a larger platform, the API provides a consistent, predictable interface built on standard HTTP conventions.

​
Base URL

All API requests are made to the following base URL: 
https://api.pharen.de/v1
Every endpoint in this reference is relative to this base. For example, the full URL for listing pages is https://api.pharen.de/v1/new-page.

​
Versioning

The current API version is v1, reflected in the base URL path. When Pharen introduces breaking changes, a new version will be released under a new path prefix (e.g., /v2/). Your existing integrations will continue to work on /v1/ until the version is formally deprecated, at which point you’ll receive advance notice.
Non-breaking additions — such as new optional request parameters or new fields in response objects — may be added to existing endpoints at any time without a version bump. Write your integration to gracefully ignore unknown fields.

​
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": "page_01hx9k2m3nqvw4e5r6t7y8u9p",
  "title": "Getting Started Guide",
  "content": "Welcome to Pharen Hub...",
  "created_at": "2024-06-01T12:00:00Z",
  "updated_at": "2024-06-01T12: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.
CodeMeaning
200 OKThe request succeeded and the response body contains the result.
201 CreatedA new resource was created successfully. The response body contains the new resource.
204 No ContentThe request succeeded and there is no response body (e.g., after a deletion).
400 Bad RequestThe request was malformed or missing required parameters. Check the error message for details.
401 UnauthorizedThe request did not include valid authentication credentials.
403 ForbiddenYour API key is valid but does not have permission to perform this action.
404 Not FoundThe requested resource does not exist or has been deleted.
422 Unprocessable EntityThe request was well-formed but contained semantic validation errors.
500 Internal Server ErrorSomething 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"
    }
  }
}
FieldDescription
error.codeA machine-readable string identifying the error type.
error.messageA human-readable explanation of what went wrong.
error.detailsAn 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:
HeaderDescription
X-RateLimit-LimitThe maximum number of requests allowed per minute.
X-RateLimit-RemainingThe number of requests remaining in the current window.
X-RateLimit-ResetThe 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.

​
Making Your First Request

Here’s a minimal example that authenticates and retrieves your list of pages: 
curl https://api.pharen.de/v1/new-page \
  --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 the Authentication page for full details on obtaining and using API keys.