api.raml

#%RAML 1.0
title: Semaphore
baseUri: https://api.semaphoreci.com/v2
mediaType: application/json

annotationTypes:
  stability:
    enum: [prototype, development, production]

types:
  UUID:
    type: string
    pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

  time:
    type: datetime
    format: rfc3339

  Error:
    type: object
    properties:
      message: string

  Org:
    type: object
    properties:
      id:
        type: UUID
        description: "Unique ID of the organization."
        example: "86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      name:
        type: string
        description: "Name of the organization."
        example: "Rendered Text"
      url:
        type: string
        description: "Show URL for the organization."
        example: "https://api.semaphoreci.com/v2/orgs/renderedtext"
      projects_url:
        type: string
        description: "Projects URL for the organization"
        example: "https://api.semaphoreci.com/v2/orgs/renderedtext/projects"
      secrets_url:
        type: string
        description: "Secrets URL for the organization"
        example: "https://api.semaphoreci.com/v2/orgs/renderedtext/secrets"
      users_url:
        type: string
        description: "Users URL for the organization"
        example: "https://api.semaphoreci.com/v2/orgs/renderedtext/users"
      teams_url:
        type: string
        description: "Teams URL for the organization"
        example: "https://api.semaphoreci.com/v2/orgs/renderedtext/teams"
      username:
        type: string
        description: "Unique username of the organization."
        example: "renderedtext"
      created_at: time
      updated_at: time

  TeamPatch:
    type: object
    properties:
      name?:
        type: string
        description: "Name of the team. The name must be unique in the organization."
        example: "developers"
      permission?:
        description: "The permission level for team members in the organization."
        enum: [read, edit, admin]
        example: "edit"
      description?:
        type: string
        description: "Description for the team."
        example: "Developers team"

  TeamPost:
    type: object
    properties:
      name:
        type: string
        description: "Name of the team. The name must be unique in the organization."
        example: "developers"
      permission:
        enum: [read, edit, admin]
        description: "The permission level for team members in the organization."
        example: "edit"
      description?:
        type: string
        description: "Description for the team."
        example: "Developers team"

  Team:
    type: TeamPost
    properties:
      id:
        type: UUID
        description: "Unique ID of the team."
        example: "86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      url:
        type: string
        description: "Show URL for the team."
        example: "https://api.semaphoreci.com/v2/teams/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      users_url:
        type: string
        description: "Users URL for the team"
        example: "https://api.semaphoreci.com/v2/teams/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5/users"
      projects_url:
        type: string
        description: "Projects URL for the team"
        example: "https://api.semaphoreci.com/v2/teams/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5/projects"
      secrets_url:
        type: string
        description: "Secrets URL for the team"
        example: "https://api.semaphoreci.com/v2/teams/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5/secrets"
      updated_at: time
      created_at: time

  ProjectPost:
    type: object
    properties:
      name:
        type: string
        description: "Name of the project on Semaphore"
        example: "cli"
      repo_name:
        type: string
        description: "Name of the repository on GitHub or BitBucket"
        example: "cli"
      repo_owner:
        type: string
        description: "Name of the repository owner on GitHub or BitBucket"
        example: "renderedtext"
      repo_provider:
        enum: [github, bitbucket]
        description: "Repository Host"
        example: "github"

  Project:
    type: object
    properties:
      id:
        type: UUID
        description: "Unique ID of the project."
        example: "86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      name:
        type: string
        description: "Name of the project."
        example: "elixir-lang"
      html_url:
        type: string
        description: "Project's HTML URL"
        example: "https://semaphoreci.com/renderedtext/elixir-lang"
      users_url:
        type: string
        description: "Users URL for the project"
        example: "https://api.semaphoreci.com/v2/projects/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5/users"
      secrets_url:
        type: string
        description: "Secrets URL for the project"
        example: "https://api.semaphoreci.com/v2/projects/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5/secrets"
      updated_at: time
      created_at: time

  SecretPatch:
    type: object
    properties:
      name?:
        type: string
        description: "Name of the secret."
        example: "AWS Tokens"
      description?:
        type: string
        description: "Description for the secrets."
        example: "AWS tokens for deployment"

  SecretPost:
    type: object
    properties:
      name:
        type: string
        description: "Name of the secret."
        example: "AWS Tokens"
      description?:
        type: string
        description: "Description for the secret."
        example: "AWS tokens for deployment"

  Secret:
    type: SecretPost
    properties:
      id:
        type: UUID
        description: "Unique ID of the secret."
        example: "86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      url:
        type: string
        description: "Show URL for the secret."
        example: "https://api.semaphoreci.com/v2/secrets/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      projects_url:
        type: string
        description: "Projects URL for the secret"
        example: "https://api.semaphoreci.com/v2/secrets/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5/projects"
      teams_url:
        type: string
        description: "Teams URL for the secret"
        example: "https://api.semaphoreci.com/v2/secrets/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5/teams"
      env_vars_url:
        type: string
        description: "Environment Variables URL for the secret"
        example: "https://api.semaphoreci.com/v2/secrets/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5/env_vars"
      config_files_url:
        type: string
        description: "Config Files URL for the the secret"
        example: "https://api.semaphoreci.com/v2/secrets/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5/config_files"
      created_at: time
      updated_at: time

  EnvVarPatch:
    type: object
    properties:
      name?:
        type: string
        description: "Name of the environment variable."
        example: "API_TOKEN"
      content?:
        type: string
        description: "Content of the environment variable."
        example: "8CgLAxXn"

  EnvVarPost:
    type: object
    properties:
      name:
        type: string
        description: "Name of the environment variable."
        example: "API_TOKEN"
      content:
        type: string
        description: "Content of the environment variable."
        example: "8CgLAxXn"
      encrypted:
        type: boolean
        example: false

  EnvVar:
    type: object
    properties:
      id:
        type: UUID
        description: "Unique ID of the environment variable."
        example: "86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      name:
        type: string
        description: "Name of the environment variable."
        example: "API_TOKEN"
      url:
        type: string
        description: "Show URL for the environment variable."
        example: "https://api.semaphoreci.com/v2/env_vars/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      content:
        type: string
        description: "Content of the environment variable. Will be `null` if encrypted."
        example: "8CgLAxXn"
      shared:
        type: boolean
        description: "True if the environment variable belongs to a secret."
        example: true
      encrypted:
        type: boolean
        description: "True if the environment variable is encrypted."
        example: false
      created_at: time
      updated_at: time

  ConfigFilePatch:
    type: object
    properties:
      path?:
        type: string
        description: "Path of the configuration file."
        example: ".credentials"
      content?:
        type: string
        description: "Content of the configuration file."
        example: "password: ec2c9f6f64b5"

  ConfigFilePost:
    type: object
    properties:
      path:
        type: string
        description: "Path of the configuration file."
        example: ".credentials"
      content:
        type: string
        description: "Content of the configuration file. Will be `null` if the file is encrypted."
        example: "password: ec2c9f6f64b5"
      encrypted:
        type: boolean
        description: "True if the file is encrypted."
        example: false

  ConfigFile:
    type: object
    properties:
      id:
        type: UUID
        description: "Unique ID of the configuration file."
        example: "86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      path:
        type: string
        description: "Path of the configuration file."
        example: ".credentials"
      url:
        type: string
        description: "Show URL for the configuration file."
        example: "https://api.semaphoreci.com/v2/config_files/86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      content:
        type: string
        description: "Content of the configuration file. Will be `null` if the file is encrypted."
        example: "password: ec2c9f6f64b5"
      shared:
        type: boolean
        description: "True if the configuration file belongs to a secret."
        example: true
      encrypted:
        type: boolean
        description: "True if the file is encrypted."
        example: false
      created_at: time
      updated_at: time

  User:
    type: object
    properties:
      uid:
        type: UUID
        description: "Unique ID of the user."
        example: "86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      username:
        type: string
        description: "Unique username of the user."
        example: "johndoe"
      name:
        type: string
        description: "Name of the user."
        example: "John Doe"
      created_at: time
      updated_at: time

  Pipeline:
    type: object
    properties:
      id:
        type: UUID
        description: "Unique ID of the pipeline."
        example: "86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"

  PipelineRepo:
    type: object
    properties:
      owner:
        type: string
        required: true
        description: "Repo owner."
        example: "renderedtext"
      repo_name:
        type: string
        required: true
        description: "Repo name."
        example: "wormhole"
      branch_name:
        type: string
        required: true
        description: "Git branch."
        example: "master"
      commit_sha:
        type: string
        required: true
        description: "Git commit SHA."
        example: "78ce7905cb571ea13d3785c1197f851d757df72c"

  PipelinePost:
    type: object
    properties:
      project_uuid:
        type: UUID
        description: "Project the pipeline is building."
        example: "86e78b7e-2f9c-45a7-9939-ec2c9f6f64b5"
      repo:
        type: PipelineRepo
        required: true
        description: "The repository."
      service:
        enum: [git_hub]
        required: true
        description: "The repository type."
      pipeline_request_token:
        type: string
        required: true
        maxLength: 64
        description: "Idempotency key."
        example: "86e78b7e2f9c45a79939ec2c9f6f64b5"

  PipelineDescription:
    type: object
    properties:
      description:
        type: string
        description: "Pipeline description."
        example: ""

  PipelinePatch:
    type: object
    properties:
      terminate_request:
        enum: ["true"]
        required: true
        example: "true"

