Authentication

Every call carries an API key as a bearer token. Keys belong to a firm, and every firm is a developer account.

curl https://adv.heliosynctech.com/api/v1/account -H "Authorization: Bearer $AOS_KEY"

#Keys

A key looks like aos_test_ or aos_live_ followed by 40 letters and digits. Make and revoke keys in Firm › Developers.

• The key is shown once. Copy it when you make it. Only its last four characters are kept, so we cannot show it again; make a new one.
• Test keys (aos_test_…) read the sandbox. They cost nothing and never touch a court, a real person or money. Every response from a test key carries AOS-Mode: test.
• Live keys (aos_live_…) read real court data and are billed. Responses carry AOS-Mode: live.
• A key can carry an expiry date. An expired or revoked key stops working at once.

Keep a key in an environment variable or a secret store. Never put it in a mobile app, a browser page, a public repository or a chat. If one leaks, revoke it in Firm › Developers; nothing else needs to change.

#Scopes

A key can do only what its scopes allow. A call outside them returns 403 with the code missing_scope, naming the scope you need.

Scope	Lets the key call
data:read	Court data, research and law
reports:write	Reports
watches:write	Monitoring
webhooks:write	Webhook endpoints and the event log
ai:run	Intelligence
workspace:read	Read your firm's matters, hearings, deadlines, tasks, documents and drafts
workspace:write	Add tasks and notes to your firm's matters

A new key gets every scope except the two workspace:* ones. Add those only for a key that reads your own firm's data, and only to a key your server uses. The workspace endpoints also accept the OAuth token a person gets by connecting an AI app; see workspace and MCP.

Account, usage and sandbox endpoints need no scope.

#Rotate a key without downtime

1. Make a new key with the same scopes.
2. Put it in your secret store and deploy.
3. Watch Last used on the old key in Firm › Developers until it stops moving.
4. Revoke the old key.

#Check your account

GET /account is free and tells you which key you are using and where the account stands.

curl https://adv.heliosynctech.com/api/v1/account -H "Authorization: Bearer $AOS_KEY"

{
  "object": "account",
  "id": "acct_88",
  "name": "Verma & Nair Associates",
  "mode": "test",
  "version": "2026-12-01",
  "plan": { "id": "free", "label": "Free", "credits": 0, "renews_at": null },
  "tier": "T0",
  "discount_pct": 0,
  "postpaid_limit": 0,
  "limits": { "requests_per_second": 50, "daily_spend": 100, "spent_today": 0 },
  "credits": {
    "allowance": 250,
    "allowance_used": 0,
    "allowance_left": 250,
    "grants": [ { "kind": "early", "credits": 1000, "remaining": 1000, "expires_at": "2027-03-01T10:20:00+05:30" } ],
    "wallet": 0,
    "available": 1250
  },
  "key": { "name": "laptop", "mode": "test", "hint": "q7Zp", "scopes": ["data:read", "reports:write", "watches:write", "webhooks:write", "ai:run"], "expires_at": null }
}

tier is your trust tier. credits shows what is left of this month's free allowance, your grants, the wallet, and the total you can spend now (available). limits.requests_per_second is the limit for this key's mode.

GET /usage?from=yyyy-MM-dd&to=yyyy-MM-dd&group=endpoint|day|request is free and tells you what you spent, for the key's mode. from defaults to the 1st of this month, to to today, and the range is at most 366 days. group defaults to endpoint; request lists single calls, newest first, and takes limit and cursor.

curl "https://adv.heliosynctech.com/api/v1/usage?from=2026-12-01&to=2026-12-07&group=endpoint" \
  -H "Authorization: Bearer $AOS_KEY"

{
  "object": "list",
  "from": "2026-12-01",
  "to": "2026-12-07",
  "group": "endpoint",
  "total_credits": 45.5,
  "data": [
    { "object": "usage", "endpoint": "court.case.detail", "requests": 41, "billed": 41, "units": 41, "credits": 41 },
    { "object": "usage", "endpoint": "research.judgment.search", "requests": 9, "billed": 9, "units": 9, "credits": 4.5 }
  ],
  "has_more": false,
  "next_cursor": null
}

requests counts every call, billed those that cost something, units the things counted (cases, pages) and credits what was charged. With group=day each row has day in place of endpoint. With group=request each row is { "object": "request", "request_id", "endpoint", "http_status", "credits", "created_at" }.

#Errors you will see here

• missing_api_key: there was no Authorization header. Send Authorization: Bearer aos_….
• invalid_api_key: the key does not exist, or was typed wrongly. Check for a stray space or newline.
• revoked_api_key and expired_api_key: make a new key.
• account_suspended: the firm is paused; contact support.
• oauth_workspace_only: an OAuth token was used outside the workspace endpoints.

Each is described, with its fix, in errors.