Docs

First request

1. 1. Add prepaid funds. Top up from Billing. The first accepted write costs $0.001 plus transfer if the request exceeds 1 MB.
2. 2. Create a Collection. Copy its public UUID. Leave it active — a paused collection rejects writes with 403.
3. 3. Pick an API. Use a private nib_sk_* key from your server to read and write. Use a public nib_pk_* token only for browser write-only ingest.
4. 4. POST a JSON object. A successful create returns 201 with the stored record. Copy X-Nibbleful-Request-Id if anything fails — it matches a row in Activity.

Private API

Server-side only. Never put a nib_sk_* key in frontend code. Keys are granted per collection. A key with no collection permissions cannot read or write — the API returns collection_not_found. Permissions cannot be edited later; revoke the key and create a new one. The plaintext secret is shown once at creation.

Endpoints

POST https://nibbleful.com/api/v1/collections/:collection_id/records
GET  https://nibbleful.com/api/v1/collections/:collection_id/records
GET  https://nibbleful.com/api/v1/collections/:collection_id/records/:record_id

Auth

Authorization: Bearer nib_sk_test_...

WRITE is required to POST. READ is required to GET. Test tokens start with nib_sk_test_; production tokens start with nib_sk_live_.

Create

curl -X POST https://nibbleful.com/api/v1/collections/COLLECTION_ID/records \
  -H "Authorization: Bearer nib_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","source":"website"}'

Success body

{
  "id": "01j...",
  "created_at": "2026-09-17T20:00:00.000Z",
  "data": { "email": "[email protected]", "source": "website" }
}

List

Newest first. limit defaults to 50 and maxes at 100. Pass a record id as before or after to page.

{
  "data": [ { "id": "...", "created_at": "...", "data": {} } ],
  "pagination": { "next": "01j...", "previous": null }
}

Public ingest

Write-only ingest from the browser. Enable it on the collection, then send X-Nibbleful-Token with the collection’s nib_pk_* token. The token is not a secret and is not authentication by itself. It cannot read, query, or delete data.

Endpoint

POST https://nibbleful.com/public/v1/collections/:collection_id/records

CORS allows POST and OPTIONS. Allowed request headers: Content-Type, Accept, X-Nibbleful-Token, X-Nibbleful-Turnstile-Token.

Browser example

const response = await fetch(
  "https://nibbleful.com/public/v1/collections/COLLECTION_ID/records",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Nibbleful-Token": "nib_pk_test_..."
    },
    body: JSON.stringify({
      email: "[email protected]"
    })
  }
);

Public ingest checks run in this order: collection exists, ingest enabled, token valid, not paused, payload size, JSON object, origin, rate limit, Turnstile, honeypot, duplicate, daily spend, then balance. A later failure can still happen after an earlier check has already recorded state — see duplicate protection below.

Collection states

Public ingest protections

These apply only to /public/v1. Rejected requests are free. Configure them on the collection Settings tab.

Pricing

• Accepted API requests cost $0.001.
• The first 1 MB of transfer (bytes in + bytes out) is included per accepted request. Each started additional MB is $0.001.
• Storage is $1/GB-month based on retained byte-time, billed monthly per collection, rounded down to $0.001.
• Rejected requests, dashboard browsing, and exports are not billed as API usage.
• Top-ups are $5–$100. Optional auto top-up charges a saved card when balance is low; the credit appears after Stripe confirms.

Errors

Failures return JSON. Read error.code, not only the HTTP status — several protections share 403.

{
  "error": {
    "code": "collection_paused",
    "message": "This collection is paused."
  }
}

Debugging

• Every API response includes X-Nibbleful-Request-Id. Open Activity and search that id.
• Activity shows outcome, rejection reason, and public ingest protection results (token, origin, Turnstile, honeypot, duplicate, spend cap).
• If the browser shows 403, check whether the collection is paused before assuming the public token is wrong.
• If you see 402 then 409 on the same body, add funds and wait 60 seconds or change the payload. Duplicate protection already claimed the first attempt.
• Dashboard record lists and CSV/JSON exports do not consume API credit.