Introduction

The Acme API is a sample REST API used to demonstrate the API docs section of this starter template. Endpoints follow a conventional REST shape, return JSON, and authenticate with Bearer tokens.

When you adapt the starter for your own project, replace the OpenAPI spec at openapi/v3.yaml with your real schema and run npm run gen:api to rebuild the markdown.

Basic flow

1. Create a token. Generate an API token from your account settings.
2. Make a request. Set the Authorization: Bearer <token> header on every request.
3. Handle the response. Successful requests return JSON with 2xx status codes; failures return 4xx or 5xx with a JSON error body.

Authentication

The API uses token-based authentication. Each request must include a valid token in the Authorization header.

• Tokens are generated through the web interface in your account’s API settings.
• Tokens never expire but can be revoked at any time.

Authentication header

Include your API token in all requests using the Bearer scheme:

Authorization: Bearer your-api-token

Rate limits

The starter template ships with a placeholder rate-limit policy. Adjust this section to match the limits your real API enforces.

• Default limit: 2 requests per second per account, shared across all endpoints.
• Detection: requests that exceed the limit get a 429 Too Many Requests response.
• Recovery: respect the Retry-After response header before retrying. Use exponential backoff as a fallback if Retry-After is missing.

Rate limit headers

• X-RateLimit-Limit — the maximum number of requests allowed in the current window.
• X-RateLimit-Remaining — the number of requests left in the current window.
• Retry-After — sent on 429 responses; seconds to wait before retrying.

Support

For technical questions about the API, contact us.