traits:
  withRequestItem:
    body:
      application/json:
        type: <<item>>
  withResponseItem:
    responses:
      200:
        body:
          application/json:
            type: <<item>>
  withResponseItems:
    responses:
      200:
        body:
          application/json:
            type: <<item>>[]
  withCreateResponse:
    responses:
      201:
        body:
          application/json:
            type: <<item>>
  withNoBodyResponse:
    responses:
      204:
  withClientError:
    responses:
      400:
        body:
          application/json:
            type: Error
  withNotFoundError:
    responses:
      404:
        body:
          application/json:
            type: Error
  withPreconditionFailedError:
    responses:
      412:
        body:
          application/json:
            type: Error

/users:
  (stability): "development"
  displayName: "Users"

/orgs:
  (stability): "development"
  displayName: "Organizations"

  get:
    displayName: List your organizations
    is: [withResponseItems: {item : Org}]

  /{username}:
    get:
      displayName: Get an organization
      is: [withResponseItem: {item : Org}, withNotFoundError]

  /{org_username}:
    /teams:
      get:
        displayName: List teams in an organization
        is: [withResponseItems: {item : Team}]
      post:
        displayName: Create a team in an organization
        description: Only organization owners can create new teams.
        is: [withRequestItem: {item : TeamPost},
             withResponseItem: {item : Team},
             withNotFoundError,
             withPreconditionFailedError]
    /projects:
      get:
        displayName: List projects in an organization
        is: [withResponseItems: {item : Project}]
      post:
        displayName: Create a project in an organization
        description: Only organization admin can create new projects.
        is: [withRequestItem: {item : ProjectPost},
             withResponseItem: {item : Project},
             withNotFoundError,
             withPreconditionFailedError]
    /secrets:
      get:
        displayName: List secrets in an organization
        is: [withResponseItems: {item : Secret}]
      post:
        displayName: Create secret in an organization
        is: [withRequestItem: {item : SecretPost},
            withResponseItem: {item : Secret},
            withNotFoundError,
            withPreconditionFailedError]
    /users:
      get:
        displayName: List all users for a organization
        is: [withResponseItems: {item : User}, withNotFoundError]

