Skip to content

API Specifications

Interactive API documentation rendered from the OpenAPI 3.0 specifications shipped with this repository.

API Gateway

The full reference for the SPOT Platform API Gateway is rendered below. Use the search box, expand individual operations to see request and response schemas, and try requests directly against your deployment by overriding the Servers field at the top of the page.

The same specification is also available as a raw YAML file at codeberg.org/SPOT_Project/sdk -> openapi/api-gateway.yaml, for tooling that prefers to consume the file directly.

Using the OpenAPI specification

The rendered view above is convenient for browsing, but the underlying YAML file is the source of truth. You can pull it into any OpenAPI-compatible tool to generate clients, run contract tests, or import into a request runner.

With Postman

  1. Download the YAML file from Codeberg.
  2. Open Postman, choose Import and select the file.
  3. Postman creates a collection with one folder per tag and one request per operation, including authentication and example payloads.

With Insomnia

  1. Download the YAML file from Codeberg.
  2. Open Insomnia, choose Create -> Import and select the file.
  3. The resulting workspace mirrors the OpenAPI structure.

With Swagger Editor

  1. Open Swagger Editor.
  2. Choose File -> Import URL and paste the Codeberg raw URL above.

Generating an SDK

The included Python and TypeScript SDKs are generated from this specification ; see Python SDK and TypeScript SDK for the supported clients. To roll your own, point openapi-generator at the YAML file:

openapi-generator-cli generate \
    -i https://codeberg.org/SPOT_Project/sdk/raw/branch/main/openapi/api-gateway.yaml \
    -g <language> \
    -o ./generated/<language>

Endpoint overview

The API Gateway exposes the following groups (consult the rendered reference above for the full schema of each):

Group Highlights
Authentication POST /token, POST /client-credentials
Analysis POST /api/v1/analyze, GET /api/v1/analyze/{job_id}
Configuration GET /api/v1/config/... and the kind-parameterised plugin endpoints
Plugins /api/v1/plugins/*, /api/v1/plugin-sources/*, /api/v1/plugin-catalog/*
Workflows /api/v1/workflows, /api/v1/workflows/{id}, default workflow lookup
Knowledge /api/v1/knowledge/readiness, internal sync endpoints
Health & Status GET /health, GET /api/v1/health, GET /api/v1/system/updates

More information

For using the generated SDKs instead of calling the API directly, see: