# VibeInfra API reference

Base URL: https://api.vibeinfra.id/api/v1

VibeInfra runs disposable infrastructure incident labs. Public catalog reads need no credential.
Protected account requests accept a browser session or a personal access token; see
[authentication and revocation](https://vibeinfra.id/auth.md).

## Public endpoints

| Method and path | Purpose |
| --- | --- |
| GET /courses | List live catalog entries |
| GET /courses/{courseId} | Read an incident blueprint |
| GET /glossary | Infrastructure definitions |
| GET /labs/capacity | Available sandbox capacity and queue |
| GET /health | API liveness |
| GET /settings/public | Current public configuration |
| GET /credits/packs | Current credit packs and prices |

Example: `GET https://api.vibeinfra.id/api/v1/courses/scenario-01` with `Accept: application/json`.
Read [OpenAPI](https://vibeinfra.id/openapi.json) for parameters and response schemas.

## Agent actions

Use [MCP](https://vibeinfra.id/docs/mcp.md) at https://api.vibeinfra.id/api/v1/mcp for
start_drill → exec_in_sandbox → grade_drill → stop_drill. Default to scenario-01 for autonomous
practice. These tools use actual disposable containers, not a mock API test mode. They never
operate a customer's production infrastructure. Heavy human Flight Simulator clusters are
not suitable for automated benchmarking loops.

## Account credentials

After interactive sign-in, POST /auth/tokens creates a personal access token, GET /auth/tokens
lists tokens and DELETE /auth/tokens revokes a token. Use `Authorization: Bearer <PAT>` on
protected REST requests. PATs inherit the account's permissions and do not use OAuth scopes.

## Error handling

Use HTTP status codes first: 400 invalid input, 401 missing or invalid credentials, 403 denied,
404 absent resource, 429 throttled, and 5xx server or upstream failure. Newer routes use a typed
`{"error":{"code":"not_found","message":"Resource not found","resolution_hint":"Check the catalog"}}`
envelope. Legacy handlers can return a string error or plain text; OpenAPI documents those alternatives.
MCP failures are reported separately through JSON-RPC errors or tool-result `isError`.

## Versioning and integrations

REST routes use /api/v1. Consult [deprecation policy](https://vibeinfra.id/docs/deprecation.md)
before upgrading clients. SDKs and integration resources are listed at
[the developer portal](https://vibeinfra.id/en/developers/).
ACP can prepare an expiring checkout handoff at `/checkout_sessions`; payment still requires
the signed-in pricing flow and payment-provider confirmation. OAuth token exchange and dynamic
agent registration are not supported.