ArenOS

ArenOS Developers: API, OAuth, webhooks, and AI agents

Use the ArenOS API, CLI and webhooks with AI agents and internal tools.

Use the ArenOS REST API to automate your organization from AI agents, scripts and internal tools: read activities, registrations, memberships, bookings, orders, members and schedules, and create activities, pricing options, coupons and announcements.

Using an AI agent like Claude Code? Point it at this guide and the OpenAPI document (/api/openapi.json), then tell it what you want to build.

Authentication

  • Create a token in Dashboard › Settings › API access (Plus plan and above). Choose read, or read and write.
  • Send it on every request: Authorization: Bearer ak_…
  • Copy the full token when it's shown. Later you'll only see its name and first characters, and those won't authenticate.

A missing, wrong or revoked token returns 401. A read-only token calling a write endpoint returns 403 insufficient_scope.

Requests and responses

  • Base path: /api/v1. Bodies are JSON and capped at 16 MiB (413 above that).
  • Money is in paise (₹1 = 100 paise). Times are ISO 8601.
  • Lists return { "data": [...], "next_cursor": "…" }. Pass limit (1–100, default 25) and cursor (the previous next_cursor) to page. next_cursor is null on the last page.
  • Every JSON response carries meta.api_version and meta.request_id; the request id is also in the X-Request-Id header. Quote it when you contact support.
  • Errors look like { "error": { "code": "not_found", "message": "…" } }. Codes include unauthorized, insufficient_scope, plan_required, invalid_parameter, validation, not_found, conflict, rate_limited and unsupported_api_version.

Versioning and deprecations

ArenOS uses date-based API versions. The current version is 2026-09-23.

  • Send X-ArenOS-Api-Version: 2026-09-23 to pin it, or leave the header out to get the current version. Every response names the version that served it.
  • An unsupported value returns 400 unsupported_api_version. It never silently falls back to another version.
  • Backward-compatible additions (new fields, endpoints or enum values) can arrive within a version, so ignore fields you don't recognise. A breaking change always gets a new dated version.
  • A deprecated endpoint gets at least 90 days' notice, except for urgent security, privacy, legal or reliability issues. Its responses carry Deprecation and Sunset headers and a Link to the migration notes.

Rate limits

  • 600 requests per minute per token and 1,200 per minute per IP address.
  • Every response reports the tighter applicable limit with the IETF fields RateLimit-Policy ("api-token-requests";q=600;w=60) and RateLimit ("api-token-requests";r=599;t=42), plus RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.
  • Over the limit you get 429 rate_limited with Retry-After in seconds. Wait that long, then retry.

Endpoints

Organizer (token or OAuth):

  • GET /api/v1/me: the organization, token scopes and published item counts.
  • GET|POST /api/v1/activities, GET|PATCH|DELETE /api/v1/activities/{id}, GET|POST /api/v1/activities/{id}/pricing_options, POST|DELETE /api/v1/activities/{id}/publication to publish or unpublish.
  • GET /api/v1/registrations (activity_id, status) and GET /api/v1/registrations/{id or receipt number}.
  • GET /api/v1/memberships and GET /api/v1/membership_subscriptions (status). Plans show locked once someone has joined; memberships list their add-on products; subscriptions include first_payment_discount_paise and the addons_order; orders bought as add-ons carry membership_subscription.
  • GET /api/v1/bookings (from, to), GET /api/v1/orders (status), GET /api/v1/products.
  • GET|POST /api/v1/coupons. A duplicate code returns 409 conflict.
  • GET /api/v1/members (q) and GET /api/v1/members/{id}.
  • GET|POST /api/v1/announcements: send now, schedule, or save a draft; inbox plus email, SMS or WhatsApp.
  • GET /api/v1/schedules, GET /api/v1/schedules/{id}, GET /api/v1/schedules/{id}/games (status), GET /api/v1/schedules/{id}/standings.

Public, no account needed:

  • GET /api/v1/discoveries: search published activities, bookings, memberships and schedules (q, city, sport, kind).
  • POST /api/v1/guest_sessions returns a gs_… token for the free schedule maker. Use it with GET|POST /api/v1/guest/schedules, GET|PATCH /api/v1/guest/schedules/{id} and GET /api/v1/guest/schedules/{id}/standings. Guest schedules last 30 days.

OpenAPI

  • Full document: /api/openapi.json (also at /api/v1/openapi.json).
  • Organizer endpoints only: /api/openapi/manager.json.
  • Guest and public endpoints only: /api/openapi/guest.json.

They're OpenAPI 3.1, so you can load them into Postman, Insomnia or a code generator, or give them to an AI agent.

CLI

Install the arenos command (needs Node.js 18 or newer):

curl -fsSL https://arenos.in/cli/install.sh | sh
arenos login
arenos whoami
arenos registrations list --status active --all
arenos schedules standings DEMSCH4
arenos api POST /coupons --data '{"code":"MONSOON10","kind":"percent","value":10}'

It stores your token in ~/.arenos/config.json, readable only by you. Set ARENOS_API_TOKEN to skip login in scripts, and add --json to any command for machine-readable output. When rate limited, it waits Retry-After and retries on its own.

OAuth for apps that act for a user

Register an OAuth app under Developer and send the user to /oauth/authorize?client_id=…&redirect_uri=…&scope=read%20write. Then exchange the code at POST /api/oauth/token with grant_type=authorization_code, sending your client credentials in the body or with HTTP Basic auth. Access tokens start with oa_ and last an hour. Refresh them with grant_type=refresh_token; the refresh token rotates on every use.

Webhooks

Add an endpoint in Settings › API access and choose from these events: registration.created, registration.paid, registration.canceled, booking.paid, booking.canceled, subscription.activated, subscription.canceled, order.paid, sponsorship.approved, game.scored, announcement.sent and member.joined.

Each delivery is a JSON POST with these headers:

  • X-ArenOS-Event
  • X-ArenOS-Delivery, a unique id; use it to ignore duplicates.
  • X-ArenOS-Signature: t=<unix time>,v1=<hex>. v1 is the HMAC-SHA256 of <t>.<raw body> with your endpoint's signing secret. Recompute it and reject old timestamps.

Reply with any 2xx within 8 seconds. Any other response, or a timeout, is retried after 5 minutes, 30 minutes, 2 hours and 12 hours: five attempts in all, about 15 hours. After that the delivery is marked failed, and you can see it in Settings › API access.

Try it

curl "https://arenos.in/api/v1/schedules" \
  -H "Authorization: Bearer $ARENOS_API_TOKEN" \
  -H "X-ArenOS-Api-Version: 2026-09-23"

Updated 23 September 2026

ArenOS Developers: API, OAuth, webhooks, and AI agents · Support · ArenOS