Docs
Open app

API

API setup guide

The v1 API lets authorized clients read groups, balances, expenses, recurring expenses, settlements, and spend summaries, and make supported changes. Every endpoint is in the API reference.

Authentication

AllSquare uses OAuth authorization code with PKCE.

  1. Register a public client at /api/oauth/register.
  2. Request the v1 resource URI published by /.well-known/oauth-protected-resource/api/v1.
  3. Ask for allsquare:api:read, or both allsquare:api:read allsquare:api:write to make changes.
  4. Send the resulting bearer token to v1 endpoints.
First request
curl https://allsquare.app/api/v1/groups \
  -H "Authorization: Bearer $ALLSQUARE_TOKEN"

Try it in the reference

To send requests from the interactive reference, register the exact /docs/api URL on this host as the client redirect URI, then enter the returned client ID in the reference's authentication panel. It sends the v1 resource parameter and uses SHA-256 PKCE; select the write scope before trying write operations.

Requests

Write requests accept an optional Idempotency-Key header for safe retries. Within 24 hours, a retry with the same key and request returns the original result with an Idempotent-Replayed: true header, meaning nothing new was written. After 24 hours the key can be used again, so a late retry may write twice.

Send expense dates as the user's local calendar date; when omitted, the server uses today's UTC date.

Expense lists use limit and an opaque cursor; pass nextCursor from one response to the next request.

Related

  • The machine-readable OpenAPI specification is generated from the API request and response contracts.
  • For scripts and coding agents, the AllSquare CLI wraps this API with safe retries and JSON output.
  • To connect a chat assistant instead, see the AI assistant guide.