openapi: 3.0.1
info:
  title: XPipe API Documentation
  description: |
    The XPipe API provides programmatic access to XPipe’s features.
    You can get started by either using this page as an API reference or alternatively import the OpenAPI definition file into your API client of choice:
    
    <a download href="/openapi.yaml" style="font-size: 20px">OpenAPI .yaml specification</a>
  
    The XPipe application will start up an HTTP server that can be used to send requests.
    Note that this server is HTTP-only for now as it runs only on localhost. HTTPS requests are not accepted.
    
    This allows you to programmatically manage remote systems.
    To start off, you can query connections based on various filters.
    With the matched connections, you can start remote shell sessions for each one and run arbitrary commands in them.
    You get the command exit code and output as a response, allowing you to adapt your control flow based on command outputs.
    Any kind of passwords and other secrets are automatically provided by XPipe when establishing a shell connection.
    If a required password is not stored and is set to be dynamically prompted, the running XPipe application will ask you to enter any required passwords.
    
    See the authentication handshake below on how to authenticate prior to sending requests.
    For development you can also skip the authentication step by disabling it in the settings menu.
  termsOfService: https://docs.xpipe.io/terms-of-service
  contact:
    name: XPipe - Contact us
    url: mailto:hello@xpipe.io
  version: "10.0"
externalDocs:
  description: XPipe - Plans and pricing
  url: https://xpipe.io/pricing
servers:
  - url: http://localhost:21723
    description: XPipe Daemon API
