Tags

A tag is the dynamic NFC identity bound to a physical item. You provision tags under a team; later, each tag is written onto a physical chip and, once in the field, scanned to produce verifications.

Two ways to get physical tags

Preconfigured by TAGBASE — the default, and what most teams use. Order tags and we ship them written and ready to scan: apply them and they work. We make sure the chips always match the protocol you provision.
Written by you — for testing, experimenting, and small batches. Provision tags through this API, then write them onto blank chips with the TAGBASE Writer app. Sourcing compatible blank chips is up to you — the platform only supports the chips listed under protocol.

Fields

Field	Type	Notes
`id`	string	`tag_`-prefixed, assigned by the platform and returned at creation.
`protocol`	string	Required at creation. The tag protocol to provision (see below).
`url`	string	Required at creation. The address written to the chip and opened when the tag is scanned. You choose it.
`comment`	string	Optional, max 50 characters. A human-readable label. Makes it easy to see what any tag is at a glance, e.g. a product name. Writer apps can display it to identify which physical item a tag belongs to.
`session_duration`	integer	Optional, defaults to `600`. How long a session on this tag stays open between its first and second scan, in seconds (`1` to `3600`).
`status`	string	Lifecycle state (see below). Returned when you retrieve a tag.
`configured_at`	string	ISO 8601 timestamp when the tag was written to a chip, or `null`. Returned when you retrieve a tag.
`inserted_at`	string	ISO 8601 timestamp when the tag was provisioned.

A tag also carries a lifecycle status that advances as the tag is manufactured:

Status	Meaning
`created`	Provisioned in the platform; not yet written to a chip.
`configured`	Written to a chip and ready to be scanned in the field.

A tag can only be verified once it reaches configured. Before that it has no chip behind it, so a scan against it returns 404 (see Verifications).

The `protocol` attribute

protocol selects which tag protocol the chip uses. The currently supported values are:

Value	Chip
`ntag_424_dna`	NTAG 424 DNA
`ntag_223_dna`	NTAG 223 DNA

Use the identifier (left column) as the protocol value. Any other value is rejected with 422.

The `url` attribute

url is the address written onto the chip and opened when the tag is scanned: your verification landing page. You choose it freely: it can live on your own custom domain, in whatever shape you like. The platform writes exactly what you provide and enforces no format.

The platform assigns the id, so the URL can’t contain it. Keep your own mapping from each url you send to the id returned for it, or read the pairs back later with List tags.

Create tags

POST /api/v1/tags

Provision a batch of tags under the team whose key you present. Send a protocol and url for each; the platform assigns an id and returns it. Tags are stored in created status, and each one fires a tag.created webhook.

Request

A JSON:API array under data, 1 to 500 resources per request. Each entry:

Member	Type	Required	Notes
`attributes.protocol`	string	yes	The tag protocol identifier.
`attributes.url`	string	yes	The address to write to the chip. You choose it.
`attributes.comment`	string	no	A human-readable label, max 50 characters.
`attributes.session_duration`	integer	no	Session window in seconds, `1` to `3600`. Defaults to `600` (10 minutes).

{
  "data": [
    {
      "type": "tags",
      "attributes": {
        "protocol": "ntag_424_dna",
        "url": "https://zannatherapeutics.com/verify/lonafen/8a3f9c2b"
      }
    }
  ]
}

curl https://platform.tagbase.io/api/v1/tags \
  -X POST \
  -H "Authorization: Bearer $TAGBASE_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{ "data": [ { "type": "tags", "attributes": { "protocol": "ntag_424_dna", "url": "https://zannatherapeutics.com/verify/lonafen/8a3f9c2b" } } ] }'

