ControlUp Tags API
The Tags API from ControlUp — 2 operation(s) for tags.
The Tags API from ControlUp — 2 operation(s) for tags.
openapi: 3.2.0
info:
title: Dex Tags API
version: 1.0.0
description: Dex API Description
contact: {}
servers:
- url: https://api.controlup.com/v1
tags:
- name: Tags
paths:
/organizations/{orgId}/tags:
get:
operationId: OrgTagsPublicController_getAll
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/GetTagsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__'
'401':
description: 'Unauthorized: Access is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__'
'403':
description: 'Forbidden: Access to this resource is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__'
'404':
description: 'Not Found: The requested resource could not be found'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__'
description: Returns a list of all tags in your organization.
summary: List all tags
tags:
- Tags
security:
- apiKey: []
parameters:
- description: 'The page of results to return.
The first page is page number 1.'
in: query
name: _page
required: false
schema:
default: '1'
format: int32
type: integer
minimum: 1
example: 1
style: form
- description: The number of results returned per page.
in: query
name: _limit
required: false
schema:
default: '10'
format: int32
type: integer
minimum: 1
example: 10
style: form
- description: Sorts results according to the specified field.
in: query
name: _sortBy
required: false
schema:
default: id
type: string
example: id
style: form
- description: The sort order (ascending / descending) of the field specified by the `_sortBy` parameter.
in: query
name: _order
required: false
schema:
default: asc
type: string
enum:
- asc
- desc
example: asc
style: form
- description: 'A search filter that is applied to all fields.
Only results that contain the specified string are returned.'
in: query
name: _search
required: false
schema:
type: string
style: form
- description: The format of returned results.
in: query
name: _format
required: false
schema:
default: json
type: string
enum:
- json
- xml
- csv
example: json
style: form
- description: ID of your ControlUp organization. You can find your organization ID on the [API Key Management page](how-to-make-api-requests#how-to-find-your-controlup-organization-id) in the DEX platform.
in: path
name: orgId
required: true
schema:
$ref: '#/components/schemas/UUID'
- description: A search filter on the `key` field.
in: query
name: key
required: false
schema:
type: array
items:
type: string
style: form
- description: The operator to use for the `key` filter.
in: query
name: key_op
required: false
schema:
$ref: '#/components/schemas/TagFilterOperator'
style: form
- description: A search filter on the `description` field.
in: query
name: description
required: false
schema:
type: array
items:
type: string
style: form
- description: The operator to use for the `description` filter.
in: query
name: description_op
required: false
schema:
$ref: '#/components/schemas/TagFilterOperator'
style: form
- description: A search filter on the tag value labels.
in: query
name: value_label
required: false
schema:
type: array
items:
type: string
style: form
- description: The operator to use for the `value_label` filter.
in: query
name: value_label_op
required: false
schema:
$ref: '#/components/schemas/TagFilterOperator'
style: form
post:
operationId: OrgTagsPublicController_create
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/APIResponse_TagPublic_'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__'
'401':
description: 'Unauthorized: Access is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__'
'403':
description: 'Forbidden: Access to this resource is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__'
'404':
description: 'Not Found: The requested resource could not be found'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__'
description: Creates a new tag in your organization.
summary: Create a tag
tags:
- Tags
security:
- apiKey: []
parameters:
- description: ID of your ControlUp organization. You can find your organization ID on the [API Key Management page](how-to-make-api-requests#how-to-find-your-controlup-organization-id) in the DEX platform.
in: path
name: orgId
required: true
schema:
$ref: '#/components/schemas/UUID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTagRequest'
/organizations/{orgId}/tags/{id}:
get:
operationId: OrgTagsPublicController_getOneById
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/APIResponse_TagPublic_'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__'
'401':
description: 'Unauthorized: Access is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__'
'403':
description: 'Forbidden: Access to this resource is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__'
'404':
description: 'Not Found: The requested resource could not be found'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__'
description: Returns details of a tag.
summary: Retrieve a tag
tags:
- Tags
security:
- apiKey: []
parameters:
- description: The format of returned results.
in: query
name: _format
required: false
schema:
default: json
type: string
enum:
- json
- xml
- csv
example: json
style: form
- description: ID of your ControlUp organization. You can find your organization ID on the [API Key Management page](how-to-make-api-requests#how-to-find-your-controlup-organization-id) in the DEX platform.
in: path
name: orgId
required: true
schema:
$ref: '#/components/schemas/UUID'
- description: ID of the tag to retrieve. You can use [GET /tags](orgtagspubliccontroller_getall) to see the ID of each tag.
in: path
name: id
required: true
schema:
$ref: '#/components/schemas/UUID'
patch:
operationId: OrgTagsPublicController_update
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/APIResponse_TagPublic_'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__'
'401':
description: 'Unauthorized: Access is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__'
'403':
description: 'Forbidden: Access to this resource is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__'
'404':
description: 'Not Found: The requested resource could not be found'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__'
description: Updates an existing tag by its ID. Any parameters not passed are not changed.
summary: Update a tag
tags:
- Tags
security:
- apiKey: []
parameters:
- description: ID of your ControlUp organization. You can find your organization ID on the [API Key Management page](how-to-make-api-requests#how-to-find-your-controlup-organization-id) in the DEX platform.
in: path
name: orgId
required: true
schema:
$ref: '#/components/schemas/UUID'
- description: ID of the tag to update. You can use [GET /tags](orgtagspubliccontroller_getall) to see the ID of each tag.
in: path
name: id
required: true
schema:
$ref: '#/components/schemas/UUID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTagRequest'
delete:
operationId: OrgTagsPublicController_delete
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/APIResponse_DeletedActionResponse_'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__'
'401':
description: 'Unauthorized: Access is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__'
'403':
description: 'Forbidden: Access to this resource is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__'
'404':
description: 'Not Found: The requested resource could not be found'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__'
description: Deletes a tag by its ID.
summary: Delete a tag
tags:
- Tags
security:
- apiKey: []
parameters:
- description: ID of your ControlUp organization. You can find your organization ID on the [API Key Management page](how-to-make-api-requests#how-to-find-your-controlup-organization-id) in the DEX platform.
in: path
name: orgId
required: true
schema:
$ref: '#/components/schemas/UUID'
- description: ID of the tag to delete. You can use [GET /tags](orgtagspubliccontroller_getall) to see the ID of each tag.
in: path
name: id
required: true
schema:
$ref: '#/components/schemas/UUID'
components:
schemas:
APIResponse_DeletedActionResponse_:
properties:
data:
allOf:
- $ref: '#/components/schemas/DeletedActionResponse'
required:
- data
type: object
? ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__
: properties:
metadata:
$ref: '#/components/schemas/ErrorResponseMetadata'
error:
$ref: '#/components/schemas/ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError_'
required:
- error
- metadata
type: object
APIResponse_TagPublic-Array_:
properties:
data:
items:
$ref: '#/components/schemas/TagPublic'
type:
- array
- 'null'
required:
- data
type: object
GetTagsResponse:
$ref: '#/components/schemas/APIPaginatedResponse_TagPublic-Array_'
example:
metadata:
total: 2
limitPerPage: 10
currentPageNumber: 1
currentPageSize: 2
remaining: 0
data:
- id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
key: environment
description: Deployment environment
updatedAt: '2024-08-05T18:40:22.244Z'
values:
- id: v1b2c3d4-e5f6-7890-abcd-ef1234567890
label: production
color: '#FF0000'
- id: v2b2c3d4-e5f6-7890-abcd-ef1234567890
label: staging
color: '#FFFF00'
DeletedActionResponse:
properties:
affectedRows:
type: number
format: double
required:
- affectedRows
type: object
ErrorCode.NotFound:
enum:
- 5
type: number
TagFilterOperator:
type: string
enum:
- equals
- not_equals
- contains
- not_contains
HttpStatusCode.INTERNAL_SERVER_ERROR:
enum:
- 500
type: number
ErrorMessage.Unauthorized:
enum:
- Unauthorized
type: string
TagValuePublic:
properties:
id:
$ref: '#/components/schemas/UUID'
description: The unique identifier of the tag value.
label:
type: string
description: The tag value label.
color:
type:
- string
- 'null'
description: The tag value color.
required:
- color
- label
- id
type: object
BadRequestErrorMessages:
enum:
- Bad Request
- Invalid Params
- Unique Field Violation
type: string
APIPaginatedResponse_TagPublic-Array_:
allOf:
- $ref: '#/components/schemas/APIResponse_TagPublic-Array_'
- properties:
metadata:
allOf:
- $ref: '#/components/schemas/PaginatedResponseMetadata'
- additionalProperties: true
type: object
required:
- metadata
type: object
ErrorCode.Unauthorized:
enum:
- 3
type: number
ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__:
properties:
metadata:
$ref: '#/components/schemas/ErrorResponseMetadata'
error:
$ref: '#/components/schemas/ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized_'
required:
- error
- metadata
type: object
ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden_:
properties:
message:
$ref: '#/components/schemas/ErrorMessage.Forbidden'
code:
$ref: '#/components/schemas/ErrorCode.Forbidden'
status:
$ref: '#/components/schemas/HttpStatusCode.FORBIDDEN'
data:
additionalProperties: true
type: object
required:
- status
- code
- message
type: object
TagPublic:
properties:
id:
$ref: '#/components/schemas/UUID'
description: The unique identifier of the tag.
key:
type: string
description: The tag key.
description:
type:
- string
- 'null'
description: The tag description.
updatedAt:
$ref: '#/components/schemas/ISOString'
description: When the tag was last updated.
values:
items:
$ref: '#/components/schemas/TagValuePublic'
type: array
description: The values associated with this tag.
required:
- updatedAt
- description
- key
- id
type: object
HttpStatusCode.UNAUTHORIZED:
enum:
- 401
type: number
BadRequestErrorCodes:
enum:
- 2
- 14
- 50
type: number
ErrorMessage.InternalServerError:
enum:
- Internal Server Error
type: string
ErrorResponseMetadata:
properties:
cuRequestId:
type: string
orgId:
type: string
userId:
type: string
userIp:
type: string
required:
- userIp
- userId
- orgId
- cuRequestId
type: object
ErrorMessage.Forbidden:
enum:
- Forbidden
type: string
ErrorMessage.NotFound:
enum:
- Not Found
type: string
ErrorCode.InternalServerError:
enum:
- 6
type: number
ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized_:
properties:
message:
$ref: '#/components/schemas/ErrorMessage.Unauthorized'
code:
$ref: '#/components/schemas/ErrorCode.Unauthorized'
status:
$ref: '#/components/schemas/HttpStatusCode.UNAUTHORIZED'
data:
additionalProperties: true
type: object
required:
- status
- code
- message
type: object
HttpStatusCode.FORBIDDEN:
enum:
- 403
type: number
ErrorCode.Forbidden:
enum:
- 4
type: number
UpdateTagRequest:
properties:
key:
type: string
description: New key for the tag.
description:
type:
- string
- 'null'
description: New description for the tag.
values:
items:
properties:
color:
type:
- string
- 'null'
description: Optional hex color code for the value.
label:
type: string
description: The value label.
id:
type: string
description: ID of an existing value to update. Omit to create a new value.
required:
- label
type: object
type: array
description: Updated set of values. Values with an `id` are updated; values without an `id` are created; existing values omitted here are deleted.
type: object
ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__:
properties:
metadata:
$ref: '#/components/schemas/ErrorResponseMetadata'
error:
$ref: '#/components/schemas/ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound_'
required:
- error
- metadata
type: object
HttpStatusCode.BAD_REQUEST:
enum:
- 400
type: number
CreateTagRequest:
properties:
key:
type: string
description: The tag key. Must be unique within the organization.
description:
type:
- string
- 'null'
description: An optional description for the tag.
values:
items:
properties:
color:
type:
- string
- 'null'
description: Optional hex color code for the value.
label:
type: string
description: The value label.
required:
- label
type: object
type: array
description: Optional initial values for the tag.
required:
- key
type: object
ISOString:
type: string
example: '2022-12-22T18:43:55.483Z'
format: ISO String YYYY-MM-DDTHH:mm:ss.sssZ
description: Valid ISO string
pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\.\d{3})?Z$
ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__:
properties:
metadata:
$ref: '#/components/schemas/ErrorResponseMetadata'
error:
$ref: '#/components/schemas/ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes_'
required:
- error
- metadata
type: object
ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound_:
properties:
message:
$ref: '#/components/schemas/ErrorMessage.NotFound'
code:
$ref: '#/components/schemas/ErrorCode.NotFound'
status:
$ref: '#/components/schemas/HttpStatusCode.NOT_FOUND'
data:
additionalProperties: true
type: object
required:
- status
- code
- message
type: object
ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError_:
properties:
message:
$ref: '#/components/schemas/ErrorMessage.InternalServerError'
code:
$ref: '#/components/schemas/ErrorCode.InternalServerError'
status:
$ref: '#/components/schemas/HttpStatusCode.INTERNAL_SERVER_ERROR'
data:
additionalProperties: true
type: object
required:
- status
- code
- message
type: object
PaginatedResponseMetadata:
properties:
total:
type: number
format: double
description: The total number of results across all pages.
limitPerPage:
type: number
format: double
description: The maximum number of results returned per page (set by the `_limit` parameter).
currentPageNumber:
type: number
format: double
description: The page of result returned (set by the `_page` parameter).
currentPageSize:
type: number
format: double
description: The number of results on the current page.
remaining:
type: number
format: double
description: The total number of results on all pages higher than the current page.
required:
- remaining
- currentPageSize
- currentPageNumber
- limitPerPage
- total
type: object
example:
total: 18
limitPerPage: 10
currentPageNumber: 1
currentPageSize: 10
remaining: 8
ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__:
properties:
metadata:
$ref: '#/components/schemas/ErrorResponseMetadata'
error:
$ref: '#/components/schemas/ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden_'
required:
- error
- metadata
type: object
HttpStatusCode.NOT_FOUND:
enum:
- 404
type: number
ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes_:
properties:
message:
$ref: '#/components/schemas/BadRequestErrorMessages'
code:
$ref: '#/components/schemas/BadRequestErrorCodes'
status:
$ref: '#/components/schemas/HttpStatusCode.BAD_REQUEST'
data:
additionalProperties: true
type: object
required:
- status
- code
- message
type: object
UUID:
type: string
format: uuid
description: 'Stringified UUIDv4.
See [RFC 4112](https://tools.ietf.org/html/rfc4122)'
pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$
APIResponse_TagPublic_:
properties:
data:
allOf:
- $ref: '#/components/schemas/TagPublic'
required:
- data
type: object
securitySchemes:
apiKey:
type: http
scheme: bearer
x-readme:
explorer-enabled: true
proxy-enabled: false
samples-languages:
- shell
- powershell
- node
- javascript
- python
- c
- clojure
- cplusplus
- csharp
- http
- go
- java
- json
- kotlin
- objectivec
- ocaml
- php
- r
- ruby
- shell
- swift