swagger: '2.0' info: title: SEMAPHORE description: Semaphore API version: "2.2.0" host: localhost:3000 consumes: - application/json produces: - application/json - text/plain; charset=utf-8 tags: - name: authentication description: Authentication, Logout & API Tokens - name: project description: Everything related to a project - name: user description: User-related API schemes: - http - https basePath: /api definitions: Pong: type: string x-example: pong Login: type: object properties: auth: type: string description: Username/Email address x-example: user@semaphore.com password: type: string format: password description: Password LoginMetadata: type: object properties: oidc_providers: type: array description: List of OIDC providers items: type: object properties: id: type: string description: ID of the provider, used in the login URL x-example: mysso name: type: string description: Text to show on the login button x-example: Sign in with MySSO UserRequest: type: object properties: name: type: string x-example: Integration Test User example: Integration Test User username: type: string x-example: test-user example: test-user email: type: string x-example: test@ansiblesemaphore.test example: test@ansiblesemaphore.test alert: type: boolean admin: type: boolean UserPutRequest: type: object properties: name: type: string x-example: Integration Test User2 example: Integration Test User2 username: type: string x-example: test-user2 example: test-user2 email: type: string x-example: test2@ansiblesemaphore.test example: test2@ansiblesemaphore.test alert: type: boolean admin: type: boolean User: type: object properties: id: type: integer minimum: 1 name: type: string username: type: string email: type: string created: type: string alert: type: boolean admin: type: boolean ProjectUser: type: object properties: id: type: integer minimum: 1 name: type: string username: type: string APIToken: type: object properties: id: type: string created: type: string # pattern: ^\d{4}-(?:0[0-9]{1}|1[0-2]{1})-[0-9]{2}T\d{2}:\d{2}:\d{2}Z$ expired: type: boolean user_id: type: integer minimum: 1 ProjectRequest: type: object properties: name: type: string example: Test alert: type: boolean alert_chat: type: string example: Test max_parallel_tasks: type: integer minimum: 0 Project: type: object properties: id: type: integer minimum: 1 name: type: string example: Test created: type: string # pattern: ^\d{4}-(?:0[0-9]{1}|1[0-2]{1})-[0-9]{2}T\d{2}:\d{2}:\d{2}Z$ alert: type: boolean alert_chat: type: string example: Test max_parallel_tasks: type: integer minimum: 0 AccessKeyRequest: type: object properties: name: type: string x-example: None example: None type: type: string enum: [none,ssh,login_password] x-example: none project_id: type: integer minimum: 1 x-example: 2 login_password: type: object properties: password: type: string x-example: password example: password login: type: string x-example: username example: username ssh: type: object properties: login: type: string x-example: user example: user private_key: type: string x-example: private key example: private key AccessKey: type: object properties: id: type: integer name: type: string example: Test type: type: string enum: [none,ssh,login_password] project_id: type: integer login_password: type: object properties: password: type: string x-example: password example: password login: type: string x-example: username example: username ssh: type: object properties: login: type: string x-example: user example: user private_key: type: string x-example: private key example: private key EnvironmentRequest: type: object properties: name: type: string example: Test project_id: type: integer minimum: 1 password: type: string json: type: string example: '{}' env: type: string example: '{}' Environment: type: object properties: id: type: integer minimum: 1 name: type: string example: Test project_id: type: integer minimum: 1 password: type: string json: type: string example: '{}' env: type: string example: '{}' InventoryRequest: type: object properties: name: type: string example: Test project_id: type: integer minimum: 1 inventory: type: string ssh_key_id: type: integer minimum: 1 become_key_id: type: integer minimum: 1 type: type: string enum: [static, static-yaml, file] Inventory: type: object properties: id: type: integer name: type: string example: Test project_id: type: integer inventory: type: string ssh_key_id: type: integer become_key_id: type: integer type: type: string enum: [static, static-yaml, file] RepositoryRequest: type: object properties: name: type: string example: Test project_id: type: integer git_url: type: string example: git@example.com git_branch: type: string example: master ssh_key_id: type: integer Repository: type: object properties: id: type: integer name: type: string example: Test project_id: type: integer git_url: type: string example: git@example.com git_branch: type: string example: master ssh_key_id: type: integer Task: type: object properties: id: type: integer example: 23 template_id: type: integer status: type: string debug: type: boolean playbook: type: string environment: type: string limit: type: string TaskOutput: type: object properties: task_id: type: integer example: 23 task: type: string time: type: string format: date-time output: type: string TemplateRequest: type: object properties: project_id: type: integer minimum: 1 inventory_id: type: integer minimum: 1 repository_id: type: integer minimum: 1 environment_id: type: integer minimum: 1 view_id: type: integer minimum: 1 name: type: string example: Test playbook: type: string example: test.yml arguments: type: string example: '[]' description: type: string example: Hello, World! allow_override_args_in_task: type: boolean example: false limit: type: string example: '' suppress_success_alerts: type: boolean survey_vars: type: array items: $ref: "#/definitions/TemplateSurveyVar" Template: type: object properties: id: type: integer minimum: 1 project_id: type: integer minimum: 1 inventory_id: type: integer minimum: 1 repository_id: type: integer environment_id: type: integer minimum: 1 view_id: type: integer minimum: 1 name: type: string example: Test playbook: type: string example: test.yml arguments: type: string example: '[]' description: type: string example: Hello, World! allow_override_args_in_task: type: boolean example: false suppress_success_alerts: type: boolean app: type: string TemplateSurveyVar: type: object properties: name: type: string title: type: string description: type: string type: type: string example: String => "", Integer => "int" required: type: boolean ScheduleRequest: type: object properties: id: type: integer cron_format: type: string x-example: "* * * 1 *" example: "* * * 1 *" project_id: type: integer template_id: type: integer Schedule: type: object properties: id: type: integer cron_format: type: string project_id: type: integer template_id: type: integer ViewRequest: type: object properties: title: type: string example: Test project_id: type: integer minimum: 1 position: type: integer minimum: 1 View: type: object properties: id: type: integer title: type: string project_id: type: integer position: type: integer Runner: type: object properties: token: type: string Event: type: object properties: project_id: type: integer user_id: type: integer object_id: type: - integer - 'null' object_type: type: - string - 'null' description: type: string InfoType: type: object properties: version: type: string updateBody: type: string update: type: object properties: tag_name: type: string securityDefinitions: cookie: type: apiKey name: Cookie in: header bearer: type: apiKey name: Authorization in: header security: - bearer: [] - cookie: [] parameters: project_id: name: project_id description: Project ID in: path type: integer required: true x-example: 1 user_id: name: user_id description: User ID in: path type: integer required: true x-example: 2 key_id: name: key_id description: key ID in: path type: integer required: true x-example: 3 repository_id: name: repository_id description: repository ID in: path type: integer required: true x-example: 4 inventory_id: name: inventory_id description: inventory ID in: path type: integer required: true x-example: 5 environment_id: name: environment_id description: environment ID in: path type: integer required: true x-example: 6 template_id: name: template_id description: template ID in: path type: integer required: true x-example: 7 task_id: name: task_id description: task ID in: path type: integer required: true x-example: 8 schedule_id: name: schedule_id description: schedule ID in: path type: integer required: true x-example: 9 view_id: name: view_id description: view ID in: path type: integer required: true x-example: 10 paths: /ping: get: summary: PING test produces: - text/plain security: [] # No security responses: 200: description: Successful "PONG" reply schema: $ref: "#/definitions/Pong" headers: content-type: type: string x-example: text/plain; charset=utf-8 /ws: get: summary: Websocket handler schemes: - ws - wss responses: 200: description: OK 401: description: not authenticated /info: get: summary: Fetches information about semaphore description: you must be authenticated to use this responses: 200: description: ok schema: $ref: "#/definitions/InfoType" # Authentication /auth/login: get: tags: - authentication summary: Fetches login metadata description: Fetches metadata for login, such as available OIDC providers security: [] responses: 200: description: Login metadata schema: $ref: "#/definitions/LoginMetadata" post: tags: - authentication summary: Performs Login description: Upon success you will be logged in security: [] # No security parameters: - name: Login Body in: body required: true schema: $ref: '#/definitions/Login' responses: 204: description: You are logged in 400: description: something in body is missing / is invalid /auth/logout: post: tags: - authentication summary: Destroys current session responses: 204: description: Your session was successfully nuked /auth/oidc/{provider_id}/login: parameters: - name: provider_id in: path type: string required: true x-example: "mysso" get: tags: - authentication summary: Begin OIDC authentication flow and redirect to OIDC provider description: The user agent is redirected to this endpoint when chosing to sign in via OIDC responses: 302: description: Redirection to the OIDC provider on success, or to the login page on error /auth/oidc/{provider_id}/redirect: parameters: - name: provider_id in: path type: string required: true x-example: "mysso" get: tags: - authentication summary: Finish OIDC authentication flow, upon succes you will be logged in description: The user agent is redirected here by the OIDC provider to complete authentication responses: 302: description: Redirection to the Semaphore root URL on success, or to the login page on error # User Tokens /user/: get: tags: - user summary: Fetch logged in user responses: 200: description: User schema: $ref: "#/definitions/User" /user/tokens: get: tags: - authentication - user summary: Fetch API tokens for user responses: 200: description: API Tokens schema: type: array items: $ref: "#/definitions/APIToken" post: tags: - authentication - user summary: Create an API token responses: 201: description: API Token schema: $ref: "#/definitions/APIToken" /user/tokens/{api_token_id}: parameters: - name: api_token_id in: path type: string required: true x-example: "kwofd61g93-yuqvex8efmhjkgnbxlo8mp1tin6spyhu=" delete: tags: - authentication - user summary: Expires API token responses: 204: description: Expired API Token # User Profiles /users: get: tags: - user summary: Fetches all users responses: 200: description: Users schema: type: array items: $ref: "#/definitions/User" post: tags: - user summary: Creates a user consumes: - application/json parameters: - name: User in: body required: true schema: $ref: "#/definitions/UserRequest" responses: 400: description: User creation failed 201: description: User created schema: $ref: "#/definitions/User" /users/{user_id}/: parameters: - $ref: "#/parameters/user_id" get: tags: - user summary: Fetches a user profile responses: 200: description: User profile schema: $ref: "#/definitions/User" put: tags: - user summary: Updates user details consumes: - application/json parameters: - name: User in: body required: true schema: $ref: "#/definitions/UserPutRequest" responses: 204: description: User Updated delete: tags: - user summary: Deletes user responses: 204: description: User deleted /users/{user_id}/password: parameters: - $ref: "#/parameters/user_id" post: tags: - user summary: Updates user password consumes: - application/json parameters: - name: Password in: body required: true schema: type: object properties: password: type: string format: password responses: 204: description: Password updated # Projects /projects: get: tags: - projects summary: Get projects responses: 200: description: List of projects schema: type: array items: $ref: "#/definitions/Project" post: tags: - projects summary: Create a new project consumes: - application/json parameters: - name: Project in: body required: true schema: $ref: '#/definitions/ProjectRequest' responses: 201: description: Created project /events: get: summary: Get Events related to Semaphore and projects you are part of responses: 200: description: Array of events in chronological order schema: type: array items: $ref: '#/definitions/Event' /events/last: get: summary: Get last 200 Events related to Semaphore and projects you are part of responses: 200: description: Array of events in chronological order schema: type: array items: $ref: '#/definitions/Event' /project/{project_id}/: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Fetch project responses: 200: description: Project schema: $ref: "#/definitions/Project" put: tags: - project summary: Update project parameters: - name: Project in: body required: true schema: type: object properties: name: type: string responses: 204: description: Project saved delete: tags: - project summary: Delete project responses: 204: description: Project deleted /project/{project_id}/role: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Fetch permissions of the current user for project responses: 200: description: Permissions schema: type: object properties: role: type: string example: owner permissions: type: number example: 0 /project/{project_id}/events: parameters: - $ref: '#/parameters/project_id' get: tags: - project summary: Get Events related to this project responses: 200: description: Array of events in chronological order schema: type: array items: $ref: '#/definitions/Event' # User management /project/{project_id}/users: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Get users linked to project parameters: - name: sort in: query required: true type: string enum: [name, username, email, role] description: sorting name x-example: email - name: order in: query required: true type: string enum: [asc, desc] description: ordering manner x-example: desc responses: 200: description: Users schema: type: array items: $ref: "#/definitions/ProjectUser" post: tags: - project summary: Link user to project parameters: - name: User in: body required: true schema: type: object properties: user_id: type: integer minimum: 2 role: type: string enum: [owner,manager,task_runner,guest] example: owner responses: 204: description: User added /project/{project_id}/users/{user_id}: parameters: - $ref: "#/parameters/project_id" - $ref: "#/parameters/user_id" delete: tags: - project summary: Removes user from project responses: 204: description: User removed put: parameters: - name: Project User in: body required: true schema: type: object properties: role: type: string enum: [owner,manager,task_runner,guest] example: owner summary: Update user role responses: 204: description: User updated # project access keys /project/{project_id}/keys: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Get access keys linked to project parameters: # TODO - the space in this parameter name results in a dredd warning - name: Key type in: query required: false type: string enum: [none,ssh,login_password] description: Filter by key type x-example: none - name: sort in: query required: true type: string enum: [name, type] description: sorting name x-example: type - name: order in: query required: true type: string enum: [asc, desc] description: ordering manner x-example: asc responses: 200: description: Access Keys schema: type: array items: $ref: "#/definitions/AccessKey" post: tags: - project summary: Add access key parameters: - name: Access Key in: body required: true schema: $ref: "#/definitions/AccessKeyRequest" responses: 204: description: Access Key created 400: description: Bad type /project/{project_id}/keys/{key_id}: parameters: - $ref: "#/parameters/project_id" - $ref: "#/parameters/key_id" put: tags: - project summary: Updates access key parameters: - name: Access Key in: body required: true schema: $ref: "#/definitions/AccessKeyRequest" responses: 204: description: Key updated 400: description: Bad type delete: tags: - project summary: Removes access key responses: 204: description: access key removed # project repositories /project/{project_id}/repositories: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Get repositories parameters: - name: sort in: query required: true type: string enum: [name, git_url, ssh_key] description: sorting name - name: order in: query required: true type: string format: asc/desc enum: [asc, desc] description: ordering manner responses: 200: description: repositories schema: type: array items: $ref: "#/definitions/Repository" post: tags: - project summary: Add repository parameters: - name: Repository in: body required: true schema: $ref: "#/definitions/RepositoryRequest" responses: 204: description: Repository created /project/{project_id}/repositories/{repository_id}: parameters: - $ref: "#/parameters/project_id" - $ref: "#/parameters/repository_id" put: tags: - project summary: Updates repository parameters: - name: Repository in: body required: true schema: $ref: "#/definitions/RepositoryRequest" responses: 204: description: Repository updated 400: description: Bad request delete: tags: - project summary: Removes repository responses: 204: description: repository removed # project inventory /project/{project_id}/inventory: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Get inventory parameters: - name: sort in: query required: true type: string description: sorting name enum: [name, type] - name: order in: query required: true type: string description: ordering manner enum: [asc, desc] responses: 200: description: inventory schema: type: array items: $ref: "#/definitions/Inventory" post: tags: - project summary: create inventory parameters: - name: Inventory in: body required: true schema: $ref: "#/definitions/InventoryRequest" responses: 201: description: inventory created schema: $ref: "#/definitions/Inventory" /project/{project_id}/inventory/{inventory_id}: parameters: - $ref: "#/parameters/project_id" - $ref: "#/parameters/inventory_id" put: tags: - project summary: Updates inventory parameters: - name: Inventory in: body required: true schema: $ref: "#/definitions/InventoryRequest" responses: 204: description: Inventory updated delete: tags: - project summary: Removes inventory responses: 204: description: inventory removed # project environment /project/{project_id}/environment: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Get environment parameters: - name: sort in: query required: true type: string format: name description: sorting name x-example: 'db-deploy' - name: order in: query required: true type: string format: asc/desc description: ordering manner x-example: desc responses: 200: description: environment schema: type: array items: $ref: "#/definitions/Environment" post: tags: - project summary: Add environment parameters: - name: environment in: body required: true schema: $ref: "#/definitions/EnvironmentRequest" responses: 204: description: Environment created /project/{project_id}/environment/{environment_id}: parameters: - $ref: "#/parameters/project_id" - $ref: "#/parameters/environment_id" put: tags: - project summary: Update environment parameters: - name: environment in: body required: true schema: $ref: "#/definitions/EnvironmentRequest" responses: 204: description: Environment Updated delete: tags: - project summary: Removes environment responses: 204: description: environment removed # project templates /project/{project_id}/templates: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Get template parameters: - name: sort in: query required: true type: string description: sorting name enum: [name, playbook, ssh_key, inventory, environment, repository] - name: order in: query required: true type: string description: ordering manner enum: [asc, desc] responses: 200: description: template schema: type: array items: $ref: "#/definitions/Template" properties: survey_vars: type: array items: $ref: "#/definitions/TemplateSurveyVar" last_task: $ref: "#/definitions/Task" post: tags: - project summary: create template parameters: - name: templateyes in: body required: true schema: $ref: "#/definitions/TemplateRequest" responses: 201: description: template created schema: $ref: "#/definitions/TemplateRequest" /project/{project_id}/templates/{template_id}: parameters: - $ref: "#/parameters/project_id" - $ref: "#/parameters/template_id" get: tags: - project summary: Get template responses: 200: description: template object schema: $ref: "#/definitions/Template" put: tags: - project summary: Updates template parameters: - name: template in: body required: true schema: $ref: "#/definitions/TemplateRequest" responses: 204: description: template updated delete: tags: - project summary: Removes template responses: 204: description: template removed # project schedules /project/{project_id}/schedules/{schedule_id}: parameters: - $ref: "#/parameters/project_id" - $ref: "#/parameters/schedule_id" get: tags: - schedule summary: Get schedule responses: 200: description: Schedule schema: $ref: "#/definitions/Schedule" delete: tags: - schedule summary: Deletes schedule responses: 204: description: schedule deleted put: tags: - schedule summary: Updates schedule parameters: - name: schedule in: body required: true schema: $ref: "#/definitions/ScheduleRequest" responses: 204: description: schedule updated /project/{project_id}/schedules: parameters: - $ref: "#/parameters/project_id" post: tags: - schedule summary: create schedule parameters: - name: schedule in: body required: true schema: $ref: "#/definitions/ScheduleRequest" responses: 201: description: schedule created schema: $ref: "#/definitions/Schedule" # project views /project/{project_id}/views: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Get view responses: 200: description: view schema: type: array items: $ref: "#/definitions/View" post: tags: - project summary: create view parameters: - name: view in: body required: true schema: $ref: "#/definitions/ViewRequest" responses: 201: description: view created schema: $ref: "#/definitions/View" /project/{project_id}/views/{view_id}: parameters: - $ref: "#/parameters/project_id" - $ref: "#/parameters/view_id" get: tags: - project summary: Get view responses: 200: description: view object schema: $ref: "#/definitions/View" put: tags: - project summary: Updates view parameters: - name: view in: body required: true schema: $ref: "#/definitions/ViewRequest" responses: 204: description: view updated delete: tags: - project summary: Removes view responses: 204: description: view removed # tasks /project/{project_id}/tasks: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Get Tasks related to current project responses: 200: description: Array of tasks in chronological order schema: type: array items: $ref: '#/definitions/Task' post: tags: - project summary: Starts a job parameters: - name: task in: body required: true schema: type: object properties: template_id: type: integer debug: type: boolean dry_run: type: boolean diff: type: boolean playbook: type: string environment: type: string limit: type: string responses: 201: description: Task queued schema: $ref: "#/definitions/Task" /project/{project_id}/tasks/last: parameters: - $ref: "#/parameters/project_id" get: tags: - project summary: Get last 200 Tasks related to current project responses: 200: description: Array of tasks in chronological order schema: type: array items: $ref: '#/definitions/Task' /project/{project_id}/tasks/{task_id}/stop: parameters: - $ref: "#/parameters/project_id" - $ref: '#/parameters/task_id' post: tags: - project summary: Stop a job responses: 204: description: Task queued /project/{project_id}/tasks/{task_id}: parameters: - $ref: "#/parameters/project_id" - $ref: "#/parameters/task_id" get: tags: - project summary: Get a single task responses: 200: description: Task schema: $ref: "#/definitions/Task" delete: tags: - project summary: Deletes task (including output) responses: 204: description: task deleted /project/{project_id}/tasks/{task_id}/output: parameters: - $ref: '#/parameters/project_id' - $ref: '#/parameters/task_id' get: tags: - project summary: Get task output responses: 200: description: output schema: type: array items: $ref: "#/definitions/TaskOutput" # /runners: # post: # tags: # - project # summary: Starts a job # parameters: # - name: task # in: body # required: true # schema: # type: object # properties: # registration_token: # type: string # example: test123 # responses: # 201: # description: Task queued # schema: # $ref: "#/definitions/Runner"