Labels¶

Create a label¶

POST /labels

Code samples

curl -X POST https://localhost:9543/api/v0.9/labels \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Creates a label for the organization.

Payload

{
  "id": "premium",
  "displayName": "Premium APIs"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	LabelRequest	true	Label payload.

Example responses

201 Response

{
  "id": "premium",
  "displayName": "Premium APIs"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
201	Created	The created label.	LabelResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Response Headers¶

Status	Header	Type	Format	Description
201	Location	string	uri	URL of the created label.

List labels¶

GET /labels

Code samples

curl -X GET https://localhost:9543/api/v0.9/labels \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Returns all labels configured for the organization.

Authentication¶

Parameters

Name	In	Type	Required	Description
limit	query	integer	false	Maximum number of records to return.
offset	query	integer	false	Number of records to skip before returning results.

Example responses

200 Response

{
  "list": [
    {
      "id": "premium",
      "displayName": "Premium APIs"
    }
  ],
  "count": 1,
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Paginated list of label DTOs.	Inline
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[LabelResponse]	false	none	none
»» id	string	false	none	The label's handle (unique per org). Not the internal database uuid.
»» displayName	string	false	none	none
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Enumerated Values

Property	Value
status	error

Get a label¶

GET /labels/{labelId}

Code samples

curl -X GET https://localhost:9543/api/v0.9/labels/{labelId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Retrieves a single label by handle.

Authentication¶

Parameters

Name	In	Type	Required	Description
labelId	path	string	true	The label's handle (its `id` in request/response payloads), not the internal database uuid.

Example responses

200 Response

{
  "id": "premium",
  "displayName": "Premium APIs"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Label DTO.	LabelResponse
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Update a label¶

PUT /labels/{labelId}

Code samples

curl -X PUT https://localhost:9543/api/v0.9/labels/{labelId} \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Updates an existing label by handle.

Payload

{
  "id": "premium",
  "displayName": "Premium APIs"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
labelId	path	string	true	The label's handle (its `id` in request/response payloads), not the internal database uuid.
body	body	LabelRequest	true	Label payload.

Example responses

200 Response

{
  "id": "premium",
  "displayName": "Premium APIs"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Label DTO.	LabelResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Delete a label¶

DELETE /labels/{labelId}

Code samples

curl -X DELETE https://localhost:9543/api/v0.9/labels/{labelId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Deletes a label by handle.

Authentication¶

Parameters

Name	In	Type	Required	Description
labelId	path	string	true	The label's handle (its `id` in request/response payloads), not the internal database uuid.

Example responses

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
204	No Content	Label deleted successfully.	None
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse