Skip to content
Docs

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:

StatuserrorMeaning
400invalid_requestThe body or query failed validation
401unauthorizedMissing, malformed or revoked API key
402plan_limitThe Free plan limit was reached
404not_foundNo such resource, or it belongs to another host
409variousA conflict, such as a taken slot
429rate_limitedToo 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

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
emailstring (email)yes-
handlestringyes-
displayNamestringyes1–100 chars
timezonestringyesmin 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

FieldTypeRequiredDefault / limits
displayNamestringno1–100 chars
timezonestringno-
handlestringno-

Response 200

Body

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
emailstring (email)yes-
handlestringyes-
displayNamestringyes1–100 chars
timezonestringyesmin 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)

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
namestringyes-
prefixstringyes-
lastUsedAtstring (date-time) | nullyes-
createdAtstring (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

FieldTypeRequiredDefault / limits
namestringyes1–80 chars

Response 201

Body

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
namestringyes-
prefixstringyes-
lastUsedAtstring (date-time) | nullyes-
createdAtstring (date-time)yes-
keystringyes-

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

FieldTypeRequiredDefault / limits
idstringyes-

Response 204

No body.

Errors: not_found, unauthorized

curl -X DELETE "https://devalender.com/api/api-keys/<id>" \
  -H "Authorization: Bearer dvl_..."