Readers and antennas

Method	Path	Does
GET	/readers	List readers and their health
PATCH	/readers/{id}	Start or stop a reader
DELETE	/readers/{id}	Remove a reader from your account
GET	/readers/{id}/antennas	A reader's four antenna ports
PUT	/readers/{id}/antennas	Map ports to zones and change RF settings
POST	/devices/claim	Claim a reader using the code on its box
GET	/devices	Readers your account has claimed

List readers

GET /readers

[
  {
    "id": "3c9a2f61-0e4b-4d7a-8f15-2b6c9d0e1a73",
    "name": "Goods In 1",
    "serial": "37025502846",
    "model": "R700",
    "firmware": "8.4.1",
    "status": "online",
    "enabled": true,
    "temperatureC": 48,
    "cpuPercent": 12,
    "memoryPercent": 41,
    "healthAt": "2026-10-10T14:02:50.000Z",
    "brokerStatus": "connected",
    "brokerStatusAt": "2026-10-10T06:30:12.000Z",
    "lastEventAt": "2026-10-10T14:03:21.000Z",
    "lastSeenAt": "2026-10-10T14:03:21.000Z",
    "commandsSupported": true,
    "lastCommand": {
      "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
      "kind": "start",
      "state": "applied",
      "createdAt": "2026-10-10T06:31:00.000Z",
      "settledAt": "2026-10-10T06:31:01.000Z"
    }
  }
]

Field
status	online, degraded, offline, disabled (stopped by someone), or unknown (never reported). See Readers.
enabled	false when someone has stopped the reader.
offlineReason	Present when the reader isn't online: never-connected, broker-disconnected, no-data, radio-idle or stopped.
brokerStatus	never, connected or disconnected: whether the reader's connection to Titan is open right now.
lastSeenAt	The latest sign of life of any kind.
lastEventAt	When tag data last arrived.
temperatureC, cpuPercent, memoryPercent, powerMilliwatts	Health figures, present when the reader reports them.
commandsSupported	Whether the reader has confirmed it can take Start/Stop commands.
lastCommand	The latest Start/Stop sent. state is pending, published, applied, failed or superseded.

The response also contains fields Titan uses internally to manage the reader (for example desiredConfig, controlPath and hostname). Don't rely on them, because they may change.

Start or stop a reader

PATCH /readers/{id}

{ "enabled": false }

false stops the radio and true starts it. Returns the updated reader. The command goes to the reader over its existing connection. Watch lastCommand.state change to applied to confirm the reader acted on it.

Remove a reader

DELETE /readers/{id}

Removes the reader from your account, with any open alerts about it. Tags it has read keep their data and history. Returns 204. Contact support before removing a reader you plan to keep using (see Readers).

Antennas

GET /readers/{id}/antennas

[
  {
    "id": "5e8b1a2c-3d4f-4a6b-8c9d-0e1f2a3b4c5d",
    "readerId": "3c9a2f61-0e4b-4d7a-8f15-2b6c9d0e1a73",
    "port": 1,
    "zoneId": "9d2e4f60-1a3b-4c5d-8e7f-6a5b4c3d2e10",
    "zoneName": "Receiving",
    "role": "coverage",
    "transmitPowerCdbm": 2700,
    "inventorySession": 2,
    "searchMode": "dual-target",
    "tagPopulation": 128,
    "enabled": true
  }
]

There's one entry per port, 1 to 4.

PUT /readers/{id}/antennas

Send an array with one object per port you want to change. Settings you leave out of an object are left unchanged, except zoneId and role: these are always set from what you send. Leave zoneId out (or send null) and the port becomes unmapped. Leave role out and it becomes coverage.

[
  { "port": 1, "zoneId": "9d2e4f60-1a3b-4c5d-8e7f-6a5b4c3d2e10", "transmitPowerCdbm": 2400 },
  { "port": 2, "zoneId": "9d2e4f60-1a3b-4c5d-8e7f-6a5b4c3d2e10" },
  { "port": 3, "zoneId": null, "enabled": false }
]

Field	Values
port	1 to 4. Required.
zoneId	A zone's id, or null to unmap.
role	coverage. The default, and the only role in use today.
transmitPowerCdbm	Transmit power in hundredths of a dBm, 1000 to 3300 (10.00 to 33.00 dBm). The default is 3000.
inventorySession	0 to 3. The default is 2.
searchMode	dual-target (default), single-target or single-target-with-tagfocus.
tagPopulation	Expected number of tags in view. The default is 128.
enabled	Whether the port is used.

The new settings are sent to the reader straight away. Returns the full antenna list. An unknown port or an out-of-range value returns 400, and nothing is changed.

Claim a reader

POST /devices/claim

{ "code": "TTN-7KQM-R4XW", "readerName": "Goods In 1" }

Adds a reader that shipped with a claim code to your account. Both fields are required. Returns 201 with the claimed device. Its readerId is the id you'll see in /readers.

Response	Meaning
201	Claimed. The reader appears in /readers.
404	The code isn't valid. That's also the answer for a code that has already been used, so codes can't be guessed.
409	That reader has been withdrawn. Contact support.

Claimed devices

GET /devices

Lists the readers your account has claimed, with serial, model, firmware, readerId, claimedAt and firstSeenAt. It's useful for confirming a claim went through.