xpipe-mirror/openapi.yaml
2024-06-25 07:56:30 +00:00

741 lines
26 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

openapi: 3.0.1
info:
title: XPipe API Documentation
description: |
The XPipe API provides programmatic access to XPipes 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": [ "f0ec68aa-63f5-405c-b178-9a4454556d6b" ] }
'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: { "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'
'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: 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
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: [ ]