Developer documentation / API v2

Your first calculation.

1. Create your workspace

On a configured deployment, sign up or sign in to the developer account, verify email when required, create an organization and issue a scoped test key. A production key is separate. The local preview does not promise an activated public trial.

Developer account

2. Keep your key on the server

Use X-API-Key and X-G1-Environment: test. Keys are shown once, stored as digests and revocable. Owner/developer roles manage keys; owner/billing roles manage financial records. Browser sessions use HttpOnly cookies and mutations require the dashboard client header.

3. Inspect and quote

Copy a sample calculation request into request.json. The quote endpoint takes it under a calculation field. The calculation endpoint accepts the calculation object directly.

# API_ORIGIN must be your verified deployment origin.
# G1_API_KEY is an environment secret, never commit it.
curl --fail-with-body "$API_ORIGIN/v2/calculations" \
  -H "X-API-Key: $G1_API_KEY" \
  -H 'X-G1-Environment: test' \
  -H 'Idempotency-Key: first-calculation-0001' \
  -H 'Content-Type: application/json' --data-binary @request.json

4. Handle the receipt

Inspect state, quoted_units, charged_units, source_sha256 and cost_version. For HTTP202, poll GET /v2/jobs/{id}. Retry an uncertain POST with the original idempotency key and unchanged body; changing input requires a new key. Rejected/failed work is not charged. Partial batch items retain their own settlement.

Civil time, methods and uncertainty

Supply the IANA timezone and coordinates, local date/time and stated accuracy. DST gaps are invalid; repeated times require an explicit fold where supported. Unknown-time profiles omit time-dependent factors or reject incompatible methods; never invent noon as a known birth time. Use the profile selectors in the exact schema. Named house, ayanamsa and node options differ by family.

Troubleshooting

401: check key/revocation.403: check scope, role or environment.409: inspect idempotency or billing state.422: validate inputs and profile.429: honor Retry-After and quota.503: retry only with the original operation key; investigate availability or release gates. Keep X-Request-ID for support without including keys or birth details.

Retention

Encrypted job input is cleared after settlement. Results normally expire after 24 hours; the idempotency/usage metadata remains. Export results from your own server when needed. Subscription records are financial evidence, not automatically accountant-approved tax invoices.