openapi: 3.0.3
info:
title: Semaphore Public Dashboards API
description: 'The Semaphore Public API is a RESTful API that allows you to interact with Semaphore CI/CD.
## Authorization
Authorization is done via bearer token. You can obtain a token by visiting your [account settings](https://me.semaphoreci.com/account).
## Pagination with link headers
Each list request supports pagination. List responses include a [link header](https://datatracker.ietf.org/doc/html/rfc5988#section-5) with the pagination URLs.
Link headers contain next, previous, first relative URLs.
'
version: v2
contact:
url: https://semaphore.io/contact
email: support@semaphoreci.com
termsOfService: https://semaphore.io/terms
license:
name: Proprietary
url: https://semaphore.io/terms
servers:
- url: https://{org_name}.semaphoreci.com/api/v2
variables:
org_name:
default: me
description: Organization name
security:
- authorization: []
tags:
- name: Dashboards
description: Dashboard management
paths:
/dashboards:
post:
operationId: Dashboards.Create
description: Create a dashboard.
tags:
- Dashboards
requestBody:
content:
application/json:
schema:
properties:
apiVersion:
default: v2
description: "ApiVersion defines the versioned schema of this representation of an object.\n Servers should convert recognized schemas to the latest internal value, and may reject\n unrecognized values."
example: v2
readOnly: true
title: ApiVersion
type: string
kind:
default: Dashboard
description: "Kind is a string value representing the REST resource this object represents.\n Servers may infer this from the endpoint the client submits requests to. Cannot be\n updated. In CamelCase."
example: Dashboard
readOnly: true
title: Kind
type: string
metadata:
description: Metadata of the dashboard, all fields are read only
properties:
created_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
id:
description: ID of a Dashboard
example: 645d2d5b-603c-49b2-9022-594297b60aa1
format: uuid
title: Dashboard.ID
type: string
name:
description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
org_id:
description: ID of a Organization
example: a44db728-f627-4560-a548-9f61d61e8780
format: uuid
title: Organization.ID
type: string
title:
description: Title of the dashboard
type: string
updated_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
readOnly: true
required:
- id
- name
type: object
spec:
description: Specification of the dashboard
properties:
name:
description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
title:
description: Title of the dashboard
type: string
widgets:
description: List of widgets on the dashboard
items:
description: Widget on the dashboard
properties:
filters:
additionalProperties:
type: string
description: Object with filters for the widget
type: object
name:
description: Name of the widget
type: string
type:
description: Type of the widget
type: string
required:
- name
- type
type: object
type: array
required:
- name
- title
- widgets
type: object
required:
- apiVersion
- kind
- metadata
- spec
title: Dashboards.Dashboard
type: object
description: Dashboard to be created
required: false
responses:
'200':
content:
application/json:
schema:
properties:
apiVersion:
default: v2
description: "ApiVersion defines the versioned schema of this representation of an object.\n Servers should convert recognized schemas to the latest internal value, and may reject\n unrecognized values."
example: v2
readOnly: true
title: ApiVersion
type: string
kind:
default: Dashboard
description: "Kind is a string value representing the REST resource this object represents.\n Servers may infer this from the endpoint the client submits requests to. Cannot be\n updated. In CamelCase."
example: Dashboard
readOnly: true
title: Kind
type: string
metadata:
description: Metadata of the dashboard, all fields are read only
properties:
created_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
id:
description: ID of a Dashboard
example: 645d2d5b-603c-49b2-9022-594297b60aa1
format: uuid
title: Dashboard.ID
type: string
name:
description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
org_id:
description: ID of a Organization
example: a44db728-f627-4560-a548-9f61d61e8780
format: uuid
title: Organization.ID
type: string
title:
description: Title of the dashboard
type: string
updated_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
readOnly: true
required:
- id
- name
type: object
spec:
description: Specification of the dashboard
properties:
name:
description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
title:
description: Title of the dashboard
type: string
widgets:
description: List of widgets on the dashboard
items:
description: Widget on the dashboard
properties:
filters:
additionalProperties:
type: string
description: Object with filters for the widget
type: object
name:
description: Name of the widget
type: string
type:
description: Type of the widget
type: string
required:
- name
- type
type: object
type: array
required:
- name
- title
- widgets
type: object
required:
- apiVersion
- kind
- metadata
- spec
title: Dashboards.Dashboard
type: object
description: Created dashboard
'400':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Bad Request
'401':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Unauthorized
'404':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Not Found
'422':
content:
application/json:
schema:
description: Resource validation failed
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
errors:
items:
properties:
field:
type: string
message:
type: string
type: object
type: array
message:
type: string
title: Error.Validation
type: object
description: Validation Failed
'500':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Internal Server Error
security:
- authorization: []
get:
operationId: Dashboards.List
description: "List all organization level dashboards.\n If the response does not fit all the dashboards refer to the link header to get next page url."
tags:
- Dashboards
parameters:
- description: Ordering of the dashboards
in: query
name: order
required: false
schema:
default: BY_NAME_ASC
enum:
- BY_NAME_ASC
- BY_CREATE_TIME_ASC
type: string
- description: Starting point for listing, if you are fetching first page leave it empty
in: query
name: page_token
required: false
schema:
default: ''
type: string
- description: Page size
in: query
name: page_size
required: false
schema:
default: 20
maximum: 100
minimum: 1
title: PageSize
type: integer
responses:
'200':
content:
application/json:
schema:
items:
properties:
apiVersion:
default: v2
description: "ApiVersion defines the versioned schema of this representation of an object.\n Servers should convert recognized schemas to the latest internal value, and may reject\n unrecognized values."
example: v2
readOnly: true
title: ApiVersion
type: string
kind:
default: Dashboard
description: "Kind is a string value representing the REST resource this object represents.\n Servers may infer this from the endpoint the client submits requests to. Cannot be\n updated. In CamelCase."
example: Dashboard
readOnly: true
title: Kind
type: string
metadata:
description: Metadata of the dashboard, all fields are read only
properties:
created_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
id:
description: ID of a Dashboard
example: 645d2d5b-603c-49b2-9022-594297b60aa1
format: uuid
title: Dashboard.ID
type: string
name:
description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
org_id:
description: ID of a Organization
example: a44db728-f627-4560-a548-9f61d61e8780
format: uuid
title: Organization.ID
type: string
title:
description: Title of the dashboard
type: string
updated_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
readOnly: true
required:
- id
- name
type: object
spec:
description: Specification of the dashboard
properties:
name:
description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
title:
description: Title of the dashboard
type: string
widgets:
description: List of widgets on the dashboard
items:
description: Widget on the dashboard
properties:
filters:
additionalProperties:
type: string
description: Object with filters for the widget
type: object
name:
description: Name of the widget
type: string
type:
description: Type of the widget
type: string
required:
- name
- type
type: object
type: array
required:
- name
- title
- widgets
type: object
required:
- apiVersion
- kind
- metadata
- spec
title: Dashboards.Dashboard
type: object
title: Dashboards.ListResponse
type: array
description: List of dashboards
'400':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Bad Request
'401':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Unauthorized
'404':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Not Found
'422':
content:
application/json:
schema:
description: Resource validation failed
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
errors:
items:
properties:
field:
type: string
message:
type: string
type: object
type: array
message:
type: string
title: Error.Validation
type: object
description: Validation Failed
'500':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Internal Server Error
security:
- authorization: []
/dashboards/{id_or_name}:
delete:
operationId: Dashboards.Delete
description: Delete a dashboard by its id or name.
tags:
- Dashboards
parameters:
- description: Id or name of the dashboard
in: path
name: id_or_name
required: true
schema:
anyOf:
- description: ID of a Dashboard
example: 825c58c3-bf1a-4680-a186-21df37d5907d
format: uuid
title: Dashboard.ID
type: string
- description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
responses:
'200':
content:
application/json:
schema:
description: ''
properties:
dashboard_id:
description: ID of a Dashboard
example: ec3078ea-ba19-4f50-927c-3fc8174899bd
format: uuid
title: Dashboard.ID
type: string
title: Dashboards.DeleteResponse
type: object
description: ID of the deleted dashboard
'400':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Bad Request
'401':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Unauthorized
'404':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Not Found
'422':
content:
application/json:
schema:
description: Resource validation failed
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
errors:
items:
properties:
field:
type: string
message:
type: string
type: object
type: array
message:
type: string
title: Error.Validation
type: object
description: Validation Failed
'500':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Internal Server Error
security:
- authorization: []
get:
operationId: Dashboards.Describe
description: Describe a dashboard by its id or name.
tags:
- Dashboards
parameters:
- description: Id or name of the dashboard
in: path
name: id_or_name
required: true
schema:
anyOf:
- description: ID of a Dashboard
example: 2757e6f0-fcdb-4aa7-b24f-9b76b76efc0d
format: uuid
title: Dashboard.ID
type: string
- description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
responses:
'200':
content:
application/json:
schema:
properties:
apiVersion:
default: v2
description: "ApiVersion defines the versioned schema of this representation of an object.\n Servers should convert recognized schemas to the latest internal value, and may reject\n unrecognized values."
example: v2
readOnly: true
title: ApiVersion
type: string
kind:
default: Dashboard
description: "Kind is a string value representing the REST resource this object represents.\n Servers may infer this from the endpoint the client submits requests to. Cannot be\n updated. In CamelCase."
example: Dashboard
readOnly: true
title: Kind
type: string
metadata:
description: Metadata of the dashboard, all fields are read only
properties:
created_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
id:
description: ID of a Dashboard
example: 645d2d5b-603c-49b2-9022-594297b60aa1
format: uuid
title: Dashboard.ID
type: string
name:
description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
org_id:
description: ID of a Organization
example: a44db728-f627-4560-a548-9f61d61e8780
format: uuid
title: Organization.ID
type: string
title:
description: Title of the dashboard
type: string
updated_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
readOnly: true
required:
- id
- name
type: object
spec:
description: Specification of the dashboard
properties:
name:
description: Dashboard name must match the regex
example: my-dashboard
minLength: 1
pattern: \A(?!-)[a-z0-9\-]+\z
title: Dashboards.Name
type: string
title:
description: Title of the dashboard
type: string
widgets:
description: List of widgets on the dashboard
items:
description: Widget on the dashboard
properties:
filters:
additionalProperties:
type: string
description: Object with filters for the widget
type: object
name:
description: Name of the widget
type: string
type:
description: Type of the widget
type: string
required:
- name
- type
type: object
type: array
required:
- name
- title
- widgets
type: object
required:
- apiVersion
- kind
- metadata
- spec
title: Dashboards.Dashboard
type: object
description: Dashboard
'400':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Bad Request
'401':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Unauthorized
'404':
content:
application/json:
schema:
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
message:
type: string
title: Error
type: object
description: Not Found
'422':
content:
application/json:
schema:
description: Resource validation failed
properties:
documentation_url:
example: https://docs.semaphoreci.com/api/error-codes/bad-request
format: uri
type: string
errors:
items:
properties:
field:
type: string
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/semaphore/refs/heads/main/openapi/semaphore-dashboards-api-openapi.yml