OpenAPI Specification
openapi: 3.0.3
info:
title: Semaphore Public Dashboards DeploymentTargets 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: DeploymentTargets
description: Deployment target management
paths:
/projects/{project_id_or_name}/deployment_targets:
post:
operationId: DeploymentTargets.Create
description: Create a deployment target for the project.
tags:
- DeploymentTargets
parameters:
- description: Id or name of the project
in: path
name: project_id_or_name
required: true
schema:
anyOf:
- description: ID of a Project
example: c92c0098-5842-4867-b2d9-de8aae1505d2
format: uuid
title: Project.ID
type: string
- description: Project name must match the regex
example: my-project
minLength: 1
pattern: \A[\w\-\.]+\z
title: Project.Name
type: string
requestBody:
content:
application/json:
schema:
properties:
deployment_target:
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: DeploymentTarget
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: DeploymentTarget
readOnly: true
title: Kind
type: string
metadata:
description: Metadata of the deployment targets, all fields are read only
properties:
created_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
created_by:
properties:
id:
description: ID of a User
example: 18b40eaf-ce10-49c3-93f2-e4fe72d5160b
format: uuid
title: User.ID
type: string
title: User
type: object
description:
description: Description of the deployment target
type: string
id:
description: ID of a DeploymentTarget
example: 9c777b65-213f-4fe1-bc6b-727d2cdde97d
format: uuid
title: DeploymentTarget.ID
type: string
last_deployment:
description: A deployment history item contains relevant details about deployments triggered for a deployment target.
nullable: true
properties:
env_vars:
description: Environment variables of the deployment target
items:
description: EnvVar
properties:
name:
description: Name of the environment variable
example: MY_SECRET
minLength: 1
type: string
value:
description: Value of the environment variable
example: secret
minLength: 1
type: string
required:
- name
- value
title: Secrets.Secret.EnvVar
type: object
type: array
id:
description: ID of a Deployment
example: a0424427-ff28-4f77-a893-0fdf5f50c380
format: uuid
title: Deployment.ID
type: string
origin_pipeline_id:
description: ID of a Pipeline
example: 97ba55d1-90d7-40b9-a2dd-bdbd02389b58
format: uuid
nullable: true
title: Pipeline.ID
type: string
pipeline_id:
description: ID of a Pipeline
example: adc5a26f-4077-47bc-8d4f-cb4467f2c103
format: uuid
nullable: true
title: Pipeline.ID
type: string
state:
description: The state of the last deployment of the deployment target
enum:
- PENDING
- STARTED
- FAILED
type: string
state_message:
description: The message of the last deployment of the deployment target
type: string
target_id:
description: ID of a DeploymentTarget
example: 4a9e9001-6703-4815-9c19-ed2e9e8c87ea
format: uuid
title: DeploymentTarget.ID
type: string
target_name:
description: The name of the deployment target
type: string
triggered_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
triggered_by:
properties:
id:
description: ID of a User
example: 18b40eaf-ce10-49c3-93f2-e4fe72d5160b
format: uuid
title: User.ID
type: string
title: User
type: object
title: DeploymentTargets.HistoryItem
type: object
name:
description: 'DeploymentTargets name must be unique on project level, must match the name regex: `^[A-Za-z0-9_.-]+$`'
example: production
minLength: 1
pattern: ^[A-Za-z0-9_\.\-]+$
title: DeploymentTargets.Name
type: string
org_id:
description: ID of a Organization
example: 02b7c528-b0f1-4266-8e5e-10b7b984e76a
format: uuid
title: Organization.ID
type: string
project_id:
description: ID of a Project
example: 726dbefd-b30c-4c80-bc9a-c0613968a2ca
format: uuid
title: Project.ID
type: string
state:
description: "State of the deployment target.\n - `SYNCING` - Deployment Target secret is synchronizing\n - `USABLE` - Deployment Target is active and can be used or modified\n - `UNUSABLE` - Deployment Target is corrupted and cannot be used or modified\n - `CORDONED` - Deployment Target has been cordoned and deactivated\n "
enum:
- SYNCING
- USABLE
- UNUSABLE
- CORDONED
type: string
updated_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
updated_by:
properties:
id:
description: ID of a User
example: 18b40eaf-ce10-49c3-93f2-e4fe72d5160b
format: uuid
title: User.ID
type: string
title: User
type: object
readOnly: true
required:
- id
- name
- project_id
type: object
spec:
description: Specification of the deployment target
properties:
active:
description: The state of the deployment target, true if the deployment is not cordoned
type: boolean
bookmark_parameters:
description: The names of the promotion parameters. You can later use values of these parameters to filter deployments in deployment history.
items:
description: The name of the promotion parameter
type: string
maxItems: 3
minItems: 0
type: array
description:
description: Description of the deployment target
type: string
env_vars:
description: Environment variables of the deployment target, only in create requests.
items:
description: EnvVar
properties:
name:
description: Name of the environment variable
example: MY_SECRET
minLength: 1
type: string
value:
description: Value of the environment variable
example: secret
minLength: 1
type: string
required:
- name
- value
title: Secrets.Secret.EnvVar
type: object
type: array
files:
description: Files of the deployment target, only in create requests.
items:
description: File
properties:
content:
description: base64 encoded content of the file or a md5 checksum
type: string
path:
description: Name of the file. Both absolute and relative paths are allowed.
example: /path/to/file
minLength: 1
type: string
required:
- path
- content
title: Secrets.Secret.File
type: object
type: array
name:
description: 'DeploymentTargets name must be unique on project level, must match the name regex: `^[A-Za-z0-9_.-]+$`'
example: production
minLength: 1
pattern: ^[A-Za-z0-9_\.\-]+$
title: DeploymentTargets.Name
type: string
object_rules:
description: "Configure which branches, tags or PRs can trigger a deployment.\n **If left empty all branches, tags or PRs can trigger a deployment.**"
properties:
branches:
oneOf:
- description: Allows all branch to trigger a deployment
enum:
- ALL
title: DeploymentTargets.DeploymentTarget.ObjectRule.Branch.All
type: string
- description: The pattern to match against the branch name
title: DeploymentTargets.DeploymentTarget.ObjectRule.Branch.MatchType
type: array
title: DeploymentTargets.DeploymentTarget.ObjectRule.Branch
prs:
default: NONE
description: Allows all or none of the PRs to trigger a deployment
enum:
- ALL
- NONE
type: string
tags:
oneOf:
- description: Allows all tag to trigger a deployment
enum:
- ALL
title: DeploymentTargets.DeploymentTarget.ObjectRule.Tag.All
type: string
- description: The pattern to match against the tag name
title: DeploymentTargets.DeploymentTarget.ObjectRule.Tag.MatchType
type: array
title: DeploymentTargets.DeploymentTarget.ObjectRule.Tag
type: object
subject_rules:
description: '
Configure who can trigger a deployment.
**If left empty all users can trigger a deployment.**
'
properties:
any:
default: false
description: Allows any user or auto-promotion to trigger a deployment, if true all other rules are ignored and all users can trigger a deployment
type: boolean
auto:
description: Allows auto-promotions to be triggered
type: boolean
roles:
description: "The list of roles of users that are allowed to trigger a deployment,\n by default project roles are `Reader`, `Contributor` and `Admin`, read more [here](https://docs.semaphoreci.com/security/default-roles/#project-roles).\n Role names are case insensitive."
items:
description: The name of the role.
example: Contributor
type: string
type: array
users:
description: The list of users that are allowed to trigger a deployment
items:
anyOf:
- description: The uuid of the user
format: uuid
type: string
- description: The git handle of the user
type: string
description: The git handle or id of the user
type: array
type: object
url:
description: The URL of the target
type: string
required:
- name
type: object
required:
- apiVersion
- kind
- spec
title: DeploymentTargets.DeploymentTarget
type: object
unique_token:
description: "The unique value used as an idempotency token.\n If there are multiple requests with the same `unique_token` values only the first one will be processed,\n and the rest will be disregarded but the response will be 200 OK as if those requests were processed successfully."
type: string
required:
- unique_token
- deployment_target
title: DeploymentTargets.CreateRequest
type: object
description: Deployment target to be created and a unique token.
required: true
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: DeploymentTarget
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: DeploymentTarget
readOnly: true
title: Kind
type: string
metadata:
description: Metadata of the deployment targets, all fields are read only
properties:
created_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
created_by:
properties:
id:
description: ID of a User
example: 18b40eaf-ce10-49c3-93f2-e4fe72d5160b
format: uuid
title: User.ID
type: string
title: User
type: object
description:
description: Description of the deployment target
type: string
id:
description: ID of a DeploymentTarget
example: 9c777b65-213f-4fe1-bc6b-727d2cdde97d
format: uuid
title: DeploymentTarget.ID
type: string
last_deployment:
description: A deployment history item contains relevant details about deployments triggered for a deployment target.
nullable: true
properties:
env_vars:
description: Environment variables of the deployment target
items:
description: EnvVar
properties:
name:
description: Name of the environment variable
example: MY_SECRET
minLength: 1
type: string
value:
description: Value of the environment variable
example: secret
minLength: 1
type: string
required:
- name
- value
title: Secrets.Secret.EnvVar
type: object
type: array
id:
description: ID of a Deployment
example: a0424427-ff28-4f77-a893-0fdf5f50c380
format: uuid
title: Deployment.ID
type: string
origin_pipeline_id:
description: ID of a Pipeline
example: 97ba55d1-90d7-40b9-a2dd-bdbd02389b58
format: uuid
nullable: true
title: Pipeline.ID
type: string
pipeline_id:
description: ID of a Pipeline
example: adc5a26f-4077-47bc-8d4f-cb4467f2c103
format: uuid
nullable: true
title: Pipeline.ID
type: string
state:
description: The state of the last deployment of the deployment target
enum:
- PENDING
- STARTED
- FAILED
type: string
state_message:
description: The message of the last deployment of the deployment target
type: string
target_id:
description: ID of a DeploymentTarget
example: 4a9e9001-6703-4815-9c19-ed2e9e8c87ea
format: uuid
title: DeploymentTarget.ID
type: string
target_name:
description: The name of the deployment target
type: string
triggered_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
triggered_by:
properties:
id:
description: ID of a User
example: 18b40eaf-ce10-49c3-93f2-e4fe72d5160b
format: uuid
title: User.ID
type: string
title: User
type: object
title: DeploymentTargets.HistoryItem
type: object
name:
description: 'DeploymentTargets name must be unique on project level, must match the name regex: `^[A-Za-z0-9_.-]+$`'
example: production
minLength: 1
pattern: ^[A-Za-z0-9_\.\-]+$
title: DeploymentTargets.Name
type: string
org_id:
description: ID of a Organization
example: 02b7c528-b0f1-4266-8e5e-10b7b984e76a
format: uuid
title: Organization.ID
type: string
project_id:
description: ID of a Project
example: 726dbefd-b30c-4c80-bc9a-c0613968a2ca
format: uuid
title: Project.ID
type: string
state:
description: "State of the deployment target.\n - `SYNCING` - Deployment Target secret is synchronizing\n - `USABLE` - Deployment Target is active and can be used or modified\n - `UNUSABLE` - Deployment Target is corrupted and cannot be used or modified\n - `CORDONED` - Deployment Target has been cordoned and deactivated\n "
enum:
- SYNCING
- USABLE
- UNUSABLE
- CORDONED
type: string
updated_at:
description: Timestamp in ISO 8601 format
format: date-time
title: Timestamp
type: string
updated_by:
properties:
id:
description: ID of a User
example: 18b40eaf-ce10-49c3-93f2-e4fe72d5160b
format: uuid
title: User.ID
type: string
title: User
type: object
readOnly: true
required:
- id
- name
- project_id
type: object
spec:
description: Specification of the deployment target
properties:
active:
description: The state of the deployment target, true if the deployment is not cordoned
type: boolean
bookmark_parameters:
description: The names of the promotion parameters. You can later use values of these parameters to filter deployments in deployment history.
items:
description: The name of the promotion parameter
type: string
maxItems: 3
minItems: 0
type: array
description:
description: Description of the deployment target
type: string
env_vars:
description: Environment variables of the deployment target, only in create requests.
items:
description: EnvVar
properties:
name:
description: Name of the environment variable
example: MY_SECRET
minLength: 1
type: string
value:
description: Value of the environment variable
example: secret
minLength: 1
type: string
required:
- name
- value
title: Secrets.Secret.EnvVar
type: object
type: array
files:
description: Files of the deployment target, only in create requests.
items:
description: File
properties:
content:
description: base64 encoded content of the file or a md5 checksum
type: string
path:
description: Name of the file. Both absolute and relative paths are allowed.
example: /path/to/file
minLength: 1
type: string
required:
- path
- content
title: Secrets.Secret.File
type: object
type: array
name:
description: 'DeploymentTargets name must be unique on project level, must match the name regex: `^[A-Za-z0-9_.-]+$`'
example: production
minLength: 1
pattern: ^[A-Za-z0-9_\.\-]+$
title: DeploymentTargets.Name
type: string
object_rules:
description: "Configure which branches, tags or PRs can trigger a deployment.\n **If left empty all branches, tags or PRs can trigger a deployment.**"
properties:
branches:
oneOf:
- description: Allows all branch to trigger a deployment
enum:
- ALL
title: DeploymentTargets.DeploymentTarget.ObjectRule.Branch.All
type: string
- description: The pattern to match against the branch name
title: DeploymentTargets.DeploymentTarget.ObjectRule.Branch.MatchType
type: array
title: DeploymentTargets.DeploymentTarget.ObjectRule.Branch
prs:
default: NONE
description: Allows all or none of the PRs to trigger a deployment
enum:
- ALL
- NONE
type: string
tags:
oneOf:
- description: Allows all tag to trigger a deployment
enum:
- ALL
title
# --- truncated at 32 KB (136 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/semaphore/refs/heads/main/openapi/semaphore-deploymenttargets-api-openapi.yml