REST API

The apistash REST API is available at https://api.apistash.io. It powers account and workspace management — authentication, API keys, OAuth clients, custom tools, prompts, resources, agent definitions, organizations, teams, and billing.

info

Tools are executed over MCP, not REST. To run tools, connect an MCP client to the MCP endpoint. This REST API is for managing your account, governed content, and platform configuration.

Interactive reference

The full API is documented with OpenAPI. Explore and test every endpoint interactively in the Swagger UI:

https://api.apistash.io/swagger-ui/

The raw OpenAPI JSON spec is available at:

https://api.apistash.io/api-docs/openapi.json

Authentication

Protected endpoints require a credential: a JWT access token in the Authorization: Bearer header, or an API key in the X-API-Key header:

Authorization: Bearer <jwt-access-token>
X-API-Key: <api-key>

See Authentication for how to obtain a key. Some endpoints — creating API keys, managing OAuth clients, changing your email, and deleting your account — require an interactive dashboard session and reject API keys.

Endpoint groups

Prefix	Covers
/api/auth/*	Registration, login, token refresh, email verification, password reset
/api/me/*	Your profile, API keys, custom tools, prompts, resources, agents, usage, and billing
/api/organizations/{slug}/*	Organization members, roles, teams, custom tools, prompts, resources, agents, settings, and billing
/oauth/*, /.well-known/*	OAuth authorization, token, and discovery endpoints

Response envelope

Every response — success or failure — comes back in the same envelope, so a client can parse one shape for both. The payload lives under data, never at the top level:

{
	"status": 200,
	"data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "My MCP Client" },
	"errors": null,
	"meta": {
		"timestamp": "2026-07-27T10:15:30.123456+00:00",
		"request_id": "018f3c2a-7b41-7c3e-9d2a-6f5e4d3c2b1a",
		"version": "2.0.0"
	}
}

Field	Description
status	Mirrors the HTTP status code.
data	The payload on success; null on error.
errors	Array of error objects on failure; null on success.
meta	timestamp (RFC 3339), request_id, and the API version.

The request_id is also returned in the X-Request-Id header — quote it when reporting a problem.

info

A few endpoints are exempt because an external specification pins their shape: the OAuth token and discovery endpoints (RFC 6749, RFC 8414, RFC 9728), the OpenAPI spec endpoint, and the /health and /ready probes.

Error responses

On failure, data is null and errors carries one or more entries:

{
	"status": 404,
	"data": null,
	"errors": [
		{
			"code": "not_found",
			"message": "User not found",
			"detail": null
		}
	],
	"meta": {
		"timestamp": "2026-07-27T10:15:30.123456+00:00",
		"request_id": "018f3c2a-7b41-7c3e-9d2a-6f5e4d3c2b1a",
		"version": "2.0.0"
	}
}

Branch on code — it is a stable, machine-readable slug — rather than on message, which is written for humans and may be reworded. detail carries structured context when there is any (for example, which field failed validation) and is null otherwise.

HTTP status	Meaning
400	Bad request — malformed JSON, a wrong type, or a missing or null required value
401	Not authenticated
402	Payment required — plan limit reached
403	Forbidden — insufficient permissions
404	Resource not found
409	Conflict — resource already exists
422	Unprocessable — a well-shaped request violates a domain rule
429	Rate limit exceeded
500	Internal server error
503	Temporarily unavailable — nothing was changed, retry later