> ## Documentation Index
> Fetch the complete documentation index at: https://hyperspeed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/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:

```json theme={null}
{ "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.

```bash theme={null}
curl https://your-hostname/health
```

```json theme={null}
{
  "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.

```bash theme={null}
curl https://your-hostname/api/v1/public/instance
```

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.