paths:
  /handshake:
    post:
      summary: Establish a new API session
      description: |
        Prior to sending requests to the API, you first have to establish a new API session via the handshake endpoint.
        In the response you will receive a session token that you can use to authenticate during this session.
        
        This is done so that the daemon knows what kind of clients are connected and can manage individual capabilities for clients.
        If your client is running on the same system as the daemon, you can choose the local authentication method to avoid having to deal with API keys.
        If your client does not have file system access, e.g. if it is running remotely, then you have to use an API key.
        
        Note that for development you can also turn off the required authentication in the XPipe settings menu, allowing you to send unauthenticated requests.
      operationId: handshake
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HandshakeRequest'
            examples:
              standard:
                summary: Standard handshake
                value: { "auth": { "type": "ApiKey", "key": "<API key>" }, "client": { "type": "Api", "name": "My client name" } }
              local:
                summary: Local application handshake
                value: { "auth": { "type": "Local", "authFileContent": "<Contents of the local file $TEMP/xpipe_auth>" }, "client": { "type": "Api", "name": "My client name" } }
      responses:
        '200':
          description: The handshake was successful. The returned token can be used for authentication in this session. The token is valid as long as XPipe is running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandshakeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /connection/query:
    post:
      summary: Query connections
      description: |
        Queries all connections using various filters.
        
        The filters support globs and can match the category names and connection names.
        All matching is case insensitive.
      operationId: connectionQuery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionQueryRequest'
            examples:
              all:
                summary: All
                value: { "categoryFilter": "*", "connectionFilter": "*", "typeFilter": "*" }
              simple:
                summary: Simple filter
                value: { "categoryFilter": "default", "connectionFilter": "local machine", "typeFilter": "*" }
              globs:
                summary: Globs
                value: { "categoryFilter": "*", "connectionFilter": "*/podman/*", "typeFilter": "*" }
      responses:
        '200':
          description: The query was successful. The body contains all matched connections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionQueryResponse'
              examples:
                standard:
                  summary: Matched connections
                  value: { "found": [ { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b", "category": ["default"] ,
                                        "name": ["local machine"], "type": "local" },
                    { "connection": "e1462ddc-9beb-484c-bd91-bb666027e300", "category": ["default", "category 1"],
                      "name": ["ssh system", "shell environments", "bash"], "type": "shellEnvironment" } ] }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /connection/info:
    post:
      summary: Connection information
      description: |
        Queries detailed information about a connection.
      operationId: connectionInfo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionInfoRequest'
            examples:
              simple:
                summary: Standard
                value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b" }
      responses:
        '200':
          description: The query was successful. The body contains the detailed connection information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionInfoResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /shell/start:
    post:
      summary: Start shell connection
      description: |
        Starts a new shell session for a connection. If an existing shell session is already running for that connection, this operation will do nothing.
        
        Note that there are a variety of possible errors that can occur here when establishing the shell connection.
        These errors will be returned with the HTTP return code 500.
      operationId: shellStart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShellStartRequest'
            examples:
              local:
                summary: Start local shell
                value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b" }
      responses:
        '200':
          description: The operation was successful. The shell session was started.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /shell/stop:
    post:
      summary: Stop shell connection
      description: |
        Stops an existing shell session for a connection.
        
        This operation will return once the shell has exited.
        If the shell is busy or stuck, you might have to work with timeouts to account for these cases.
      operationId: shellStop
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShellStopRequest'
            examples:
              local:
                summary: Stop local shell
                value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b" }
      responses:
        '200':
          description: The operation was successful. The shell session was stopped.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /shell/exec:
    post:
      summary: Execute command in a shell session
      description: |
        Runs a command in an active shell session and waits for it to finish. The exit code and output will be returned in the response.
        
        Note that a variety of different errors can occur when executing the command.
        If the command finishes, even with an error code, a normal HTTP 200 response will be returned.
        However, if any other error occurs like the shell not responding or exiting unexpectedly, an HTTP 500 response will be returned.
      operationId: shellExec
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShellExecRequest'
            examples:
              user:
                summary: echo $USER
                value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b", "command": "echo $USER" }
              invalid:
                summary: invalid
                value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b", "command": "invalid" }
      responses:
        '200':
          description: The operation was successful. The shell command finished.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShellExecResponse'
              examples:
                user:
                  summary: echo $USER
                  value: { "exitCode": 0, "stdout": "root", "stderr": "" }
                fail:
                  summary: invalid
                  value: { "exitCode": 127, "stdout": "", "stderr": "invalid: command not found" }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /fs/blob:
    post:
      summary: Store a raw blob to be used later
      description: |
        Stores arbitrary binary data in a blob such that it can be used later on to for example write to a remote file.
        
        This will return a uuid which can be used as a reference to the blob.
        You can also store normal text data in blobs if you intend to create text or shell script files with it.
      operationId: fsData
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: The operation was successful. The data was stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FsBlobResponse'
              examples:
                success:
                  summary: Success
                  value: { "blob": "854afc45-eadc-49a0-a45d-9fb76a484304" }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /fs/read:
    post:
      summary: Read the content of a remote file
      description: |
        Reads the entire content of a remote file through an active shell session.
      operationId: fsRead
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FsReadRequest'
            examples:
              simple:
                summary: Read file
                value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b", "path": "/home/user/myfile.txt" }
      responses:
        '200':
          description: The operation was successful. The file was read.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /fs/write:
    post:
      summary: Write a blob to a remote file
      description: |
        Writes blob data to a file through an active shell session.
      operationId: fsWrite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FsWriteRequest'
            examples:
              simple:
                summary: Write simple file
                value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b", "blob": "854afc45-eadc-49a0-a45d-9fb76a484304", "path": "/home/user/myfile.txt" }
      responses:
        '200':
          description: The operation was successful. The file was written.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /fs/script:
    post:
      summary: Create a shell script file from a blob
      description: |
        Creates a shell script in the temporary directory of the file system that is access through the shell connection.
        
        This can be used to run more complex commands on remote systems.
      operationId: fsScript
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FsScriptRequest'
            examples:
              standard:
                summary: Standard write
                value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b", "blob": "854afc45-eadc-49a0-a45d-9fb76a484304" }
      responses:
        '200':
          description: The operation was successful. The script file was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FsScriptResponse'
              examples:
                success:
                  summary: Success
                  value: { "path": "/tmp/exec-123.sh" }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ShellStartRequest:
      type: object
      properties:
        connection:
          type: string
          description: The connection uuid
      required:
        - connection
    ShellStopRequest:
      type: object
      properties:
        connection:
          type: string
          description: The connection uuid
      required:
        - connection
    ShellExecRequest:
      type: object
      properties:
        connection:
          type: string
          description: The connection uuid
        command:
          type: string
          description: The command to execute
      required:
        - connection
        - command
    ShellExecResponse:
      type: object
      properties:
        exitCode:
          type: integer
          description: The exit code of the command
        stdout:
          type: string
          description: The stdout output of the command
        stderr:
          type: string
          description: The stderr output of the command
      required:
        - exitCode
        - stdout
        - stderr
    FsBlobResponse:
      type: object
      properties:
        blob:
          type: string
          description: The data uuid
      required:
        - blob
    FsWriteRequest:
      type: object
      properties:
        connection:
          type: string
          description: The connection uuid
        blob:
          type: string
          description: The blob uuid
        path:
          type: string
          description: The target filepath
      required:
        - connection
        - blob
        - path
    FsReadRequest:
      type: object
      properties:
        connection:
          type: string
          description: The connection uuid
        path:
          type: string
          description: The target file path
      required:
        - connection
        - path
    FsScriptRequest:
      type: object
      properties:
        connection:
          type: string
          description: The connection uuid
        blob:
          type: string
          description: The blob uuid
      required:
        - connection
        - blob
    FsScriptResponse:
      type: object
      properties:
        path:
          type: string
          description: The generated script file path
      required:
        - path
    ConnectionQueryRequest:
      type: object
      properties:
        categoryFilter:
          type: string
          description: The filter string to match categories. Categories are delimited by / if they are hierarchical. The filter supports globs.
        connectionFilter:
          type: string
          description: The filter string to match connection names. Connection names are delimited by / if they are hierarchical. The filter supports globs.
        typeFilter:
          type: string
          description: The filter string to connection types. Every unique type of connection like SSH or docker has its own type identifier that you can match. The filter supports globs.
      required:
        - categoryFilter
        - connectionFilter
        - typeFilter
    ConnectionQueryResponse:
      type: object
      properties:
        found:
          type: array
          description: The found connections
          items:
            type: object
            properties:
              connection:
                type: string
                description: The unique id of the connection
              category:
                type: array
                description: The full category path as an array
                items:
                  type: string
                  description: Individual category name
              name:
                type: array
                description: The full connection name path as an array
                items:
                  type: string
                  description: Individual connection name
              type:
                type: string
                description: The type identifier of the connection
            required:
              - connection
              - category
              - name
              - type
      required:
        - found
    ConnectionInfoRequest:
      type: object
      properties:
        connection:
          type: string
          description: The unique id of the connection
      required:
        - connection
    ConnectionInfoResponse:
      type: object
      properties:
        connection:
          type: string
          description: The unique id of the connection
        category:
          type: array
          description: The full category path as an array
          items:
            type: string
            description: Individual category name
        name:
          type: array
          description: The full connection name path as an array
          items:
            type: string
            description: Individual connection name
        type:
          type: string
          description: The type identifier of the connection
        rawData:
          type: object
          description: The raw internal configuration data for the connection. The schema for these is internal and should not be relied upon.
        usageCategory:
          type: string
          description: The category of how this connection can be used.
          enum:
            - shell
            - tunnel
            - script
            - database
            - command
            - desktop
            - group
        lastModified:
          type: string
          description: The timestamp of when the connection configuration was last modified in ISO 8601.
        lastUsed:
          type: string
          description: The timestamp of when the connection was last launched in ISO 8601.
      required:
        - connection
        - category
        - name
        - type
        - rawData
        - usageCategory
        - lastUsed
        - lastModified
    HandshakeRequest:
      type: object
      properties:
        auth:
          $ref: '#/components/schemas/AuthMethod'
        client:
          $ref: '#/components/schemas/ClientInformation'
      required:
        - auth
        - client
    HandshakeResponse:
      type: object
      properties:
        sessionToken:
          type: string
          description: The generated bearer token that can be used for authentication in this session
      required:
        - sessionToken
    AuthMethod:
      discriminator:
        propertyName: type
        mapping:
          apiKey: '#/components/schemas/ApiKey'
          local: '#/components/schemas/Local'
      oneOf:
        - $ref: '#/components/schemas/ApiKey'
        - $ref: '#/components/schemas/Local'
    ApiKey:
      description: API key authentication
      type: object
      properties:
        type:
          type: string
        key:
          type: string
          description: The API key
      required:
        - key
        - type
    Local:
      description: Authentication method for local applications. Uses file system access as proof of authentication.
      type: object
      properties:
        type:
          type: string
        authFileContent:
          type: string
          description: The contents of the local file $TEMP/xpipe_auth. This file is automatically generated when XPipe starts.
      required:
        - authFileContent
        - type
    ClientInformation:
      type: object
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
      required:
        - type
    ApiClientInformation:
      description: Provides information about the client that connected to the XPipe API.
      allOf:
        - $ref: '#/components/schemas/ClientInformation'
        - type: object
          properties:
            name:
              type: string
              description: The name of the client.
          required:
            - name
    ClientErrorResponse:
      description: Error returned in case of a client exception
      type: object
      properties:
        message:
          type: string
          description: The error message
      required:
        - message
    ServerErrorResponse:
      description: Error returned in case of a server exception with HTTP code 500
      type: object
      properties:
        error:
          type: object
          description: The exception information
          properties:
            cause:
              type: object
              description: The exception cause
            stackTrace:
              type: array
              description: The java stack trace information
            suppressed:
              type: array
              description: Any suppressed exceptions
            localizedMessage:
              type: string
              description: Not used
            message:
              type: string
              description: The error message
          required:
            - message
      required:
        - error
  responses:
    Success:
      description: The action was successfully performed.
    BadRequest:
      description: Bad request. Please check error message and your parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientErrorResponse'
    Unauthorized:
      description: Authorization failed. Please supply a `Bearer` token via
        the `Authorization` header.
    Forbidden:
      description: Authorization failed. Please supply a valid `Bearer` token via
        the `Authorization` header.
    NotFound:
      description: The requested resource could not be found.
    InternalServerError:
      description: Internal error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: The bearer token used is the session token that you receive from the handshake exchange.
security:
  - bearerAuth: []