Conventions

The platform API is a JSON:API over HTTPS. Every endpoint follows the same conventions, so once you’ve made one request the rest are predictable.

Base URL

https://platform.tagbase.io/api/v1

All paths in this reference are relative to that base.

Content type

Send Content-Type: application/vnd.api+json on any request with a body — it’s the expected media type, and if you send a different one the request is rejected. (Omitting it is tolerated, but sending it is best practice.) Accept is optional; responses always come back as application/vnd.api+json regardless. If you do send Accept, use the same media type.

Content-Type: application/vnd.api+json

Request bodies are a single JSON:API document — a data object carrying a type and an attributes map:

{
  "data": {
    "type": "tags",
    "attributes": { "...": "..." }
  }
}

Identifiers

Every resource id is a URL-safe string with a type prefix (team_, key_, tag_, ses_, vrf_). The prefix identifies the resource type; treat the full string as opaque.

Errors

Errors come back as a JSON:API errors array. Each entry has an HTTP status and a short title:

{
  "errors": [
    { "status": "401", "title": "Unauthorized" }
  ]
}

The HTTP response status matches the status field. The statuses you’ll see:

Error bodies carry only status and title — there’s no detail or source pointer naming the attribute that failed. A 422 tells you the request was rejected, not which field to fix, so when one is unexpected, check your request against the relevant endpoint’s reference (for example, that a tag protocol is one of the supported values).

Idempotency

The API has no idempotency keys, and every POST creates a new resource each time it’s called. Retrying a request that already succeeded — after a timeout or a dropped connection — creates a duplicate: another batch of tags, another subteam, or another verification.

So retry deliberately. Treat a network-level failure (no response, a timeout) as “unknown”, not “failed”: before retrying a create, confirm on your side whether the first attempt actually landed, or accept and reconcile the possibility of a duplicate.

A response you did receive tells you what to do:

• 400, 401, 404 are definitive — the same request will fail the same way, so fix the request rather than retry it.
• 422 means nothing was recorded, so retrying the identical request is safe and won’t create a duplicate. A 422 that keeps recurring is a problem to escalate, not a transient blip.
• 201 succeeded — don’t resend it, or you’ll create a duplicate.

Rate limiting

Requests are throttled per client IP at 600 requests per minute across the API. Exceeding the limit returns a plain-text 429 Too Many Requests — not a JSON:API error document — and no rate-limit headers are sent, so there’s nothing to inspect ahead of time: back off and retry after a pause. The limit is generous for interactive traffic; batch work (like registering hundreds of tags) should pace itself rather than burst.

What the API does not have (yet)

Keeping this explicit so you don’t design around features that aren’t there:

• No list endpoints. Each resource can be retrieved individually by id — GET /tags/:id, GET /verifications/:id, and so on (see the “Retrieve a…” section on each resource’s page) — but there is no way to list, search, or paginate a collection. If you didn’t keep the id, you can’t find the resource again.
• Webhooks push event notifications (e.g. when a tag is written) to a URL you register. They’re the one place the platform calls you — see Webhooks. Scan verdicts still come back in the response to the verification request you made, not via a callback.
• No sandbox or test mode for verifications. A verification only succeeds against a tag that’s been written to a physical chip — one whose lifecycle has reached configured (see Tags). A freshly provisioned tag returns 404 until then, and there’s no API to simulate a scan or mint a pre-configured test tag. Exercising the verification path end to end means using real written hardware.

When you need to find a resource again later, store its id at the moment you receive it — the retrieve endpoints can re-fetch the rest. Verdicts and session ids are still yours to persist when they arrive.