Authentication
How to authenticate with the planni Public API using API keys.
Base URL
All API requests use the following base URL:
https://api.planni.de/v1API Keys
Every request must include an X-Api-Key header with a valid API key.
curl -H "X-Api-Key: your-api-key" https://api.planni.de/v1/contactsAPI keys are created in the planni admin under Settings > Integrations.
Scopes
Each API key can be assigned one or more scopes to restrict access:
| Scope | Description |
|---|---|
contacts:read | Read contacts |
contacts:write | Create and update contacts |
orders:read | Read orders |
events:read | Read event registrations |
webhooks:manage | Manage webhook subscriptions |
An API key with no scopes has full access (backward compatibility).
Pagination
List endpoints support pagination with limit and offset query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 25 | Max items to return (min 1) |
offset | integer | 0 | Items to skip |
curl -H "X-Api-Key: your-api-key" \
"https://api.planni.de/v1/contacts?limit=10&offset=20"Error Handling
The API returns standard HTTP status codes.
Error Responses
{
"error": "Unauthorized",
"message": "Missing or invalid API key"
}Status Codes
| Status | Meaning |
|---|---|
| 400 | Bad request (missing/invalid parameters) |
| 401 | Missing or invalid API key |
| 403 | Insufficient scope for this endpoint |
| 404 | Resource not found |
| 500 | Internal server error |
Rate Limiting
There are currently no rate limits enforced. This may change in future versions.