LeadMagnet/leadchat
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs(swagger): document account label endpoints (#13760)

Browse Source 
Documents the missing account-level label CRUD endpoints in Chatwoot's
Swagger output so label management is discoverable alongside the
existing contact and conversation label APIs.

Fixes: none
Closes: none

Why
The account-level label API already exists in Chatwoot, but it was
missing from the published Swagger spec. That made label management
harder to discover even though contact and conversation label assignment
endpoints were already documented.

What this change does
- adds a `Labels` tag to the application Swagger docs
- adds the label resource and create/update payload schemas
- documents `GET/POST /api/v1/accounts/{account_id}/labels`
- documents `GET/PATCH/DELETE /api/v1/accounts/{account_id}/labels/{id}`
- regenerates the compiled Swagger JSON artifacts

Validation
- rebuilt the Swagger JSON from the source YAML
- verified the new label endpoints appear in `swagger/swagger.json`
- verified the new label endpoints appear in
`swagger/tag_groups/application_swagger.json`
- started the local Rails server and confirmed `/swagger` and
`/swagger/swagger.json` return `200 OK`
This commit is contained in:
Sojan Jose
2026-03-10 22:24:16 -07:00
committed by GitHub
parent 9a9398b386
commit fdc326094a
16 changed files with 940 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
swagger/definitions/index.yml
View File

@@ -70,6 +70,8 @@ platform_account:
$ref: ./resource/platform_account.yml
team:
$ref: ./resource/team.yml
label:
$ref: ./resource/label.yml
integrations_app:
$ref: ./resource/integrations/app.yml
integrations_hook:
@@ -142,6 +144,10 @@ inbox_update_payload:
team_create_update_payload:
$ref: ./request/team/create_update_payload.yml
# Label
label_create_update_payload:
$ref: ./request/label/create_update_payload.yml
# Custom Filter
custom_filter_create_update_payload:
$ref: ./request/custom_filter/create_update_payload.yml

18
swagger/definitions/request/label/create_update_payload.yml Normal file
View File

@@ -0,0 +1,18 @@
type: object
properties:
title:
type: string
description: The label title
example: support
description:
type: string
description: A short description for the label
example: Conversations that need support follow-up
color:
type: string
description: Hex color code for the label
example: '#1f93ff'
show_on_sidebar:
type: boolean
description: Whether the label should appear in the sidebar
example: true

17
swagger/definitions/resource/label.yml Normal file
View File

@@ -0,0 +1,17 @@
type: object
properties:
id:
type: number
description: The ID of the label
title:
type: string
description: The title of the label
description:
type: string
description: The description of the label
color:
type: string
description: Hex color code for the label
show_on_sidebar:
type: boolean
description: Whether the label should appear in the sidebar

3
swagger/index.yml
View File

@@ -67,6 +67,8 @@ tags:
description: Communication channels setup
- name: Integrations
description: Third-party integrations
- name: Labels
description: Account label management APIs
- name: Messages
description: Message management APIs
- name: Profile
@@ -112,6 +114,7 @@ x-tagGroups:
- Custom Filters
- Inboxes
- Integrations
- Labels
- Messages
- Profile
- Reports

26
swagger/paths/application/labels/create.yml Normal file
View File

@@ -0,0 +1,26 @@
tags:
- Labels
operationId: create-a-label
summary: Create a label
security:
- userApiKey: []
description: Create a label in the account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/label_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/label'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'

22
swagger/paths/application/labels/delete.yml Normal file
View File

@@ -0,0 +1,22 @@
tags:
- Labels
operationId: delete-a-label
summary: Delete a label
security:
- userApiKey: []
description: Delete a label from the account
responses:
'200':
description: Success
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: The label does not exist in the account
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'

26
swagger/paths/application/labels/index.yml Normal file
View File

@@ -0,0 +1,26 @@
tags:
- Labels
operationId: list-all-labels
summary: List all labels
security:
- userApiKey: []
description: List all labels available in the current account
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
payload:
type: array
description: Array of labels
items:
$ref: '#/components/schemas/label'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'

26
swagger/paths/application/labels/show.yml Normal file
View File

@@ -0,0 +1,26 @@
tags:
- Labels
operationId: get-details-of-a-single-label
summary: Get a label
security:
- userApiKey: []
description: Get the details of a label in the account
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/label'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: The given label ID does not exist in the account
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'

26
swagger/paths/application/labels/update.yml Normal file
View File

@@ -0,0 +1,26 @@
tags:
- Labels
operationId: update-a-label
summary: Update a label
security:
- userApiKey: []
description: Update a label's attributes
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/label_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/label'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'

24
swagger/paths/index.yml
View File

@@ -438,6 +438,30 @@
delete:
$ref: ./application/inboxes/inbox_members/delete.yml
# Labels
/api/v1/accounts/{account_id}/labels:
parameters:
- $ref: '#/components/parameters/account_id'
get:
$ref: ./application/labels/index.yml
post:
$ref: ./application/labels/create.yml
/api/v1/accounts/{account_id}/labels/{id}:
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
required: true
schema:
type: number
description: ID of the label
get:
$ref: ./application/labels/show.yml
patch:
$ref: ./application/labels/update.yml
delete:
$ref: ./application/labels/delete.yml
# Messages
/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages:
parameters:

295
swagger/swagger.json
View File

@@ -6101,6 +6101,246 @@
}
}
},
"/api/v1/accounts/{account_id}/labels": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
}
],
"get": {
"tags": [
"Labels"
],
"operationId": "list-all-labels",
"summary": "List all labels",
"security": [
{
"userApiKey": []
}
],
"description": "List all labels available in the current account",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"payload": {
"type": "array",
"description": "Array of labels",
"items": {
"$ref": "#/components/schemas/label"
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
},
"post": {
"tags": [
"Labels"
],
"operationId": "create-a-label",
"summary": "Create a label",
"security": [
{
"userApiKey": []
}
],
"description": "Create a label in the account",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label_create_update_payload"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
}
},
"/api/v1/accounts/{account_id}/labels/{id}": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "number"
},
"description": "ID of the label"
}
],
"get": {
"tags": [
"Labels"
],
"operationId": "get-details-of-a-single-label",
"summary": "Get a label",
"security": [
{
"userApiKey": []
}
],
"description": "Get the details of a label in the account",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
},
"404": {
"description": "The given label ID does not exist in the account",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
},
"patch": {
"tags": [
"Labels"
],
"operationId": "update-a-label",
"summary": "Update a label",
"security": [
{
"userApiKey": []
}
],
"description": "Update a label's attributes",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label_create_update_payload"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
},
"delete": {
"tags": [
"Labels"
],
"operationId": "delete-a-label",
"summary": "Delete a label",
"security": [
{
"userApiKey": []
}
],
"description": "Delete a label from the account",
"responses": {
"200": {
"description": "Success"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
},
"404": {
"description": "The label does not exist in the account",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
}
},
"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages": {
"parameters": [
{
@@ -10324,6 +10564,31 @@
}
}
},
"label": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The ID of the label"
},
"title": {
"type": "string",
"description": "The title of the label"
},
"description": {
"type": "string",
"description": "The description of the label"
},
"color": {
"type": "string",
"description": "Hex color code for the label"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar"
}
}
},
"integrations_app": {
"type": "object",
"properties": {
@@ -11633,6 +11898,31 @@
}
}
},
"label_create_update_payload": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The label title",
"example": "support"
},
"description": {
"type": "string",
"description": "A short description for the label",
"example": "Conversations that need support follow-up"
},
"color": {
"type": "string",
"description": "Hex color code for the label",
"example": "#1f93ff"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar",
"example": true
}
}
},
"custom_filter_create_update_payload": {
"type": "object",
"properties": {
@@ -14118,6 +14408,10 @@
"name": "Integrations",
"description": "Third-party integrations"
},
{
"name": "Labels",
"description": "Account label management APIs"
},
{
"name": "Messages",
"description": "Message management APIs"
@@ -14190,6 +14484,7 @@
"Custom Filters",
"Inboxes",
"Integrations",
"Labels",
"Messages",
"Profile",
"Reports",

4
swagger/tag_groups/application.yml
View File

@@ -36,6 +36,8 @@ tags:
description: Manage inboxes
- name: Integrations
description: Manage integrations
- name: Labels
description: Manage account labels
- name: Messages
description: Manage messages
- name: Profile
@@ -62,4 +64,4 @@ components:
type: apiKey
in: header
name: api_access_token
description: This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels.
description: This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels.

295
swagger/tag_groups/application_swagger.json
View File

@@ -4644,6 +4644,246 @@
}
}
},
"/api/v1/accounts/{account_id}/labels": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
}
],
"get": {
"tags": [
"Labels"
],
"operationId": "list-all-labels",
"summary": "List all labels",
"security": [
{
"userApiKey": []
}
],
"description": "List all labels available in the current account",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"payload": {
"type": "array",
"description": "Array of labels",
"items": {
"$ref": "#/components/schemas/label"
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
},
"post": {
"tags": [
"Labels"
],
"operationId": "create-a-label",
"summary": "Create a label",
"security": [
{
"userApiKey": []
}
],
"description": "Create a label in the account",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label_create_update_payload"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
}
},
"/api/v1/accounts/{account_id}/labels/{id}": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "number"
},
"description": "ID of the label"
}
],
"get": {
"tags": [
"Labels"
],
"operationId": "get-details-of-a-single-label",
"summary": "Get a label",
"security": [
{
"userApiKey": []
}
],
"description": "Get the details of a label in the account",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
},
"404": {
"description": "The given label ID does not exist in the account",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
},
"patch": {
"tags": [
"Labels"
],
"operationId": "update-a-label",
"summary": "Update a label",
"security": [
{
"userApiKey": []
}
],
"description": "Update a label's attributes",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label_create_update_payload"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/label"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
},
"delete": {
"tags": [
"Labels"
],
"operationId": "delete-a-label",
"summary": "Delete a label",
"security": [
{
"userApiKey": []
}
],
"description": "Delete a label from the account",
"responses": {
"200": {
"description": "Success"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
},
"404": {
"description": "The label does not exist in the account",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
}
},
"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages": {
"parameters": [
{
@@ -8831,6 +9071,31 @@
}
}
},
"label": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The ID of the label"
},
"title": {
"type": "string",
"description": "The title of the label"
},
"description": {
"type": "string",
"description": "The description of the label"
},
"color": {
"type": "string",
"description": "Hex color code for the label"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar"
}
}
},
"integrations_app": {
"type": "object",
"properties": {
@@ -10140,6 +10405,31 @@
}
}
},
"label_create_update_payload": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The label title",
"example": "support"
},
"description": {
"type": "string",
"description": "A short description for the label",
"example": "Conversations that need support follow-up"
},
"color": {
"type": "string",
"description": "Hex color code for the label",
"example": "#1f93ff"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar",
"example": true
}
}
},
"custom_filter_create_update_payload": {
"type": "object",
"properties": {
@@ -12609,6 +12899,10 @@
"name": "Integrations",
"description": "Third-party integrations"
},
{
"name": "Labels",
"description": "Account label management APIs"
},
{
"name": "Messages",
"description": "Message management APIs"
@@ -12665,6 +12959,7 @@
"Custom Filters",
"Inboxes",
"Integrations",
"Labels",
"Messages",
"Profile",
"Reports",

51
swagger/tag_groups/client_swagger.json
View File

@@ -2336,6 +2336,31 @@
}
}
},
"label": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The ID of the label"
},
"title": {
"type": "string",
"description": "The title of the label"
},
"description": {
"type": "string",
"description": "The description of the label"
},
"color": {
"type": "string",
"description": "Hex color code for the label"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar"
}
}
},
"integrations_app": {
"type": "object",
"properties": {
@@ -3645,6 +3670,31 @@
}
}
},
"label_create_update_payload": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The label title",
"example": "support"
},
"description": {
"type": "string",
"description": "A short description for the label",
"example": "Conversations that need support follow-up"
},
"color": {
"type": "string",
"description": "Hex color code for the label",
"example": "#1f93ff"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar",
"example": true
}
}
},
"custom_filter_create_update_payload": {
"type": "object",
"properties": {
@@ -6106,6 +6156,7 @@
"Custom Filters",
"Inboxes",
"Integrations",
"Labels",
"Messages",
"Profile",
"Reports",

51
swagger/tag_groups/other_swagger.json
View File

@@ -1751,6 +1751,31 @@
}
}
},
"label": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The ID of the label"
},
"title": {
"type": "string",
"description": "The title of the label"
},
"description": {
"type": "string",
"description": "The description of the label"
},
"color": {
"type": "string",
"description": "Hex color code for the label"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar"
}
}
},
"integrations_app": {
"type": "object",
"properties": {
@@ -3060,6 +3085,31 @@
}
}
},
"label_create_update_payload": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The label title",
"example": "support"
},
"description": {
"type": "string",
"description": "A short description for the label",
"example": "Conversations that need support follow-up"
},
"color": {
"type": "string",
"description": "Hex color code for the label",
"example": "#1f93ff"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar",
"example": true
}
}
},
"custom_filter_create_update_payload": {
"type": "object",
"properties": {
@@ -5513,6 +5563,7 @@
"Custom Filters",
"Inboxes",
"Integrations",
"Labels",
"Messages",
"Profile",
"Reports",

51
swagger/tag_groups/platform_swagger.json
View File

@@ -2512,6 +2512,31 @@
}
}
},
"label": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The ID of the label"
},
"title": {
"type": "string",
"description": "The title of the label"
},
"description": {
"type": "string",
"description": "The description of the label"
},
"color": {
"type": "string",
"description": "Hex color code for the label"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar"
}
}
},
"integrations_app": {
"type": "object",
"properties": {
@@ -3821,6 +3846,31 @@
}
}
},
"label_create_update_payload": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The label title",
"example": "support"
},
"description": {
"type": "string",
"description": "A short description for the label",
"example": "Conversations that need support follow-up"
},
"color": {
"type": "string",
"description": "Hex color code for the label",
"example": "#1f93ff"
},
"show_on_sidebar": {
"type": "boolean",
"description": "Whether the label should appear in the sidebar",
"example": true
}
}
},
"custom_filter_create_update_payload": {
"type": "object",
"properties": {
@@ -6286,6 +6336,7 @@
"Custom Filters",
"Inboxes",
"Integrations",
"Labels",
"Messages",
"Profile",
"Reports",