mirror of
https://github.com/xpipe-io/xpipe.git
synced 2024-08-27 07:51:18 +12:00
417 lines
15 KiB
YAML
417 lines
15 KiB
YAML
openapi: 3.0.1
|
||
info:
|
||
title: XPipe API Documentation
|
||
description: |
|
||
The XPipe API provides programmatic access to XPipe’s features.
|
||
|
||
The XPipe application will start up an HTTP server that can be used to send requests.
|
||
You can change the port of it in the settings menu.
|
||
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.
|
||
|
||
You can quickly get started by either using this page as an API reference or alternatively import the [OpenAPI definition file](/openapi.yaml) into your API client of choice.
|
||
See the authentication handshake below on how to authenticate prior to sending requests.
|
||
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.
|
||
|
||
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": [ { "uuid": "f0ec68aa-63f5-405c-b178-9a4454556d6b", "category": ["default"] ,
|
||
"connection": ["local machine"], "type": "local" },
|
||
{ "uuid": "e1462ddc-9beb-484c-bd91-bb666027e300", "category": ["default", "category 1"],
|
||
"connection": ["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'
|
||
/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: { "uuid": "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: { "uuid": "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: { "uuid": "f0ec68aa-63f5-405c-b178-9a4454556d6b", "command": "echo $USER" }
|
||
invalid:
|
||
summary: invalid
|
||
value: { "uuid": "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'
|
||
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
|
||
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:
|
||
uuid:
|
||
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
|
||
connection:
|
||
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:
|
||
- uuid
|
||
- category
|
||
- connection
|
||
- type
|
||
required:
|
||
- found
|
||
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:
|
||
type: object
|
||
discriminator:
|
||
propertyName: type
|
||
properties:
|
||
type:
|
||
type: string
|
||
required:
|
||
- type
|
||
oneOf:
|
||
- $ref: '#/components/schemas/ApiKey'
|
||
- $ref: '#/components/schemas/Local'
|
||
ApiKey:
|
||
description: API key authentication
|
||
allOf:
|
||
- $ref: '#/components/schemas/AuthMethod'
|
||
- type: object
|
||
properties:
|
||
key:
|
||
type: string
|
||
description: The API key
|
||
required:
|
||
- key
|
||
Local:
|
||
description: Authentication method for local applications. Uses file system access as proof of authentication.
|
||
allOf:
|
||
- $ref: '#/components/schemas/AuthMethod'
|
||
- type: object
|
||
properties:
|
||
authFileContent:
|
||
type: string
|
||
description: The contents of the local file $TEMP/xpipe_auth. This file is automatically generated when XPipe starts.
|
||
required:
|
||
- authFileContent
|
||
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
|
||
responses:
|
||
Success:
|
||
description: The action was successfully performed.
|
||
BadRequest:
|
||
description: Bad request. Please check error message and your parameters.
|
||
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.
|
||
securitySchemes:
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
description: The bearer token used is the session token that you receive from the handshake exchange.
|
||
security:
|
||
- bearerAuth: []
|