Termius Host API

openapi: 3.2.0
info:
  title: Termius API Bridge Host API
  description: '# Welcome

    You are viewing the REST API documentation for the Termius API Bridge.'
  termsOfService: https://termius.com/terms-of-use
  contact:
    email: support@termius.com
  license:
    name: Proprietary and confidential
  version: 0.0.1
tags:
- name: Host
  description: Create or Delete a host inside the vault or the group
paths:
  /v1/host/{external_id}/:
    post:
      tags:
      - Host
      summary: Create a new Host in the vault
      description: 'Pass the host ID in your infrastructure as `external_id` in the API

        path, the vault name in the `vault`, `address`, and optional `label`

        fields. Additionally, pass the ssh port in `port` field inside the

        `ssh` object or telnet port in `port` inside the `telnet` object.


        To see the full schema of the request, click on the **Schema** in

        **Request body** below.


        Example of the request that creates a new host with `external_id` as

        `vm-1234` in `Team` vault with address `example.com`, label `Database`,

        ssh port `22`, and ssh credentials in `username` and `password`

        properties, and SSH key in the `key` property:


        - path: `/v1/host/vm-1234/`

        - body:

        ```

        {

        "vault": "Team",

        "address": "example.com",

        "label": "Database",

        "ssh": {

        "port": 22,

        "credentials": {

        "username": "username",

        "password": "password",

        "key": {

        "label": "shared with the team",

        "private": "-----BEGIN OPENSSH PRIVATE KEY-----\nb3Blbn..."

        }

        }

        }

        }

        ```


        Optionally, pass the `group` field with the group `external_id` instead

        of the vault. Create such a group with the


        /group/{external_id}/ API.'
      operationId: createHost
      parameters:
      - $ref: '#/components/parameters/HostExternalID'
      requestBody:
        $ref: '#/components/requestBodies/Host'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateHostResponse'
        '400':
          description: Failed request. Check the request body.
    delete:
      tags:
      - Host
      summary: Delete the Host
      operationId: deleteHost
      description: 'Pass the host id in your infrastructure as `external_id` in the API

        path.


        Example of the request that deletes the host with `external_id` as

        `vm-1234`:


        - path: `/v1/host/vm-1234/`'
      parameters:
      - $ref: '#/components/parameters/HostExternalID'
      responses:
        '204':
          description: successful operation
        '400':
          description: Failed request. Check the request body.
components:
  parameters:
    HostExternalID:
      name: external_id
      in: path
      description: Host ID in your original system
      required: true
      example: vm-1234
      schema:
        type: string
  requestBodies:
    Host:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Host'
  schemas:
    Port:
      type: integer
      format: int64
      default: 22
      minimum: 1
      maximum: 65535
    CreateHostResponse:
      type: object
    Host:
      type: object
      allOf:
      - $ref: '#/components/schemas/GroupReference'
      - $ref: '#/components/schemas/VaultReference'
      required:
      - address
      example:
        vault: Team
        address: some.address.for.connection
      properties:
        address:
          type: string
          example: example.com
        label:
          type: string
          example: Database
        tags:
          type: array
          items:
            type: string
        ssh:
          type: object
          properties:
            port:
              $ref: '#/components/schemas/Port'
            credentials:
              allOf:
              - $ref: '#/components/schemas/Credentials'
              properties:
                key:
                  $ref: '#/components/schemas/SShKey'
        telnet:
          type: object
          properties:
            port:
              $ref: '#/components/schemas/Port'
            credentials:
              $ref: '#/components/schemas/Credentials'
    GroupReference:
      type: object
      required:
      - group
      properties:
        group:
          type: string
          example: client-1234
    SShKey:
      required:
      - label
      - private
      properties:
        label:
          type: string
        private:
          type: string
        public:
          type: string
    Credentials:
      properties:
        username:
          type: string
        password:
          type: string
    VaultReference:
      type: object
      required:
      - vault
      properties:
        vault:
          type: string
          example: Team
externalDocs:
  description: Termius Documentation
  url: https://support.termius.com/hc/en-us/