Entities
Creates an entity, or updates it if one with the same id already exists in your organisation. On an update, the kind you send replaces the stored one and attributes are merged into what's there. Returns the entity as stored.
See Entities and the graph for what each kind represents.
Request body
customer, account, wallet, device, agent or counterparty.Example
curl -X POST "$SENTINEL_URL/v1/entities" \
-H "Authorization: Bearer $SENTINEL_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "cus_10442",
"kind": "customer",
"attributes": {
"name": "Test Customer",
"date_of_birth": "1990-04-12",
"kyc_result": "verified",
"risk_tier": "standard"
}
}'
{
"id": "cus_10442",
"kind": "customer",
"attributes": {
"name": "Test Customer",
"date_of_birth": "1990-04-12",
"kyc_result": "verified",
"risk_tier": "standard"
},
"created_at": "2026-10-15T09:14:03.512Z",
"updated_at": "2026-10-15T09:14:03.512Z"
}
A wallet looks the same with a different kind:
{
"id": "wal_8812",
"kind": "wallet",
"attributes": {
"operator": "Example Mobile Money",
"opened_at": "2026-10-12"
}
}
Response fields
| Field | Type | Meaning |
|---|---|---|
id | string | Your ID |
kind | string | The entity kind |
attributes | object | Attributes as stored |
created_at | string, date-time | When Sentinel first saw this entity |
updated_at | string, date-time | When it was last changed |
Errors
| Code | error |
|---|---|
400 | id is required |
400 | unknown kind |
401 | missing or invalid API key |
List entities
GET /v1/entitiesEntities in your organisation, most recently changed first. Lists come a page at a time, newest first. Pass limit (1 to 200, default 50); if there are more, the response has a next_cursor. Send it back as cursor for the next page. Cursors are opaque and keep their place even while new rows arrive.
| Parameter | Meaning |
|---|---|
kind | Only this kind. Placeholders are left out, since their kind is unknown |
q | Part of the id or of the name attribute, in any case |
limit, cursor | Paging, as above |
{
"entities": [
{
"id": "wal_8812",
"kind": "wallet",
"attributes": {
"name": "Ama Mensah"
},
"registered": true,
"open_alerts": 1,
"last_seen": "2026-10-16T09:12:44Z",
"created_at": "2026-10-01T08:00:00Z",
"updated_at": "2026-10-15T11:20:00Z"
}
],
"next_cursor": "MTc5MjE2MjQ3NTkxMzAwMDAwMHx3YWxfODgxMg"
}
registered is false for a placeholder Sentinel made because an event named the entity before you registered it; a placeholder has no kind. open_alerts counts its alerts that are open or in_review, and last_seen is its latest event in or out.
Timeline
GET /v1/entities/{id}/eventsThe entity's events, money in and out, newest first, each with its decision. The response is the same as listing events, and it pages the same way. An id with no events returns an empty list.
Get an entity
GET /v1/entities/{id}Returns the entity with the same fields as above, or 404 with entity not found. An entity Sentinel created as a placeholder, because an event named it before you registered it, comes back too; register it to set its real kind.
Links
GET /v1/entities/{id}/linksWho the entity is connected to, built from events, most recently seen first, up to 50. An entity with no links returns an empty list.
curl "$SENTINEL_URL/v1/entities/wal_8812/links" -H "Authorization: Bearer $SENTINEL_KEY"
{
"links": [
{
"entity_id": "wal_6603",
"kind": "wallet",
"relation": "shares_device",
"via": "dev_a3f1e2d4",
"first_seen": "2026-10-15T08:10:00Z",
"last_seen": "2026-10-16T09:12:44Z",
"open_alert": {
"id": "c7d4e1a2-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
"number": 20477,
"priority": "high"
}
},
{
"entity_id": "dev_a3f1e2d4",
"kind": "device",
"relation": "uses_device",
"first_seen": "2026-10-15T08:10:00Z",
"last_seen": "2026-10-16T09:12:44Z"
}
]
}
| Field | Type | Meaning |
|---|---|---|
entity_id | string | The linked entity |
kind | string | Its kind. Absent for placeholders you haven't registered |
name | string | Its name attribute, if it has one |
relation | string | paid (this entity paid it), paid_by (it paid this entity), uses_device (a device this entity used), device_user (for a device: who used it) or shares_device (another entity used one of this entity's devices) |
via | string | For shares_device, the device they share |
first_seen, last_seen | string, date-time | When the connection was first and last seen, by the events' occurred_at |
open_alert | object | The linked entity's open alert, if it has one: id, number and priority |