Gidsen

Aan de slag met de Nubbo-API

Van nul naar je eerste request in een paar minuten. Maak een sleutel aan en beheer je opslag vanuit je eigen code.

De Nubbo-API is een REST-API om vanuit je eigen code met je buckets te werken: bestanden, mappen, links, inboxen, galerijen, labels, projecten en automatiseringen. In deze gids maak je een sleutel aan en doe je je eerste verzoeken met curl.

Wat je krijgt

  • Je Nubbo-ruimte beheren vanuit je programma’s, met sleutels die alleen zien wat jij kiest.
  • Rechtstreeks uploaden en downloaden tussen je code en je opslagprovider.
  • Reageren op nieuwe bestanden, uploads naar inboxen en activiteit met de triggers.

Voordat je begint

Je hebt een Nubbo-account met het Pro- of Teams-abonnement nodig en een terminal met curl. In een team maken de eigenaar of een beheerder de API-sleutels aan.

Stap 1: maak een sleutel aan

  1. Open in Nubbo Instellingen › API (of Team › API in een team) en klik op API-sleutel aanmaken.

  2. Geef hem een naam en kies:

    • Toegang: Alleen lezen of Lezen en schrijven.
    • Bereik: Hele ruimte of Gekozen buckets en projecten. De sleutel ziet alleen wat je hier kiest.
    • Vervaldatum: 30 dagen, 90 dagen, 1 jaar of Geen vervaldatum. Nubbo waarschuwt je 7 dagen van tevoren.

    Klik op Sleutel aanmaken. Nubbo vraagt je wachtwoord om te bevestigen dat jij het bent. Staat verificatie in twee stappen aan, dan vraagt Nubbo ook de code.

    Venster API-sleutel aanmaken met de toegang, het bereik en de vervaldatum Venster API-sleutel aanmaken met de toegang, het bereik en de vervaldatum
  3. Kopieer de sleutel en klik op Ik heb hem opgeslagen. Hij begint met nbk_ en dit is de enige keer dat je hem volledig ziet. Bewaar hem op de server of in de tool die hem gaat gebruiken, nooit in een webpagina.

    Venster Je API-sleutel met de sleutel klaar om te kopiëren Venster Je API-sleutel met de sleutel klaar om te kopiëren

Stap 2: je eerste verzoek

Stuur de sleutel mee in de header Authorization van elk verzoek. Begin met GET /v1/me, dat geen verzoeken verbruikt:

curl https://api.nubbo.app/v1/me \
  -H "Authorization: Bearer nbk_je_sleutel"

Het antwoord bevat je ruimte, je abonnement, het quotum van de maand en de sleutel met zijn toegang en bereik. Dit is een fragment:

{
  "workspace": { "id": "…", "name": "Studio Noord", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "Mijn eerste sleutel",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Toon daarna je buckets en de bestanden van een map:

curl https://api.nubbo.app/v1/buckets \
  -H "Authorization: Bearer nbk_je_sleutel"

curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=facturen/" \
  -H "Authorization: Bearer nbk_je_sleutel"

Lijsten geven data en nextCursor terug. Voor de volgende pagina stuur je die waarde mee in cursor. Als nextCursor null is, is er niets meer.

Terminal met het verzoek GET /v1/me en het antwoord Terminal met het verzoek GET /v1/me en het antwoord

Stap 3: de referentie

Klik in Instellingen › API op Documentatie bekijken, of open api.nubbo.app/v1/docs. Daar staat elke resource met zijn velden en voorbeelden. Het OpenAPI-document staat op api.nubbo.app/v1/openapi.json.

Referentie van de Nubbo-API met het voorbeeld in curl Referentie van de Nubbo-API met het voorbeeld in curl

Uploads en downloads

Bestanden gaan niet via Nubbo. Om er een te uploaden vraag je de upload aan met POST /v1/buckets/{bucketId}/uploads, stuur je het bestand naar het presigned adres dat je terugkrijgt en rond je af met POST /v1/uploads/{uploadId}/complete. Om te downloaden vraag je een link aan met POST /v1/files/{fileId}/download-link en download je het bestand bij je provider.

Limieten

ProTeams
Verzoeken per minuut per sleutel60120
Verzoeken per maand50.000100.000 + 10.000 per plaats
Trigger-events per maand20.00050.000 + 5.000 per plaats

Het quotum hoort bij de ruimte en wordt elke factuurperiode vernieuwd. GET /v1/me, de opvragingen van de triggers en de antwoorden 401, 429 en 5xx tellen niet als verzoeken. Elk event dat een trigger aflevert telt als event. Elk antwoord bevat de headers X-RateLimit-Remaining en X-Nubbo-Quota-Requests-Remaining, en in Instellingen › API zie je het gebruik van de periode.

API-gebruik van de periode in de instellingen van Nubbo API-gebruik van de periode in de instellingen van Nubbo

Als er iets misgaat

  • API_KEY_INVALID, API_KEY_REVOKED of API_KEY_EXPIRED: de sleutel is ongeldig, ingetrokken of verlopen. Controleer de header of maak een nieuwe sleutel aan.
  • API_PLAN_REQUIRED: de ruimte van de sleutel heeft geen API. Die zit in de abonnementen Pro en Teams.
  • API_KEY_READ_ONLY: de sleutel is alleen-lezen. Maak er een aan met Lezen en schrijven.
  • API_RATE_LIMITED: te veel verzoeken met deze sleutel. Wacht de seconden uit Retry-After af en probeer het opnieuw.
  • API_QUOTA_EXCEEDED: de ruimte heeft de limiet van de maand bereikt. details.resetsAt zegt wanneer die wordt vernieuwd.

Elke fout bevat een requestId. Vermeld die als je ons schrijft.

Meer over de Nubbo-API. Om hem zonder code te gebruiken, volg je de gids voor Zapier, die voor n8n of die voor Make. Om hem vanuit je AI-assistent te gebruiken, lees je hoe je Nubbo koppelt aan Claude, ChatGPT of Cursor.

Veelgestelde vragen

Bij welke abonnementen hoort de API?

Pro en Teams. Met Gratis of Personal antwoorden de verzoeken met API_PLAN_REQUIRED.

Kan ik versleutelde bestanden lezen met de API?

Nee. Versleutelde inhoud verschijnt zonder naam, pad, grootte of type en elke wijziging erop wordt geweigerd met API_ENCRYPTED_CONTENT.

Wat gebeurt er als ik een verzoek herhaal na een netwerkfout?

Stuur de header Idempotency-Key mee in je POST en PATCH. Gedurende 24 uur geeft hetzelfde verzoek het eerste antwoord terug en wordt er niets twee keer aangemaakt.

Verandert de API zonder waarschuwing?

Nee. Een wijziging die iets breekt komt als /v2 en /v1 blijft minstens 12 maanden bestaan, met de headers Deprecation en Sunset.

Bronnen

Stappen gecontroleerd met deze pagina's.