const res = await fetch("https://platform.tagbase.io/api/v1/tags", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TAGBASE_API_KEY}`,
    "Content-Type": "application/vnd.api+json",
  },
  body: JSON.stringify({
    data: [
      {
        type: "tags",
        attributes: {
          protocol: "ntag_424_dna",
          url: "https://zannatherapeutics.com/verify/lonafen/8a3f9c2b",
        },
      },
    ],
  }),
});
const tags = (await res.json()).data;

$response = $client->post("https://platform.tagbase.io/api/v1/tags", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("TAGBASE_API_KEY"),
        "Content-Type"  => "application/vnd.api+json",
    ],
    "json" => [
        "data" => [[
            "type" => "tags",
            "attributes" => [
                "protocol" => "ntag_424_dna",
                "url"      => "https://zannatherapeutics.com/verify/lonafen/8a3f9c2b",
            ],
        ]],
    ],
]);
$tags = json_decode((string) $response->getBody(), true)["data"];

tags =
  Req.post!("https://platform.tagbase.io/api/v1/tags",
    headers: [
      {"authorization", "Bearer #{System.fetch_env!("TAGBASE_API_KEY")}"},
      {"content-type", "application/vnd.api+json"}
    ],
    json: %{
      data: [
        %{
          type: "tags",
          attributes: %{
            protocol: "ntag_424_dna",
            url: "https://zannatherapeutics.com/verify/lonafen/8a3f9c2b"
          }
        }
      ]
    }
  ).body["data"]

Response: `201 Created`

A JSON:API array of the created tags. Each entry pairs the platform-assigned id with the url it was created from, so you can map them back to your records.

{
  "data": [
    {
      "type": "tags",
      "id": "tag_abcdef0123456789",
      "attributes": {
        "url": "https://zannatherapeutics.com/verify/lonafen/8a3f9c2b",
        "comment": null,
        "session_duration": 600,
        "status": "created",
        "configured_at": null,
        "inserted_at": "2026-06-07T09:00:00.000000Z"
      }
    }
  ]
}

Tags are returned in created status. Writing them onto physical chips happens separately and asynchronously; your integration holds the ids in the meantime and learns when each tag advances through webhooks: tag.configured when it’s written and ready to scan, tag.configuration_failed if a write fails.

Errors

Status	When
`400`	`data` is not an array of 1 to 500 entries, or any entry is missing `protocol` or `url`.
`401`	Missing, invalid, or revoked key.
`422`	Validation failed, e.g. a duplicate `url` or an unrecognized `protocol`.

Retrieve a tag

GET /api/v1/tags/:id

Fetch a tag you provisioned, including its current lifecycle status. The key you present must own the tag, or the platform responds 404.

curl https://platform.tagbase.io/api/v1/tags/tag_abcdef0123456789 \
  -H "Authorization: Bearer $TAGBASE_API_KEY" \
  -H "Accept: application/vnd.api+json"

const res = await fetch(
  "https://platform.tagbase.io/api/v1/tags/tag_abcdef0123456789",
  {
    headers: {
      "Authorization": `Bearer ${process.env.TAGBASE_API_KEY}`,
      "Accept": "application/vnd.api+json",
    },
  },
);
const tag = await res.json();

$response = $client->get("https://platform.tagbase.io/api/v1/tags/tag_abcdef0123456789", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("TAGBASE_API_KEY"),
        "Accept"        => "application/vnd.api+json",
    ],
]);
$tag = json_decode((string) $response->getBody(), true);

tag =
  Req.get!("https://platform.tagbase.io/api/v1/tags/tag_abcdef0123456789",
    headers: [
      {"authorization", "Bearer #{System.fetch_env!("TAGBASE_API_KEY")}"},
      {"accept", "application/vnd.api+json"}
    ]
  ).body

Response: `200 OK`

{
  "data": {
    "type": "tags",
    "id": "tag_abcdef0123456789",
    "attributes": {
      "url": "https://zannatherapeutics.com/verify/lonafen/8a3f9c2b",
      "comment": "Lonafen 50mg",
      "session_duration": 600,
      "status": "configured",
      "configured_at": "2026-06-08T12:34:56.123456Z"
    }
  }
}

Polling this endpoint is a fallback for tracking a tag’s lifecycle; webhooks are the push alternative and fire as the tag advances.

Errors

Status	When
`401`	Missing, invalid, or revoked key.
`404`	No such tag under your team.

Update a tag

PATCH /api/v1/tags/:id

Update a tag’s mutable attributes. The comment and session_duration are always editable: they live only in the platform, not on the chip. The url can only change while the tag is still created; once configured it is physically on the chip and locked, and a url change responds 422.

Request

A single JSON:API resource under data:

{
  "data": {
    "type": "tags",
    "id": "tag_abcdef0123456789",
    "attributes": { "comment": "Lonafen 50mg" }
  }
}

curl https://platform.tagbase.io/api/v1/tags/tag_abcdef0123456789 \
  -X PATCH \
  -H "Authorization: Bearer $TAGBASE_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{ "data": { "type": "tags", "id": "tag_abcdef0123456789", "attributes": { "comment": "Lonafen 50mg" } } }'

const res = await fetch(
  "https://platform.tagbase.io/api/v1/tags/tag_abcdef0123456789",
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${process.env.TAGBASE_API_KEY}`,
      "Content-Type": "application/vnd.api+json",
    },
    body: JSON.stringify({
      data: {
        type: "tags",
        id: "tag_abcdef0123456789",
        attributes: { comment: "Lonafen 50mg" },
      },
    }),
  },
);
const tag = await res.json();

