# Tooltagger API

Multi-tenant REST API voor toolbeheer en inspecties. Authenticatie via API-keys (Bearer). Elke key is gescope't en gebonden aan één tenant. Server-to-server only. Elke response is JSON met een { data, meta }-envelope; lijsten zijn cursor-gepagineerd (limit max 200, meta.page.next\_cursor). Rate limit: 120 requests per minuut per key; daarboven volgt HTTP 429 met een Retry-After-header.

Snelstartbash

```
curl https://api.tooltagger.com/v1/tools \
  -H "Authorization: Bearer $TOOLTAGGER_API_KEY"
```

## Authenticatie

Elk request heeft een API-sleutel nodig. Die maak je aan in de applicatie onder **Developers** — zie [API-sleutel aanmaken](https://tooltagger.com/kennisbank/api/api-sleutel-aanmaken). De sleutel hoort bij één tenant en krijgt de scopes die je bij het aanmaken kiest, per resource los voor lezen en schrijven. De API is bedoeld voor server-naar-serververkeer; zet een sleutel nooit in een browser of app die je uitlevert.

Headerhttp

```
Authorization: Bearer <jouw-sleutel>
```

**Bewaar de sleutel als een wachtwoord.** Hij geeft toegang tot alle gegevens van je tenant binnen de gekozen scopes. Zet hem in een omgevingsvariabele of secret store, nooit in frontend-code of een repository. Vermoed je dat hij is uitgelekt? Trek hem in de applicatie in en maak een nieuwe aan — dat kan zonder de koppeling opnieuw op te zetten.

## Antwoordformaat

Elk antwoord is JSON in een `{ data, meta }`\-envelop. Lijsten zijn cursor-gepagineerd: geef `limit` mee (standaard 50, maximaal 200) en volg `meta.page.next_cursor` tot die leeg is. Filter incrementeel met `updated_since`, dan hoef je niet elke keer alles op te halen.

## Endpoints

Alles staat onder `https://api.tooltagger.com/v1`. De API draait in de EU (regio eu‑central‑1), net als de applicatie zelf.

| Endpoint | Wat het doet | Scopes |
| --- | --- | --- |
| [GET `/bulk_inspections`](https://tooltagger.com/api/bulk-inspections) | Lijst bulk-inspecties | — |
| [GET `/customers`](https://tooltagger.com/api/customers) | Lijst | — |
| [POST `/customers`](https://tooltagger.com/api/customers) | Maak | — |
| [DELETE `/customers/{id}`](https://tooltagger.com/api/customers-id) | Verwijder | — |
| [GET `/customers/{id}`](https://tooltagger.com/api/customers-id) | Haal op | — |
| [PATCH `/customers/{id}`](https://tooltagger.com/api/customers-id) | Werk bij | — |
| [GET `/inspections`](https://tooltagger.com/api/inspections) | Lijst inspecties | — |
| [POST `/inspections`](https://tooltagger.com/api/inspections) | Maak/werk inspectie bij | — |
| [GET `/inspections/{id}`](https://tooltagger.com/api/inspections-id) | Haal inspectie op | — |
| [POST `/stock/transactions`](https://tooltagger.com/api/stock-transactions) | Voorraadmutatie | — |
| [GET `/tools`](https://tooltagger.com/api/tools) | Lijst tools | — |
| [POST `/tools`](https://tooltagger.com/api/tools) | Maak tool | — |
| [DELETE `/tools/{id}`](https://tooltagger.com/api/tools-id) | Deactiveer tool | — |
| [GET `/tools/{id}`](https://tooltagger.com/api/tools-id) | Haal tool op | — |
| [PATCH `/tools/{id}`](https://tooltagger.com/api/tools-id) | Werk tool bij | — |
| [POST `/tools/{id}/status`](https://tooltagger.com/api/tools-id-status) | Wijzig toolstatus | — |

## Foutafhandeling

Fouten komen altijd terug in dezelfde envelop. Het `request_id` is uniek per aanroep — stuur dat mee als je support inschakelt, dan zoeken we het request op.

401 Unauthorizedjson

```
{
  "error": {
    "code": "invalid_api_key",
    "message": "Missing API key.",
    "request_id": "01fb3657-5ad6-474b-90eb-990af9296d0f"
  }
}
```

| Status | Code | Betekenis |
| --- | --- | --- |
| `401` | `invalid_api_key` | Geen sleutel meegestuurd (*Missing API key*), of de sleutel is onbekend, ingetrokken of verlopen (*Invalid or expired API key*). |

## Limieten en beschikbaarheid

De API is een losse module die je per tenant aan- en uitzet in de applicatie onder **Account › Abonnement**, voor €39 per maand. Staat de module uit, dan geeft elk request een `403` met `module_disabled`. Zie [Tarieven](https://tooltagger.com/tarieven).

Per sleutel geldt een limiet van **120 requests per minuut**. Ga je daaroverheen, dan krijg je een `429` met een `Retry-After`\-header — wacht dat aantal seconden af in plaats van meteen opnieuw te proberen. Daarnaast geldt per tenant een fair‑use limiet per maand; je verbruik zie je in de applicatie bij je sleutels. Loop je daar structureel tegenaan, neem dan contact op — dan zetten we de limiet hoger in plaats van je koppeling af te knijpen. Standaard staat dat quotum op 50.000 requests per maand voor alle sleutels van je tenant samen.

## Hoe deze pagina bijgewerkt wordt

Deze referentie wordt gegenereerd uit de OpenAPI-spec van de API zelf, niet met de hand bijgehouden. Deze build gebruikte de spec die in dit repo staat. Verandert er iets aan de API, dan verandert deze pagina mee bij de eerstvolgende build.

Loop je vast op een koppeling?

Mail [contact@tooltagger.com](mailto:contact@tooltagger.com) met het `request_id` uit de foutmelding, dan zoeken we het request voor je op.