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: OpenAPI .yaml specification 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. You can either call the API directly or use one of the following community-made libraries: - [https://github.com/coandco/python_xpipe_client](https://github.com/coandco/python_xpipe_client) To start off with the API, 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:21721 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": "" }, "client": { "type": "Api", "name": "My client name" } } local: summary: Local application handshake value: { "auth": { "type": "Local", "authFileContent": "" }, "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": [ "f0ec68aa-63f5-405c-b178-9a4454556d6b" ] } '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '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: { "connections": [ "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' examples: standard: summary: Connection information value: { "infos": [ { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b", "category": [ "default" ] , "name": [ "local machine" ], "type": "local", "rawData": { }, "usageCategory": "shell", "lastUsed": "2024-05-31T11:53:02.408504600Z", "lastModified": "2024-06-23T21:15:25.608097Z", "state": { } } ] } '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' /connection/add: post: summary: Add new connection description: | Creates the new connection in the xpipe vault from raw json data. If an equivalent connection already exists, no new one will be added. operationId: connectionAdd requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectionAddRequest' examples: simple: summary: Add new pwsh shell environment value: { "name": "my connection", "category": "97458c07-75c0-4f9d-a06e-92d8cdf67c40", "data": { "type": "shellEnvironment", "commands": null, "host": { "storeId": "f0ec68aa-63f5-405c-b178-9a4454556d6b" }, "shell": "pwsh", "elevated": false, } } responses: '200': description: The request was successful. The connection was added. content: application/json: schema: $ref: '#/components/schemas/ConnectionAddResponse' examples: standard: summary: Connection information value: { "connection": "36ad9716-a209-4f7f-9814-078d3349280c" } '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' /connection/browse: post: summary: Open connection in file browser description: | Creates a new tab in the file browser and opens the specified connections with an optional starting directory. operationId: connectionBrowse requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectionBrowseRequest' examples: simple: summary: Open local file browser value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b" } responses: '200': description: The request was successful. The connection was opened. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' /connection/terminal: post: summary: Open terminal for shell connection description: | Launches a new terminal session for a connection with an optional specified working directory. operationId: connectionTerminal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectionTerminalRequest' examples: simple: summary: Open terminal for local shell value: { "connection": "f0ec68aa-63f5-405c-b178-9a4454556d6b" } responses: '200': description: The request was successful. The connection was opened. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' /connection/toggle: post: summary: Toggle state of a connection description: | Updates the state of a connection to either start or stop a session. This can be used for all kinds of services and tunnels. operationId: connectionToggle requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectionToggleRequest' examples: simple: summary: Activate connection value: { "connection": "36ad9716-a209-4f7f-9814-078d3349280c", "state": true } responses: '200': description: The request was successful. The connection state was updated. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' /connection/refresh: post: summary: Refresh state of a connection description: | Performs a refresh on the specified connection. This will update the connection state information and also any children if the connection type has any. operationId: connectionRefresh requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectionRefreshRequest' examples: simple: summary: Refresh connection value: { "connection": "36ad9716-a209-4f7f-9814-078d3349280c" } responses: '200': description: The request was successful. The connection state was updated. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '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. content: application/json: schema: $ref: '#/components/schemas/ShellStartResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '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' '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' '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' '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' '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' '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' '500': $ref: '#/components/responses/InternalServerError' /daemon/version: post: summary: Query daemon version description: Retrieves version information from the daemon operationId: daemonVersion responses: '200': description: The operation was successful content: application/json: schema: $ref: '#/components/schemas/DaemonVersionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: schemas: ShellStartRequest: type: object properties: connection: type: string description: The connection uuid required: - connection ShellStartResponse: type: object properties: shellDialect: type: integer description: The shell dialect osType: type: string description: The general type of operating system osName: type: string description: The display name of the operating system temp: type: string description: The location of the temporary directory required: - shellDialect - osType - osName - temp 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: string description: The connection uuid required: - found ConnectionInfoRequest: type: object properties: connections: type: array description: The connections items: type: string description: The unique id of the connection required: - connections ConnectionInfoResponse: type: array items: type: object description: The array of information for each connection 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 state: type: object description: The internal persistent state information about the connection required: - connection - category - name - type - rawData - usageCategory - lastUsed - lastModified - state ConnectionRefreshRequest: type: object properties: connection: type: string description: The connection uuid required: - connection ConnectionAddRequest: type: object properties: name: type: string description: The connection name data: type: object description: The raw connection store data. Schemas for connection types are not documented but you can find the connection data of your existing connections in the xpipe vault. required: - name - data ConnectionAddResponse: type: object properties: connection: type: string description: The connection uuid required: - connection ConnectionBrowseRequest: type: object properties: directory: type: string description: The optional directory to browse to connection: type: string description: The connection uuid required: - directory - connection ConnectionToggleRequest: type: object properties: state: type: boolean description: The state to switch to connection: type: string description: The connection uuid required: - state - connection ConnectionTerminalRequest: type: object properties: directory: type: string description: The optional directory to use as the working directory connection: type: string description: The connection uuid required: - directory - connection 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 DaemonVersionResponse: type: object properties: version: type: string description: The version of the running daemon canonicalVersion: type: string description: The canonical version of the running daemon buildVersion: type: string description: The build timestamp jvmVersion: type: string description: The version of the Java Virtual Machine in which the daemon is running required: - version - canonicalVersion - buildVersion - jvmVersion 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: [ ]