Skip to main content

API Reference

Agon exposes a REST API that the desktop app and mobile app both use. If you are a developer and want to integrate with Agon or build on top of it, this page explains the basics.

Base URL​

The API runs locally on the studio manager's machine:

http://localhost:8000

When clients connect from outside (via the mobile app), they use the studio's Cloudflare Tunnel URL, which looks like:

https://your-studio.trycloudflare.com

All endpoints are versioned under /api/v1/. For example:

http://localhost:8000/api/v1/clients

This page covers the main backend, which runs locally per studio. Licensing, checkout, and the hosted-AI proxy are handled by a separate, centrally-hosted service — see License Server endpoints.

Authentication​

All protected endpoints require a valid JWT access token in the Authorization header:

Authorization: Bearer <your_access_token>

To get a token, send a POST request to /api/v1/auth/login with your email and password:

{
  "email": "manager@mystudio.com",
  "password": "your-password"
}

The response includes an access_token (valid for 8 hours for desktop, 30 days for mobile) and a refresh_token.

When the access token expires, send the refresh token to POST /api/v1/auth/refresh to get a new access token without logging in again.

Response format​

All endpoints return JSON. Successful responses return the requested data directly.

Example successful response:

{
  "id": 42,
  "full_name": "Jane Smith",
  "email": "jane@example.com",
  "status": "active"
}

Error format​

All error responses follow this structure:

{
  "error": {
    "code": "BOOKING_CLASS_FULL",
    "message": "This class is full. Would you like to join the waitlist?",
    "details": {}
  }
}

Common error codes:

CodeMeaning
AUTH_INVALID_CREDENTIALSWrong email or password
AUTH_TOKEN_EXPIREDAccess token has expired — refresh it
AUTH_INSUFFICIENT_PERMISSIONSYour role doesn't allow this action
BOOKING_CLASS_FULLNo spots available in the class
BOOKING_ALREADY_EXISTSClient is already booked for this class
BOOKING_NO_MEMBERSHIPClient has no active membership or credits (also used for appointment booking)
BOOKING_CANCELLATION_WINDOW_PASSEDToo close to class start to cancel
CHECKIN_NO_BOOKINGNo confirmed booking found for this client and class
CHECKIN_OUTSIDE_WINDOWOutside the check-in time window
CHECKIN_ALREADY_CHECKED_INClient is already checked in
WAIVER_SIGNATURE_REQUIREDClient has an unsigned required waiver and cannot book
APPOINTMENT_SERVICE_INACTIVEThe requested appointment service has been deactivated
APPOINTMENT_INSTRUCTOR_INACTIVEThe requested instructor's account is not active
APPOINTMENT_IN_PASTRequested appointment start time is in the past
APPOINTMENT_OUTSIDE_AVAILABILITYRequested time falls outside the instructor's availability
APPOINTMENT_SLOT_CONFLICTRequested time overlaps another confirmed appointment (including buffer time)
APPOINTMENT_ALREADY_CANCELLEDAppointment is not in a confirmed state and cannot be cancelled again
APPOINTMENT_NOT_CONFIRMEDAppointment must be confirmed to be marked completed or no-show
NOT_FOUNDThe requested resource does not exist
VALIDATION_ERRORThe request body is missing required fields or has invalid values

Interactive documentation (Swagger UI)​

Agon's API includes interactive documentation powered by Swagger UI. When Agon is running, open this URL in your browser:

http://localhost:8000/docs

The Swagger UI lets you browse all available endpoints, see their parameters and response formats, and make test requests directly from your browser.

An alternative OpenAPI (ReDoc) view is also available at:

http://localhost:8000/redoc

API versioning​

All current endpoints are under /api/v1/. When breaking changes are introduced in a future version, they will be available under /api/v2/ while /api/v1/ remains active for a transition period.