REST API
The base URL is https://devalender.com/api. Every endpoint is documented in the pages of this section: request, response, errors and a curl example. The schemas are rendered from the same definitions the API validates with, so they cannot drift from the code.
Authentication
Create a key in your dashboard settings and send it as a bearer token:
curl https://devalender.com/api/event-types \
-H "Authorization: Bearer dvl_..."Keys act as the host who created them and carry the same access as a dashboard login, for the endpoints documented here. A missing or revoked key returns 401 with the error unauthorized. Keys are included on every plan.
Endpoints marked Auth: none are public: slot lookups, the public profile, and booking or managing a booking with its manage token. Send no key to them from a browser.
First request
curl https://devalender.com/api/me \
-H "Authorization: Bearer dvl_..."Errors
Every error has the same JSON shape and a matching HTTP status:
{ "error": "invalid_request", "message": "start: Invalid input" }error is a stable machine-readable code; message is for humans and may change. Each endpoint lists the codes it can return. Common ones:
| Status | error | Meaning |
|---|---|---|
400 | invalid_request | The body or query failed validation |
401 | unauthorized | Missing, malformed or revoked API key |
402 | plan_limit | The Free plan limit was reached |
404 | not_found | No such resource, or it belongs to another host |
409 | various | A conflict, such as a taken slot |
429 | rate_limited | Too many requests; try again later |
Rate limits
There is no global per-key limit today. Specific public endpoints are limited and answer 429 with rate_limited; the demo host, for example, accepts 10 bookings per hour per IP address.
Pagination
List endpoints that can grow large, such as GET /bookings, return an items array and a nextCursor. Pass nextCursor back as cursor to get the next page; nextCursor is null on the last page. Cursors are opaque: do not build or parse them. limit is 1 to 200 (default 50) and order is asc or desc.
curl "https://devalender.com/api/bookings?limit=50&cursor=<nextCursor>" \
-H "Authorization: Bearer dvl_..."Timezones and instants
Every timestamp in a response is an ISO 8601 instant in UTC, such as 2030-01-07T10:00:00.000Z. Send instants with an offset (Z or +02:00). Slot lookups group slots by day in the tz you pass (an IANA name, default the host's timezone) and echo it back as timezone. Dates without a time, such as 2030-01-07, are accepted where a query takes from and to.
Account and API keys
GET /me
The authenticated host. Auth: API key.
Response 200
Body
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string (uuid) | yes | - |
email | string (email) | yes | - |
handle | string | yes | - |
displayName | string | yes | 1–100 chars |
timezone | string | yes | min 1 chars |
plan | "free" | "pro" | "teams" | yes | - |
Errors: unauthorized
curl -X GET "https://devalender.com/api/me" \
-H "Authorization: Bearer dvl_..."PATCH /me
Change display name, timezone or handle. Auth: API key.
Request body
| Field | Type | Required | Default / limits |
|---|---|---|---|
displayName | string | no | 1–100 chars |
timezone | string | no | - |
handle | string | no | - |
Response 200
Body
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string (uuid) | yes | - |
email | string (email) | yes | - |
handle | string | yes | - |
displayName | string | yes | 1–100 chars |
timezone | string | yes | min 1 chars |
plan | "free" | "pro" | "teams" | yes | - |
Errors: invalid_request, handle_taken, unauthorized
curl -X PATCH "https://devalender.com/api/me" \
-H "Authorization: Bearer dvl_..." \
-H "Content-Type: application/json" \
-d '{"displayName":"string"}'GET /api-keys
List API keys. Auth: API key.
Response 200
Body (array of objects)
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string (uuid) | yes | - |
name | string | yes | - |
prefix | string | yes | - |
lastUsedAt | string (date-time) | null | yes | - |
createdAt | string (date-time) | yes | - |
Errors: unauthorized
curl -X GET "https://devalender.com/api/api-keys" \
-H "Authorization: Bearer dvl_..."POST /api-keys
Create an API key; the key is shown once. Auth: API key.
Request body
| Field | Type | Required | Default / limits |
|---|---|---|---|
name | string | yes | 1–80 chars |
Response 201
Body
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string (uuid) | yes | - |
name | string | yes | - |
prefix | string | yes | - |
lastUsedAt | string (date-time) | null | yes | - |
createdAt | string (date-time) | yes | - |
key | string | yes | - |
Errors: invalid_request, unauthorized
curl -X POST "https://devalender.com/api/api-keys" \
-H "Authorization: Bearer dvl_..." \
-H "Content-Type: application/json" \
-d '{"name":"string"}'DELETE /api-keys/:id
Revoke an API key. Auth: API key.
Path parameters
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string | yes | - |
Response 204
No body.
Errors: not_found, unauthorized
curl -X DELETE "https://devalender.com/api/api-keys/<id>" \
-H "Authorization: Bearer dvl_..."