Create Tag

POST

/inboxes/{inbox_id}/tags

Creates a new tag for the given inbox.

Labels must be unique within the inbox; creating a tag with a label that already exists fails with 409. Labels used by the system (for example scanned, shredded or archived) are reserved and fail with 422, regardless of case.

Authorizations

Send your API key in the x-api-key header. See Authentication.

Parameters

Path Parameters

inbox_id

required

string

Request Body ^required

object

label

required

The tag’s label. Required. Must be unique within the inbox and must not be a reserved system label.

string

>= 1 characters

Urgent

parent_tag_id

ID of the parent tag, to nest this tag under another tag in the same inbox. Optional. A tag cannot be its own parent.

integer | null

Example

{
  "label": "Invoices"
}

Responses

200

Success

object

id

integer

3001

created_at

string format: date-time

updated_at

string format: date-time

label

string

Urgent

parent_tag_id

integer | null

piece_counts

integer | null

12

Example

{
  "id": 204496,
  "created_at": "2026-06-03T08:35:08Z",
  "updated_at": "2026-06-03T08:35:08Z",
  "label": "test-tag-1"
}

401

The x-api-key header is missing or the key is not valid, or the caller can’t access an ID in the request. IDs that don’t exist return the same response as IDs the caller can’t access.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

401

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

Returned only with 422 responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

object

key

additional properties

Array<string>

Examples

{
  "error": {
    "code": 401,
    "message": "The request does not include a valid access token. Please provide a valid access token.",
    "type": "Authorization"
  }
}

{
  "error": {
    "code": 401,
    "message": "x-api-key: x-api-key is invalid",
    "type": "REST"
  }
}

{
  "error": {
    "code": 401,
    "message": "User does not have access to requested resource.",
    "type": "Authorization"
  }
}

404

The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can’t access, or that don’t exist at all, return 401 instead.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

401

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

Returned only with 422 responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

object

key

additional properties

Array<string>

Example

{
  "error": {
    "code": 404,
    "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.",
    "type": "REST"
  }
}

409

The request conflicts with the current state of the resource.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

401

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

Returned only with 422 responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

object

key

additional properties

Array<string>

422

The request body failed validation. The message names the invalid field.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

401

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

Returned only with 422 responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

object

key

additional properties

Array<string>

Example

{
  "error": {
    "code": 422,
    "message": "label: must have a value",
    "type": "REST",
    "fields": {}
  }
}