/teams:
  (stability): "development"
  displayName: "Teams"

  /{id}:
    get:
      displayName: Get a team
      is: [withResponseItem: {item : Team}, withNotFoundError]
    delete:
      displayName: Delete a team
      description: Only organization owners can delete teams.
      is: [withNoBodyResponse, withNotFoundError]
    patch:
      displayName: Update a team
      description: Only organization owners can update teams.
      is: [withRequestItem: {item : TeamPatch}, withResponseItem: {item : Team}, withNotFoundError]

  /{team_id}:
    /secrets:
      get:
        displayName: List secrets in a team
        is: [withResponseItems: {item : Secret}, withNotFoundError]

      /{secret_id}:
        post:
          displayName: Add a secret to a team
          description: The user needs to be a member of the team, and to have admin permissions in the organization.
          is: [withNoBodyResponse, withNotFoundError]
        delete:
          displayName: Remove secret from a team
          description: The user needs to be a member of the team, and to have admin permissions in the organization.
          is: [withNoBodyResponse, withNotFoundError]

    /users:
      get:
        displayName: List members of a team
        is: [withResponseItems: {item : User}, withNotFoundError]
      /{user_username}:
        post:
          displayName: Add user to a team
          is: [withNoBodyResponse, withNotFoundError]
        delete:
          displayName: Remove user from a team
          is: [withNoBodyResponse, withNotFoundError]

    /projects:
      get:
        displayName: List project added to a team
        is: [withResponseItems: {item : Project}, withNotFoundError]

      /{project_id}:
        post:
          displayName: Add project to a team
          is: [withNoBodyResponse, withNotFoundError]
        delete:
          displayName: Remove project from a team
          is: [withNoBodyResponse, withNotFoundError]

