API Overview

Base URL, authentication, response format, and shared conventions for the Hyperspeed REST API.

Base URL

All API endpoints are served from the same origin as the Hyperspeed web UI:

https://your-hostname/api/v1

When running the default Docker stack locally, the API is reachable at http://localhost/api/v1 (through Caddy on port 80) or directly at http://localhost:8080 for debugging.

Authentication

All endpoints under /api/v1 (except /api/v1/public/* and /api/v1/auth/*) require a Bearer token in the Authorization header:

Authorization: Bearer <token>

Tokens are obtained by logging in with email and password, or by using a service account token (prefixed sa_). See Authentication for details.

Response format

All responses are JSON. Successful responses return the relevant resource or a wrapper object. Error responses return a JSON body with an error field:

{ "error": "space not found" }

Common HTTP status codes:

Status	Meaning
200 OK	Request succeeded
201 Created	Resource was created
204 No Content	Success with no body (e.g. delete)
400 Bad Request	Invalid input or missing required field
401 Unauthorized	Missing or invalid token
403 Forbidden	Valid token but insufficient permissions
404 Not Found	Resource does not exist
500 Internal Server Error	Server-side error

Request bodies

POST and PATCH requests must send Content-Type: application/json with a JSON body.

Health endpoint

GET /health returns the server status and build information. No authentication required.

curl https://your-hostname/health

{
  "status": "ok",
  "version": "1.2.3",
  "git_sha": "abc1234"
}

version and git_sha reflect the values baked in at build time. They default to "dev" and "" if the binary was not built with the corresponding ldflags.

Public instance info

GET /api/v1/public/instance returns public metadata about this installation. No authentication required.

curl https://your-hostname/api/v1/public/instance

{
  "provisioning_enabled": true,
  "provisioning_base_domain": "hyperspeedapp.com"
}

provisioning_enabled is true only when the server is configured with PROVISIONING_BASE_URL, PROVISIONING_INSTALL_ID, and PROVISIONING_INSTALL_SECRET.

Rate limiting

The Hyperspeed API does not implement built-in rate limiting at the application layer. Throttling behavior depends on your infrastructure (reverse proxy, load balancer, etc.).

Organization and space IDs

Most resource endpoints are scoped under an organization:

/api/v1/organizations/{orgId}/...

Use GET /api/v1/organizations (authenticated) to retrieve your organization ID. Self-hosted deployments have exactly one organization.