Create a collection

Create a face collection for your workspace. It starts empty; enroll faces into it.

POSThttps://api.decisionnode.com/v1/collections

curl -X POST https://api.decisionnode.com/v1/collections \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"face","name":"Staff, Stockholm office"}'

Headers#

Authorizationheaderrequired: Bearer dn_live_.... A Full access key: every call acts for that key's workspace only, and a Decisions-only key gets 403 key_scope_denied, "This key may only make decisions."
Content-Typeheader: application/json. Not checked: the body is read as JSON whatever its type.
Idempotency-Keyheader: 1 to 255 printable ASCII characters of your choosing, sent once. A retry with the same key, route and body within 24 hours gets the first answer again; see Retrying.

Request body#

typestringrequired: face, the only type: "Input should be 'face'" otherwise.
namestringrequired: 1 to 80 characters with no control or invisible characters, unique among your collections.

Response#

201 Created with the collection object, empty.

201 Created

{
  "id": "col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80",
  "type": "face",
  "name": "Staff, Stockholm office",
  "public": false,
  "items": 0,
  "created_at": "2026-10-12T09:00:00Z",
  "deletion": null
}

Errors#

400
Type
api_usage_error
When
A malformed Idempotency-Key: "Idempotency-Key must be sent once, as 1 to 255 printable ASCII characters."
What to do
Send one key of 1 to 255 printable ASCII characters
401
Type
authentication_error
When
The key is missing, unknown or revoked
What to do
Check the Authorization header
402
Type
insufficient_credit
When
The prepaid balance is empty. Reads, edits and deletes stay open
What to do
Add credit, then retry
403
Type
key_scope_denied
When
A Decisions-only key: "This key may only make decisions."
What to do
Use a Full access key on your server
403
Type
collections_region_unavailable
When
Your workspace's storage location is not the default: "Collections are not available yet for this workspace's storage location."
What to do
Write to us
403
Type
workspace_suspended
When
The workspace is suspended: "This workspace is suspended. Contact hello@bynn.com."
What to do
Write to us
409
Type
collections_limit_reached
When
Your workspace has 100 collections, unless we set yours otherwise: "This workspace has reached its limit of <n> collections."
What to do
Delete one, or write to us
409
Type
idempotency_key_reused, idempotency_in_progress
When
The key was used with another request, or its first request still runs (Retry-After: 1)
What to do
See Retrying
408
Type
request_timeout_error
When
The request body did not arrive in time.
What to do
Send it again
413
Type
request_too_large_error
When
The body is over 4 KiB. The message is the API's general one, which names 25 MiB
What to do
Send a smaller body
422
Type
a detail list
When
type missing or not face (literal_error); name missing, not a string, empty, too long or holding a control character; a name already used: name_taken at ["body", "name"], "A collection with this name already exists in this workspace"
What to do
Fix the field; a 422 frees the Idempotency-Key
422
Type
a detail list
When
The body is not JSON (json_invalid)
What to do
Send a JSON object
429
Type
rate_limit_error
When
Over your request rate
What to do
Wait Retry-After, then send the same call again
500
Type
api_error
When
A fault on our side
What to do
Retry with backoff
529
Type
overloaded_error
When
The collections cannot take the call right now
What to do
Wait Retry-After (1 s, or 1 to 2 s when the key store is busy), then retry

Errors this call returns
Status	Type	When	What to do
`400`	`api_usage_error`	A malformed `Idempotency-Key`: "Idempotency-Key must be sent once, as 1 to 255 printable ASCII characters."	Send one key of 1 to 255 printable ASCII characters
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`402`	`insufficient_credit`	The prepaid balance is empty. Reads, edits and deletes stay open	Add credit, then retry
`403`	`key_scope_denied`	A Decisions-only key: "This key may only make decisions."	Use a Full access key on your server
`403`	`collections_region_unavailable`	Your workspace's storage location is not the default: "Collections are not available yet for this workspace's storage location."	Write to us
`403`	`workspace_suspended`	The workspace is suspended: "This workspace is suspended. Contact hello@bynn.com."	Write to us
`409`	`collections_limit_reached`	Your workspace has 100 collections, unless we set yours otherwise: "This workspace has reached its limit of <n> collections."	Delete one, or write to us
`409`	`idempotency_key_reused`, `idempotency_in_progress`	The key was used with another request, or its first request still runs (`Retry-After: 1`)	See Retrying
`408`	`request_timeout_error`	The request body did not arrive in time.	Send it again
`413`	`request_too_large_error`	The body is over 4 KiB. The message is the API's general one, which names 25 MiB	Send a smaller body
`422`	a `detail` list	`type` missing or not `face` (`literal_error`); `name` missing, not a string, empty, too long or holding a control character; a name already used: `name_taken` at `["body", "name"]`, "A collection with this name already exists in this workspace"	Fix the field; a `422` frees the `Idempotency-Key`
`422`	a `detail` list	The body is not JSON (`json_invalid`)	Send a JSON object
`429`	`rate_limit_error`	Over your request rate	Wait `Retry-After`, then send the same call again
`500`	`api_error`	A fault on our side	Retry with backoff
`529`	`overloaded_error`	The collections cannot take the call right now	Wait `Retry-After` (1 s, or 1 to 2 s when the key store is busy), then retry

A refusal is {"detail": {"error_type": "...", "message": "..."}}; a 422 is {"detail": [...]}, one entry per field, each with type, loc, msg and input (a string cut to 64 characters, an object or array never echoed). Every 429 and 529 and the 409 idempotency_in_progress carry Retry-After (seconds) and retry-after-ms (milliseconds); enrollment_unpriced carries neither. The Collections API's own refusals (api_usage_error, collection_read_only, item_not_found, collections_region_unavailable, the limits, the idempotency 409s and image_url_refused) also carry x-decisionnode-error, the message in ASCII. Retry 408, 429, 529 and any 5xx after Retry-After; fix the call for the other 4xx.

curl -X POST https://api.decisionnode.com/v1/collections \ -H "Authorization: Bearer $DECISIONNODE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type":"face","name":"Staff, Stockholm office"}'

Headers#

Authorizationheaderrequired

Bearer dn_live_.... A Full access key: every call acts for that key's workspace only, and a Decisions-only key gets 403 key_scope_denied, "This key may only make decisions."

Content-Typeheader

application/json. Not checked: the body is read as JSON whatever its type.

Idempotency-Keyheader

1 to 255 printable ASCII characters of your choosing, sent once. A retry with the same key, route and body within 24 hours gets the first answer again; see Retrying.

Errors#

400

Type: api_usage_error
When: A malformed Idempotency-Key: "Idempotency-Key must be sent once, as 1 to 255 printable ASCII characters."
What to do: Send one key of 1 to 255 printable ASCII characters

401

Type: authentication_error
When: The key is missing, unknown or revoked
What to do: Check the Authorization header

402

Type: insufficient_credit
When: The prepaid balance is empty. Reads, edits and deletes stay open
What to do: Add credit, then retry

403

Type: key_scope_denied
When: A Decisions-only key: "This key may only make decisions."
What to do: Use a Full access key on your server

403

Type: collections_region_unavailable
When: Your workspace's storage location is not the default: "Collections are not available yet for this workspace's storage location."
What to do: Write to us

403

Type: workspace_suspended
When: The workspace is suspended: "This workspace is suspended. Contact hello@bynn.com."
What to do: Write to us

409

Type: collections_limit_reached
When: Your workspace has 100 collections, unless we set yours otherwise: "This workspace has reached its limit of <n> collections."
What to do: Delete one, or write to us

409

Type: idempotency_key_reused, idempotency_in_progress
When: The key was used with another request, or its first request still runs (Retry-After: 1)
What to do: See Retrying

408

Type: request_timeout_error
When: The request body did not arrive in time.
What to do: Send it again

413

Type: request_too_large_error
When: The body is over 4 KiB. The message is the API's general one, which names 25 MiB
What to do: Send a smaller body

422

Type: a detail list
When: type missing or not face (literal_error); name missing, not a string, empty, too long or holding a control character; a name already used: name_taken at ["body", "name"], "A collection with this name already exists in this workspace"
What to do: Fix the field; a 422 frees the Idempotency-Key

422

Type: a detail list
When: The body is not JSON (json_invalid)
What to do: Send a JSON object

429

Type: rate_limit_error
When: Over your request rate
What to do: Wait Retry-After, then send the same call again

500

Type: api_error
When: A fault on our side
What to do: Retry with backoff

529

Type: overloaded_error
When: The collections cannot take the call right now
What to do: Wait Retry-After (1 s, or 1 to 2 s when the key store is busy), then retry

Errors this call returns
Status	Type	When	What to do
`400`	`api_usage_error`	A malformed `Idempotency-Key`: "Idempotency-Key must be sent once, as 1 to 255 printable ASCII characters."	Send one key of 1 to 255 printable ASCII characters
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`402`	`insufficient_credit`	The prepaid balance is empty. Reads, edits and deletes stay open	Add credit, then retry
`403`	`key_scope_denied`	A Decisions-only key: "This key may only make decisions."	Use a Full access key on your server
`403`	`collections_region_unavailable`	Your workspace's storage location is not the default: "Collections are not available yet for this workspace's storage location."	Write to us
`403`	`workspace_suspended`	The workspace is suspended: "This workspace is suspended. Contact hello@bynn.com."	Write to us
`409`	`collections_limit_reached`	Your workspace has 100 collections, unless we set yours otherwise: "This workspace has reached its limit of <n> collections."	Delete one, or write to us
`409`	`idempotency_key_reused`, `idempotency_in_progress`	The key was used with another request, or its first request still runs (`Retry-After: 1`)	See Retrying
`408`	`request_timeout_error`	The request body did not arrive in time.	Send it again
`413`	`request_too_large_error`	The body is over 4 KiB. The message is the API's general one, which names 25 MiB	Send a smaller body
`422`	a `detail` list	`type` missing or not `face` (`literal_error`); `name` missing, not a string, empty, too long or holding a control character; a name already used: `name_taken` at `["body", "name"]`, "A collection with this name already exists in this workspace"	Fix the field; a `422` frees the `Idempotency-Key`
`422`	a `detail` list	The body is not JSON (`json_invalid`)	Send a JSON object
`429`	`rate_limit_error`	Over your request rate	Wait `Retry-After`, then send the same call again
`500`	`api_error`	A fault on our side	Retry with backoff
`529`	`overloaded_error`	The collections cannot take the call right now	Wait `Retry-After` (1 s, or 1 to 2 s when the key store is busy), then retry