Tags

Endpoints for managing tags and their assignments to checklists and tasks.

---

List Tags

Returns all tags defined in your team.

GET /api/tag/tags

Request Headers

Header	Required	Description
X-API-KEY	Yes	Your API key

Example Request

GET https://app.checkflow.io/api/tag/tags
X-API-KEY: your-api-key-here

Example Response

[
  { "key": "be67fed0-f4c9-4312-a6ff-4cca568bcf25", "name": "Human Resources" },
  { "key": "c8ddfcc2-43b3-4f82-ba6e-5505eea4d1aa", "name": "Finance" }
]

Response Codes

Code	Description
200	Returns the list of tags.
401	API key is missing or invalid.

---

Create Tag

Creates a new tag. If a tag with the same name already exists, the existing tag is returned instead of creating a duplicate.

POST /api/tag

Request Headers

Header	Required	Description
X-API-KEY	Yes	Your API key

Query Parameters

Parameter	Type	Required	Description
name	string	Yes	The name for the new tag.

Example Request

POST https://app.checkflow.io/api/tag?name=Human%20Resources
X-API-KEY: your-api-key-here

Example Response

{
  "key": "be67fed0-f4c9-4312-a6ff-4cca568bcf25",
  "name": "Human Resources"
}

Response Codes

Code	Description
200	Returns the newly created tag, or the existing tag if one with the same name already exists.
401	API key is missing or invalid.

---

Delete Tag

Permanently deletes a tag from your team.

DELETE /api/tag

Request Headers

Header	Required	Description
X-API-KEY	Yes	Your API key

Query Parameters

Parameter	Type	Required	Description
tagKey	string (GUID)	Yes	The key of the tag to delete. Use List Tags to find the key.

Example Request

DELETE https://app.checkflow.io/api/tag?tagKey=c8ddfcc2-43b3-4f82-ba6e-5505eea4d1aa
X-API-KEY: your-api-key-here

Response Codes

Code	Description
200	Tag deleted successfully.
401	API key is missing or invalid.

---

Assign Tag

Assigns a tag to a checklist or a task.

POST /api/tag/assignment

Request Headers

Header	Required	Description
X-API-KEY	Yes	Your API key

Request Body

The request body differs depending on whether you are assigning to a checklist or a task.

Assign to a checklist:

{
  "tagKey": "be67fed0-f4c9-4312-a6ff-4cca568bcf25",
  "assignmentKey": "27217bc9-1f00-460e-bf41-3821cd37beaf",
  "assignmentType": 1,
  "parentKey": null
}

Assign to a task:

{
  "tagKey": "be67fed0-f4c9-4312-a6ff-4cca568bcf25",
  "assignmentKey": "4cb6f84c-950f-4424-aa7b-d12608419d9b",
  "assignmentType": 3,
  "parentKey": "27217bc9-1f00-460e-bf41-3821cd37beaf"
}

Field	Type	Required	Description
tagKey	string (GUID)	Yes	The key of the tag to assign.
assignmentKey	string (GUID)	Yes	The key of the checklist or task the tag is being assigned to.
assignmentType	int	Yes	1 for checklist, 3 for task.
parentKey	string (GUID)	Conditional	Required when assignmentType is 3. The key of the checklist that contains the task.

Response Codes

Code	Description
200	Returns the newly created tag assignment.
401	API key is missing or invalid.
404	Tag, checklist, or task not found.

---

Remove Tag Assignment

Removes a tag assignment from a checklist or a task.

DELETE /api/tag/assignment

Request Headers

Header	Required	Description
X-API-KEY	Yes	Your API key

Request Body

The request body differs depending on whether you are removing from a checklist or a task.

Remove from a checklist:

{
  "tagKey": "be67fed0-f4c9-4312-a6ff-4cca568bcf25",
  "assignmentKey": "27217bc9-1f00-460e-bf41-3821cd37beaf",
  "assignmentType": 1,
  "parentKey": null
}

Remove from a task:

{
  "tagKey": "be67fed0-f4c9-4312-a6ff-4cca568bcf25",
  "assignmentKey": "4cb6f84c-950f-4424-aa7b-d12608419d9b",
  "assignmentType": 3,
  "parentKey": "27217bc9-1f00-460e-bf41-3821cd37beaf"
}

Field	Type	Required	Description
tagKey	string (GUID)	Yes	The key of the tag assignment to remove.
assignmentKey	string (GUID)	Yes	The key of the checklist or task the tag is being removed from.
assignmentType	int	Yes	1 for checklist, 3 for task.
parentKey	string (GUID)	Conditional	Required when assignmentType is 3. The key of the checklist that contains the task.

Response Codes

Code	Description
200	Tag assignment removed successfully.
401	API key is missing or invalid.
404	Tag, checklist, or task not found.

Related Pages

• Tags Overview — what tags are for.
• Applying Tags — the same job in the interface.