Authentication
Every request to /v1 needs an API key of your company, sent as a Bearer token:
Authorization: Bearer mds_live_...
You create and revoke keys in the planner under Einstellungen → API-Schlüssel.
A key is shown only once, when it is created. A key can expire on a date you set;
otherwise it is valid until you revoke it. Without a key, or with a wrong,
expired or revoked one, the API answers 401.
Scopes
Each key has scopes that decide what it may do. read:… lets it read, write:…
lets it create, change and delete, and includes reading: every write answers with
the record it changed, so write:customers alone is enough to create customers
and read them back. A request without the scope it needs answers
403 insufficient_scope, and required in the answer names the scope.
| Data | Read | Write |
|---|---|---|
| Projects | read:projects | write:projects |
| Offers and offer requests | read:offers | write:offers |
| Customers | read:customers | write:customers |
| Materials | read:materials | write:materials |
| Manufacturers | read:manufacturers | write:manufacturers |
| Services | read:services | write:services |
| Company profile, team members and sites | read:company | write:company |
| Bookings and appointment types | read:bookings | write:bookings |
| Analytics | read:analytics | — |
| Documents and grid operators | read:documents | — |
You can only give a key scopes for things your own role in the planner allows you to do.
A few fields come from another area and need its scope as well. Without it they
are null, and everything else works:
- Bookings: the customer's phone, address, billing details and notes need
read:customers;plannerNameneedsread:company. - Document options: product names need
read:materials.
Whatever its scopes, a key only ever sees and changes the data of its own company.
Rate limits
There are no rate limits today. Every request is logged per key (you see them
under Einstellungen → API-Schlüssel), and limits may come later. So build
your client to wait and retry on a 429 answer, keep the number of requests
reasonable, and use webhooks instead of asking for changes again
and again.
Errors
| Status | error | Meaning |
|---|---|---|
| 400 | validation_error, invalid_sort | The body, a parameter or the sort field is not valid; message says what. |
| 401 | missing_api_key, invalid_api_key | No key, or a wrong, expired or revoked one. |
| 403 | insufficient_scope | The key lacks the scope named in required. |
| 404 | not_found | No such record in your company. |
| 409 | depends on the endpoint | Not possible in the record's current state; the endpoint lists its codes. |
| 500, 502 | db_error, booking_failed, … | Something failed on our side; message has the details. |