Tags

Tags belong to one entity type: contact, request, quote, job, or invoice. The same label on two entity types represents separate tags. A tag's type cannot be changed by the update endpoint.

GET /tags requires taggable_type. Assignment reads require that type plus taggable_id. Assignment writes replace the entity's full tag set; an empty tag_ids array clears it. To add a tag while keeping existing ones, read the current set and include all desired IDs in the update.

GET and PUT /tags/assignments return an array in data, without pagination. Contact/request/quote/job/invoice lists also accept comma-separated tag_ids, matching any of the selected tags.

GET /api/v1/tags

GET /api/v1/tags

Required scopes: tags:read.

Query parameters

Field	Type / accepted values	Required	Details
`page`	integer	No	Page number, starting at 1. Default: `1`.
`per_page`	integer	No	Records per page, from 1 to 100. Default: `25`. minimum: 1. maximum: 100.
`search`	string	No	Search text. maxLength: 100.
`sort_by`	string	No	Sort column. See the supported columns below when listed.
`sort_direction`	`"asc"`, `"desc"`	No	Sort direction. Default: `"desc"`.
`taggable_type`	string	Yes	One of request, quote, job, invoice, contact. Required.

Response

200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.

See response conventions and errors.

POST /api/v1/tags

POST /api/v1/tags

Required scopes: tags:write.

JSON body

Field	Type / accepted values	Required	Details
`name`	string	Yes	minLength: 1.
`taggable_type`	`"request"`, `"quote"`, `"job"`, `"invoice"`, `"contact"`	Yes
`description`	string	No	Default: `""`.
`color`	string or null	No

Unknown body fields are rejected. Conditional requirements are explained above.

Response

201 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

GET /api/v1/tags/:id

GET /api/v1/tags/:id

Required scopes: tags:read.

Path parameters: id. Use positive integer record IDs from this workspace.

Response

200 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

PUT /api/v1/tags/:id

PUT /api/v1/tags/:id

Required scopes: tags:write.

Path parameters: id. Use positive integer record IDs from this workspace.

JSON body

Field	Type / accepted values	Required	Details
`name`	string	No	minLength: 1.
`description`	string	No	Default: `""`.
`color`	string or null	No

Unknown body fields are rejected. Conditional requirements are explained above.

Response

200 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

DELETE /api/v1/tags/:id

DELETE /api/v1/tags/:id

Required scopes: tags:write.

Path parameters: id. Use positive integer record IDs from this workspace.

No request body.

Response

200 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

GET /api/v1/tags/assignments

GET /api/v1/tags/assignments

Required scopes: tags:read.

Query parameters

Field	Type / accepted values	Required	Details
`taggable_type`	string	Yes	One of request, quote, job, invoice, contact. Required.
`taggable_id`	string	Yes	Positive integer ID of the tagged record. Required.

Response

200 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

PUT /api/v1/tags/assignments

PUT /api/v1/tags/assignments

Required scopes: tags:write.

JSON body

Field	Type / accepted values	Required
`taggable_type`	`"request"`, `"quote"`, `"job"`, `"invoice"`, `"contact"`	Yes
`taggable_id`	integer	Yes
`tag_ids`	array of integer	Yes

Unknown body fields are rejected. Conditional requirements are explained above.

Response

200 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

On this page