/projects:
  (stability): "development"
  displayName: "Projects"

  /{project_id}:
    /secrets:
      get:
        displayName: List secrets attached to a project
        is: [withResponseItems: {item : Secret}, withNotFoundError]

      /{secret_id}:
        post:
          displayName: Attach a secret to a project
          is: [withResponseItem: {item : Secret}, withNotFoundError]
        delete:
          displayName: Dettach a secret from a project
          is: [withNoBodyResponse, withNotFoundError]

    /env_vars:
      get:
        displayName: List environment variables connected to a project
        is: [withResponseItems: {item : EnvVar}, withNotFoundError]

    /config_files:
      get:
        displayName: List config files connected to a project
        is: [withResponseItems: {item : ConfigFile}, withNotFoundError]

    /teams:
      get:
        displayName: List all teams connected to project
        is: [withResponseItems: {item : Team}, withNotFoundError]

    /users:
      get:
        displayName: List all users for a project
        is: [withResponseItems: {item : User}, withNotFoundError]

/secrets:
  (stability): "development"
  displayName: "Secrets"

  /{id}:
    get:
      displayName: Get a secret
      is: [withResponseItem: {item : Secret}, withNotFoundError]
    delete:
      displayName: Delete a secret
      description: Deleting secret will remove it from all projects it is used on. Deleting a secret requires at least admin permissions in the organization.
      is: [withNoBodyResponse, withNotFoundError]
    patch:
      displayName: Update a secret
      description: To update the secret you need to be an admin or owner in your organization.
      is: [withRequestItem: {item : SecretPatch},
          withResponseItem: {item : Secret}, withNotFoundError]

  /{secret_id}:
    /projects:
      get:
        displayName: List projects for a secret
        is: [withResponseItems: {item : Project}, withNotFoundError]

    /teams:
      get:
        displayName: List teams for a secret
        is: [withResponseItems: {item : Team}, withNotFoundError]

    /env_vars:
      get:
        displayName: List environment variables belonging to a secret
        is: [withResponseItems: {item : EnvVar}, withNotFoundError]
      post:
        displayName: Create environment variable within a secret
        description: Environment variables can be only created by users who can edit the secret.
        is: [withRequestItem: {item : EnvVarPost},
            withResponseItem: {item : EnvVar}, withNotFoundError]
    /config_files:
      get:
        displayName: List config files belonging to a secret
        is: [withResponseItems: {item : ConfigFile}, withNotFoundError]
      post:
        displayName: Create a config file within a secret
        description: Configuration files can be only created by users who can edit the secret.
        is: [withRequestItem: {item : ConfigFilePost},
            withResponseItem: {item : ConfigFile}, withNotFoundError]

/env_vars:
  (stability): "development"
  displayName: "Environment Variables"

  /{id}:
    get:
      displayName: Get an environment variable
      description: Displays the environment variable. Encrypted configuration files  will have `null` as content.
      is: [withResponseItem: {item : EnvVar}, withNotFoundError]
    delete:
      displayName: Delete an environment variable
      description: Environment variables can be only deleted by users who has edit access on the project or the secret.
      is: [withNoBodyResponse, withNotFoundError]
    patch:
      displayName: Update an environment variable
      description: |
        Environment variables can be only updated by users who has edit access on the project or the secret. Encrypted environment variables can't be edited.
      is: [withRequestItem: {item : EnvVarPatch},
          withResponseItem: {item : EnvVar}, withNotFoundError]

/config_files:
  (stability): "development"
  displayName: "Configuration Files"

  /{id}:
    get:
      displayName: Get a config file
      description: Displays the configuration file. Encrypted configuration files  will have `null` as content.
      is: [withResponseItem: {item : ConfigFile}, withNotFoundError]
    delete:
      displayName: Delete a config file
      description: Configuration files can be only deleted by users who has edit access on the project or the secret.
      is: [withNoBodyResponse, withNotFoundError]
    patch:
      displayName: Update a config file
      description: |
        Configuration files can be only updated by users who has edit access on the project or the secret. Encrypted environment variables can't be edited.
      is: [withRequestItem: {item : ConfigFilePatch},
          withResponseItem: {item : ConfigFile}, withNotFoundError]

/pipelines:
  (stability): "prototype"
  displayName: Pipelines

  get:
    displayName: List pipelines
    is: [withResponseItems: {item : Pipeline}, withNotFoundError]
  post:
    displayName: Schedule pipeline execution
    is: [withRequestItem: {item : PipelinePost},
        withCreateResponse: {item : Pipeline}, withNotFoundError]

  /{pipeline_id}:
    get:
      displayName: Describe pipeline
      is: [withResponseItem: {item : PipelineDescription}, withNotFoundError]

    patch:
      displayName: Terminate pipeline
      is: [withRequestItem: {item : PipelinePatch},
          withNoBodyResponse, withNotFoundError]