$response = $client->patch("https://platform.tagbase.io/api/v1/tags/tag_abcdef0123456789", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("TAGBASE_API_KEY"),
        "Content-Type"  => "application/vnd.api+json",
    ],
    "json" => [
        "data" => [
            "type"       => "tags",
            "id"         => "tag_abcdef0123456789",
            "attributes" => ["comment" => "Lonafen 50mg"],
        ],
    ],
]);
$tag = json_decode((string) $response->getBody(), true);

tag =
  Req.patch!("https://platform.tagbase.io/api/v1/tags/tag_abcdef0123456789",
    headers: [
      {"authorization", "Bearer #{System.fetch_env!("TAGBASE_API_KEY")}"},
      {"content-type", "application/vnd.api+json"}
    ],
    json: %{
      data: %{
        type: "tags",
        id: "tag_abcdef0123456789",
        attributes: %{comment: "Lonafen 50mg"}
      }
    }
  ).body

Response: `200 OK`

The updated tag, in the same shape as Retrieve a tag.

Errors

Status	When
`400`	The body is not a single JSON:API resource with `attributes`.
`401`	Missing, invalid, or revoked key.
`404`	No such tag under your team.
`422`	Validation failed, e.g. the `url` of a `configured` tag, a duplicate `url`, a `comment` over 50 characters, or a `session_duration` outside `1` to `3600`.

GET /api/v1/tags

List the tags belonging to the team whose key you present, newest first. Use it to recover ids you didn’t store, or to reconcile a batch after a create you aren’t sure landed.

Query parameters

Parameter	Type	Notes
`page`	integer	1-based page number. Defaults to `1`.
`page_size`	integer	Tags per page. Defaults to `10`, maximum `100`. Ask for more and you get 100 back.
`q`	string	Search. Matches a tag `comment`, or an exact tag id.

curl "https://platform.tagbase.io/api/v1/tags?page=1&page_size=100" \
  -H "Authorization: Bearer $TAGBASE_API_KEY" \
  -H "Accept: application/vnd.api+json"

const res = await fetch(
  "https://platform.tagbase.io/api/v1/tags?page=1&page_size=100",
  {
    headers: {
      "Authorization": `Bearer ${process.env.TAGBASE_API_KEY}`,
      "Accept": "application/vnd.api+json",
    },
  },
);
const { data, meta } = await res.json();

$response = $client->get("https://platform.tagbase.io/api/v1/tags", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("TAGBASE_API_KEY"),
        "Accept"        => "application/vnd.api+json",
    ],
    "query" => ["page" => 1, "page_size" => 100],
]);
$page = json_decode((string) $response->getBody(), true);

page =
  Req.get!("https://platform.tagbase.io/api/v1/tags",
    params: [page: 1, page_size: 100],
    headers: [
      {"authorization", "Bearer #{System.fetch_env!("TAGBASE_API_KEY")}"},
      {"accept", "application/vnd.api+json"}
    ]
  ).body

Response: `200 OK`

A JSON:API array of tags, in the same shape as Retrieve a tag, plus a meta object describing the page.

{
  "data": [
    {
      "type": "tags",
      "id": "tag_abcdef0123456789",
      "attributes": {
        "url": "https://zannatherapeutics.com/verify/lonafen/8a3f9c2b",
        "comment": "Lonafen 50mg",
        "session_duration": 600,
        "status": "configured",
        "configured_at": "2026-06-08T12:34:56.123456Z",
        "inserted_at": "2026-06-07T09:00:00.000000Z"
      }
    }
  ],
  "meta": {
    "total_count": 1,
    "page": 1,
    "page_size": 100
  }
}

Walk the pages until you have total_count tags. The order holds across pages, so a tag never lands on two of them. The list is live, though: tags you create while paging arrive at the front and push the later pages along.

Errors

Status	When
`401`	Missing, invalid, or revoked key.

Notes

The list covers the team whose key you present, and nothing below it. To read a subteam’s tags, present that subteam’s own key.
Tags belong to the team whose key created them. To keep tenants isolated, create each tenant’s tags with that tenant’s subteam key.

Two ways to get physical tags

Fields

The protocol attribute

The url attribute

Create tags

Request

Response: 201 Created

Errors

Retrieve a tag

Response: 200 OK

Errors

Update a tag

Request

Response: 200 OK

Errors

List tags

Query parameters

Response: 200 OK

Errors

Notes

The `protocol` attribute

The `url` attribute

Response: `201 Created`

Response: `200 OK`

Response: `200 OK`

Response: `200 OK`