OpenAPI Specification
openapi: 3.0.3
info:
title: Semaphore Public Dashboards Projects 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: Projects
description: Project management
paths:
/projects:
post:
operationId: Projects.Create
description: Create a project. When creating a project description is ignored.
tags:
- Projects
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: Project
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: Project
readOnly: true
title: Kind
type: string
metadata:
description: Metadata of the project, all fields are read only
properties:
connected:
description: Connection status between Semaphore and repository.
type: boolean
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 project
type: string
id:
description: ID of a Project
example: ed12ab59-9224-45c8-82d6-79bf158aaae6
format: uuid
title: Project.ID
type: string
name:
description: Secret name must match the regex
example: my-secret
minLength: 1
pattern: '^[@: -._a-zA-Z0-9]+$'
title: Secret.Name
type: string
org_id:
description: ID of a Organization
example: ff19729a-a8d5-4a62-8c5c-9bdbabf6607e
format: uuid
title: Organization.ID
type: string
readOnly: true
required:
- id
- name
type: object
spec:
description: Specification of the project
properties:
description:
description: Description of the project
type: string
name:
description: Project name must match the regex
example: my-project
minLength: 1
pattern: \A[\w\-\.]+\z
title: Project.Name
type: string
repository:
description: Repository settings for the project
properties:
forked_pull_requests:
description: Whether to include forked pull requests in the project, read more [here](https://docs.semaphoreci.com/essentials/project-workflow-trigger-options/#exposing-secrets-in-forked-pull-requests).
properties:
allowed_contributors:
description: List of contributors that can create workflows from forked PRs. Empty list means that everyone can.
example: []
items:
description: Contributor handle
title: Contributor
type: string
type: array
allowed_secrets:
description: The allowed_secrets property specifies the array of secrets names that are allowed to be exported into jobs triggered by forked-pull-requests. If the array is empty, no secrets will be exported.
items:
description: Secret name must match the regex
example: my-secret
minLength: 1
pattern: '^[@: -._a-zA-Z0-9]+$'
title: Secret.Name
type: string
type: array
type: object
integration_type:
description: Provider of the repository and authentication method
enum:
- GITHUB_APP
- GITHUB_OAUTH_TOKEN
- BITBUCKET
type: string
pipeline_file:
default: .semaphore/semaphore.yml
description: Path to the pipeline file to run the projec pipelines with
type: string
run_on:
description: Which event will trigger the pipelines for this project. In most cases it is useful set to ["BRANCHES"]
items:
enum:
- BRANCHES
- TAGS
- PULL_REQUESTS
- FORKED_PULL_REQUESTS
title: Projects.RunType
type: string
type: array
status:
description: "The status property is used to specify which Semaphore pipeline(s) will submit a status check on GitHub pull requests.\n A pipeline can create a single status check as a result of a whole pipeline. Or each block in a pipeline can create its own status check.\n For most of the projects `path: \".semaphore/semaphore.yml\", level: \"PIPELINE\"` will be suitable. **If left empty default value assumed.** "
properties:
pipeline_files:
default:
- level: PIPELINE
path: .semaphore/semaphore.yml
items:
description: List of pipeline files that will submit a status check on GitHub pull requests
properties:
level:
description: Level of the status check
enum:
- BLOCK
- PIPELINE
type: string
path:
default: .semaphore/semaphore.yml
description: Path to the pipeline file
type: string
required:
- path
- level
type: object
type: array
type: object
url:
description: URL of the repository
example: git@github.com:semaphoreci/toolbox.git
type: string
whitelist:
description: Whitelist of branches and tags that can be built using this project
properties:
branches:
description: List of branches that can be build. Regular expressions allowed. Empty list means that all branches can. Used only when RunType BRANCHES is included.
items:
type: string
type: array
tags:
description: List of tags that can be build. Regular expressions allowed. Empty list means that all tags can. Used only when RunType TAGS is included.
items:
type: string
type: array
type: object
required:
- url
- integration_type
- run_on
type: object
visibility:
description: Visibility of the project
enum:
- PUBLIC
- PRIVATE
type: string
required:
- repository
- name
type: object
required:
- apiVersion
- kind
- metadata
- spec
title: Projects.Project
type: object
description: Project 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: Project
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: Project
readOnly: true
title: Kind
type: string
metadata:
description: Metadata of the project, all fields are read only
properties:
connected:
description: Connection status between Semaphore and repository.
type: boolean
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 project
type: string
id:
description: ID of a Project
example: ed12ab59-9224-45c8-82d6-79bf158aaae6
format: uuid
title: Project.ID
type: string
name:
description: Secret name must match the regex
example: my-secret
minLength: 1
pattern: '^[@: -._a-zA-Z0-9]+$'
title: Secret.Name
type: string
org_id:
description: ID of a Organization
example: ff19729a-a8d5-4a62-8c5c-9bdbabf6607e
format: uuid
title: Organization.ID
type: string
readOnly: true
required:
- id
- name
type: object
spec:
description: Specification of the project
properties:
description:
description: Description of the project
type: string
name:
description: Project name must match the regex
example: my-project
minLength: 1
pattern: \A[\w\-\.]+\z
title: Project.Name
type: string
repository:
description: Repository settings for the project
properties:
forked_pull_requests:
description: Whether to include forked pull requests in the project, read more [here](https://docs.semaphoreci.com/essentials/project-workflow-trigger-options/#exposing-secrets-in-forked-pull-requests).
properties:
allowed_contributors:
description: List of contributors that can create workflows from forked PRs. Empty list means that everyone can.
example: []
items:
description: Contributor handle
title: Contributor
type: string
type: array
allowed_secrets:
description: The allowed_secrets property specifies the array of secrets names that are allowed to be exported into jobs triggered by forked-pull-requests. If the array is empty, no secrets will be exported.
items:
description: Secret name must match the regex
example: my-secret
minLength: 1
pattern: '^[@: -._a-zA-Z0-9]+$'
title: Secret.Name
type: string
type: array
type: object
integration_type:
description: Provider of the repository and authentication method
enum:
- GITHUB_APP
- GITHUB_OAUTH_TOKEN
- BITBUCKET
type: string
pipeline_file:
default: .semaphore/semaphore.yml
description: Path to the pipeline file to run the projec pipelines with
type: string
run_on:
description: Which event will trigger the pipelines for this project. In most cases it is useful set to ["BRANCHES"]
items:
enum:
- BRANCHES
- TAGS
- PULL_REQUESTS
- FORKED_PULL_REQUESTS
title: Projects.RunType
type: string
type: array
status:
description: "The status property is used to specify which Semaphore pipeline(s) will submit a status check on GitHub pull requests.\n A pipeline can create a single status check as a result of a whole pipeline. Or each block in a pipeline can create its own status check.\n For most of the projects `path: \".semaphore/semaphore.yml\", level: \"PIPELINE\"` will be suitable. **If left empty default value assumed.** "
properties:
pipeline_files:
default:
- level: PIPELINE
path: .semaphore/semaphore.yml
items:
description: List of pipeline files that will submit a status check on GitHub pull requests
properties:
level:
description: Level of the status check
enum:
- BLOCK
- PIPELINE
type: string
path:
default: .semaphore/semaphore.yml
description: Path to the pipeline file
type: string
required:
- path
- level
type: object
type: array
type: object
url:
description: URL of the repository
example: git@github.com:semaphoreci/toolbox.git
type: string
whitelist:
description: Whitelist of branches and tags that can be built using this project
properties:
branches:
description: List of branches that can be build. Regular expressions allowed. Empty list means that all branches can. Used only when RunType BRANCHES is included.
items:
type: string
type: array
tags:
description: List of tags that can be build. Regular expressions allowed. Empty list means that all tags can. Used only when RunType TAGS is included.
items:
type: string
type: array
type: object
required:
- url
- integration_type
- run_on
type: object
visibility:
description: Visibility of the project
enum:
- PUBLIC
- PRIVATE
type: string
required:
- repository
- name
type: object
required:
- apiVersion
- kind
- metadata
- spec
title: Projects.Project
type: object
description: Created project
'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: Projects.List
description: List projects in organization.
tags:
- Projects
parameters:
- description: UUID of the project owner
example: 7d36df70-6eab-4768-83d8-090f44f47235
in: query
name: owner_uuid
required: false
schema:
format: uuid
type: string
- description: URL of the repository the project is associated with
example: git@github.com:semaphoreci/toolbox.git
in: query
name: repo_url
required: false
schema:
type: string
- description: "Direction of the pagination.\n `NEXT` will fetch projects after the provided token, `PREVIOUS` will fetch projects before the provided token"
in: query
name: direction
required: false
schema:
default: NEXT
enum:
- NEXT
- PREVIOUS
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: Project
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: Project
readOnly: true
title: Kind
type: string
metadata:
description: Metadata of the project, all fields are read only
properties:
connected:
description: Connection status between Semaphore and repository.
type: boolean
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 project
type: string
id:
description: ID of a Project
example: ed12ab59-9224-45c8-82d6-79bf158aaae6
format: uuid
title: Project.ID
type: string
name:
description: Secret name must match the regex
example: my-secret
minLength: 1
pattern: '^[@: -._a-zA-Z0-9]+$'
title: Secret.Name
type: string
org_id:
description: ID of a Organization
example: ff19729a-a8d5-4a62-8c5c-9bdbabf6607e
format: uuid
title: Organization.ID
type: string
readOnly: true
required:
- id
- name
type: object
spec:
description: Specification of the project
properties:
description:
description: Description of the project
type: string
name:
description: Project name must match the regex
example: my-project
minLength: 1
pattern: \A[\w\-\.]+\z
title: Project.Name
type: string
repository:
description: Repository settings for the project
properties:
forked_pull_requests:
description: Whether to include forked pull requests in the project, read more [here](https://docs.semaphoreci.com/essentials/project-workflow-trigger-options/#exposing-secrets-in-forked-pull-requests).
properties:
allowed_contributors:
description: List of contributors that can create workflows from forked PRs. Empty list means that everyone can.
example: []
items:
description: Contributor handle
title: Contributor
type: string
type: array
allowed_secrets:
description: The allowed_secrets property specifies the array of secrets names that are allowed to be exported into jobs triggered by forked-pull-requests. If the array is empty, no secrets will be exported.
items:
description: Secret name must match the regex
example: my-secret
minLength: 1
pattern: '^[@: -._a-zA-Z0-9]+$'
title: Secret.Name
type: string
type: array
type: object
integration_type:
description: Provider of the repository and authentication method
enum:
- GITHUB_APP
- GITHUB_OAUTH_TOKEN
- BITBUCKET
type: string
pipeline_file:
default: .semaphore/semaphore.yml
description: Path to the pipeline file to run the projec pipelines with
type: string
run_on:
description: Which event will trigger the pipelines for this project. In most cases it is useful set to ["BRANCHES"]
items:
enum:
- BRANCHES
- TAGS
- PULL_REQUESTS
- FORKED_PULL_REQUESTS
title: Projects.RunType
type: string
type: array
status:
description: "The status property is used to specify which Semaphore pipeline(s) will submit a status check on GitHub pull requests.\n A pipeline can create a single status check as a result of a whole pipeline. Or each block in a pipeline can create its own status check.\n For most of the projects `path: \".semaphore/semaphore.yml\", level: \"PIPELINE\"` will be suitable. **If left empty default value assumed.** "
properties:
# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/semaphore/refs/heads/main/openapi/semaphore-projects-api-openapi.yml