api-docs.yml

---
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
  - name: integration
    description: Integration 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

  ProjectBackup:
    type: object
    example: {"meta":{"name":"homelab","alert":true,"alert_chat":"Test","max_parallel_tasks":0},"templates":[{"inventory":"Build","repository":"Demo","environment":"Empty","name":"Build","playbook":"build.yml","arguments":"[]","allow_override_args_in_task":false,"description":"Build Job","vault_key":null,"type":"build","start_version":"1.0.0","build_template":null,"view":"Build","autorun":false,"survey_vars":"null","suppress_success_alerts":false,"cron":"* * * * *"}],"repositories":[{"name":"Demo","git_url":"https://github.com/semaphoreui/demo-project.git","git_branch":"main","ssh_key":"None"}],"keys":[{"name":"None","type":"none"},{"name":"Vault Password","type":"login_password"}],"views":[{"title":"Build","position":0}],"inventories":[{"name":"Build","inventory":"","ssh_key":"None","become_key":"None","type":"static"},{"name":"Dev","inventory":"","ssh_key":"None","become_key":"None","type":"file"},{"name":"Prod","inventory":"","ssh_key":"None","become_key":"None","type":"file"}],"environments":[{"name":"Empty","password":null,"json":"{}","env":null}]}
    properties:
      meta:
        type: object
        properties:
          name:
            type: string
          alert:
            type: boolean
          alert_chat:
            type:
              - string
              - 'null'
          max_parallel_tasks:
            type: integer
            minimum: 0
      templates:
        type: array
        items:
          type: object
          properties:
            view:
              type: string
            name:
              type: string
            playbook:
              type: string
            arguments:
              type:
                - string
                - 'null'
            description:
              type: string
            allow_override_args_in_task:
              type: boolean
            suppress_success_alerts:
              type: boolean
            cron:
              type:
                - string
                - 'null'
            build_template:
              type:
                - string
                - 'null'
            autorun:
              type: boolean
            survey_vars:
              type:
                - string
                - 'null'
            start_version:
              type:
                - string
                - 'null'
            type:
              type: string
      views:
        type: array
        items:
          type: object
          properties:
            name:
              type: string
            position:
              type: integer
              minimum: 0

  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
          - 'null'
        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
          - 'null'
        example: Test
      max_parallel_tasks:
        type: integer
        minimum: 0

  Task:
    type: object
    properties:
      id:
        type: integer
        example: 23
      template_id:
        type: integer
      status:
        type: string
      debug:
        type: boolean
      playbook:
        type: string
      secret:
        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
      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
      app:
        type: string
        example: ansible
      survey_vars:
        type: array
        items:
          $ref: "#/definitions/TemplateSurveyVar"
  Template:
    type: object
    properties:
      id:
        type: integer
        minimum: 1
      project_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
      name:
        type: string
      active:
        type: boolean

  Schedule:
    type: object
    properties:
      id:
        type: integer
      cron_format:
        type: string
      project_id:
        type: integer
      template_id:
        type: integer
      name:
        type: string
      active:
        type: boolean

  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
  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
  integration_id:
    name: integration_id
    description: integration ID
    in: path
    type: integer
    required: true
    x-example: 11
  extractvalue_id:
    name: extractvalue_id
    description: extractValue ID
    in: path
    type: integer
    required: true
    x-example: 12
  matcher_id:
    name: matcher_id
    description: matcher ID
    in: path
    type: integer
    required: true
    x-example: 13

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
  /projects/restore:
    post:
      tags:
        - projects
      summary: Restore Project
      consumes:
        - application/json
      parameters:
        - name: Backup
          in: body
          required: true
          schema:
            $ref: '#/definitions/ProjectBackup'
      responses:
        200:
          description: Created project
          schema:
            $ref: "#/definitions/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}/backup:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Backup A Project
      responses:
        200:
          description: Backup
          schema:
            $ref: '#/definitions/ProjectBackup'

  /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 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]
        - 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
              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"