Tags

API for managing the account-level tag catalog. Tags are short-code labels that can be applied to flow-step errors for classification and triage.

Tag schema

List the account's tag catalog

get

/v1/tags

Returns every tag defined in the account, each with its short tagId code and human-readable tag name. This is the catalog that backs the tag-picker on flow-step errors (PUT /v1/flows/{_id}/{_stepId}/tags).

The tagId field is the short code used as a write-side input on flow-step tag mutations (PUT /v1/flows/{_id}/{_stepId}/tags accepts tagIds: ["NjMMA", ...]), while the human name is stored on the error record as tags: ["Ignore", ...].

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1Optional

Maximum number of records to return per page.

Example: 100

afterstringOptional

Opaque cursor for forward pagination. Pass the value from the Link response header (rel="next") to fetch the next page.

Responses

200

Array of tag entries (at least one tag exists).

application/json

204

No tags exist in the account.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/tags

GET /v1/tags HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "6555119c0a137977fb1e7994",
    "tag": "Ignore",
    "tagId": "NjMMA"
  },
  {
    "_id": "69a1e79bdbb446adf7933049",
    "tag": "IT Related Login Issue",
    "tagId": "P3mzf"
  }
]

Create a tag

post

/v1/tags

Creates a new tag in the account's tag catalog. The server generates an immutable short tagId code automatically. Tag names are case-insensitively unique within the account — a case-variant duplicate is rejected with HTTP 422 [create_not_allowed] "A tag with this name already exists." Per Celigo's documentation, the catalog holds at most 1,000 unique tags per account. Note the per-error limit is separate and much smaller: a single error carries at most 3 tags (see PUT /v1/flows/{_id}/{_stepId}/tags).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Fields for creating or updating a tag.

tagstring · min: 1 · max: 100Required

The human-readable tag name. Case-insensitively unique within the account. Whitespace is trimmed on save; names that are empty after trimming are rejected.

Example: Urgent

Responses

201

The created tag entry.

application/json

One tag entry from the account's tag catalog. tag is the human display name; tagId is the 5-char short code used when writing tag references on flow-step errors.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

tagstring · max: 100Required

Human-readable tag name. Appears on read-side error records.

Example: Urgent

tagIdstring · min: 5 · max: 5Read-onlyRequired

Short code used when writing tag references — e.g. as the values in PUT /v1/flows/{_id}/{_stepId}/tags tagIds[]. Server-generated and immutable: tagId values supplied on create/update are ignored and a fresh code is generated.

Example: rx618Pattern: ^[a-zA-Z0-9]{5}$

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/tags

POST /v1/tags HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "tag": "Urgent"
}

{
  "_id": "65d6cd9e83ba5b97e2658fce",
  "tag": "Urgent",
  "tagId": "rx618"
}

Get a tag

get

/v1/tags/{_id}

Returns a single tag entry by its _id.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The tag ID.

Example: 65d6cd9e83ba5b97e2658fce

Responses

200

The tag entry.

application/json

One tag entry from the account's tag catalog. tag is the human display name; tagId is the 5-char short code used when writing tag references on flow-step errors.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

tagstring · max: 100Required

Human-readable tag name. Appears on read-side error records.

Example: Urgent

tagIdstring · min: 5 · max: 5Read-onlyRequired

Short code used when writing tag references — e.g. as the values in PUT /v1/flows/{_id}/{_stepId}/tags tagIds[]. Server-generated and immutable: tagId values supplied on create/update are ignored and a fresh code is generated.

Example: rx618Pattern: ^[a-zA-Z0-9]{5}$

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/tags/{_id}

GET /v1/tags/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "65d6cd9e83ba5b97e2658fce",
  "tag": "Urgent",
  "tagId": "rx618"
}

Update a tag

put

/v1/tags/{_id}

Updates the human-readable tag name for an existing tag entry. The short tagId code is immutable and cannot be changed.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The tag ID.

Example: 65d6cd9e83ba5b97e2658fce

Body

Fields for creating or updating a tag.

tagstring · min: 1 · max: 100Required

The human-readable tag name. Case-insensitively unique within the account. Whitespace is trimmed on save; names that are empty after trimming are rejected.

Example: Urgent

Responses

200

The updated tag entry.

application/json

One tag entry from the account's tag catalog. tag is the human display name; tagId is the 5-char short code used when writing tag references on flow-step errors.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

tagstring · max: 100Required

Human-readable tag name. Appears on read-side error records.

Example: Urgent

tagIdstring · min: 5 · max: 5Read-onlyRequired

Short code used when writing tag references — e.g. as the values in PUT /v1/flows/{_id}/{_stepId}/tags tagIds[]. Server-generated and immutable: tagId values supplied on create/update are ignored and a fresh code is generated.

Example: rx618Pattern: ^[a-zA-Z0-9]{5}$

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

put/v1/tags/{_id}

PUT /v1/tags/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "tag": "Production Issue"
}

{
  "_id": "65d6cd9e83ba5b97e2658fce",
  "tag": "Production Issue",
  "tagId": "rx618"
}

Delete a tag

delete

/v1/tags/{_id}

Permanently deletes a tag from the account's tag catalog.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The tag ID.

Example: 65d6cd9e83ba5b97e2658fce

Responses

204

Tag deleted successfully.

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/tags/{_id}

DELETE /v1/tags/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Patch a tag

patch

/v1/tags/{_id}

Partially updates a tag using a JSON Patch document (RFC 6902). Only the replace operation is supported, and only on the following whitelisted path:

Path	Description
/tag	The human-readable tag name

All other paths are rejected with 422.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The tag ID.

Example: 65d6cd9e83ba5b97e2658fce

Bodyobject · JsonPatchOperation[]

A JSON Patch document (RFC 6902). Send an array of patch operations on whitelisted fields — all other paths are rejected with 422.

opstring · enumRequired

The operation to perform.

Possible values:

pathstringRequired

JSON Pointer (RFC 6901) to the field to patch. Only whitelisted paths are accepted — unlisted paths return 422 with "<path> is not a whitelisted property".

valueanyOptional

The new value to set. Required for replace and add, omit for remove.

Responses

204

Tag patched successfully.

No content

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

patch/v1/tags/{_id}

PATCH /v1/tags/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

[
  {
    "op": "replace",
    "path": "/tag",
    "value": "Production"
  }
]

No content