Getting started

The CHCK Partner API lets your backend read grading results and card metadata for users who submit cards through CHCK (typically via the CHCK iOS app). Your portal receives webhook notifications when grading finishes, then calls the API to pull full details.

Architecture

flowchart LR
  subgraph partner [Your infrastructure]
    Portal[Partner portal]
    Backend[Your backend]
  end
  subgraph chck [CHCK]
    Web[Partner dashboard]
    API[Partner API /v1]
    DB[(Postgres)]
    Rails[Rails grading pipeline]
  end
  Portal -->|Create API keys| Web
  Backend -->|Bearer shbx_…| API
  API --> DB
  Rails -->|POST webhook| Backend
  Backend -->|GET grading| API

Surface	Who uses it	Purpose
Partner portal (app.chck.ai)	Humans in a browser	Create/revoke API keys, view cards and sessions
Partner API (api.chck.ai)	Your servers	/v1/* JSON API with Bearer tokens
Grading webhooks	CHCK → your URL	Notify when a session completes; you then call the API

WARNING

Never call the Partner API from a browser or mobile app. API keys must live only on your server.

Base URL

Environment	URL
Production	https://api.chck.ai
Local	http://localhost:4000

The API reference defaults to the production server; switch to local in the server dropdown when developing against a machine on port 4000.

Quick test

1. Create an API key in the partner portal (API keys → Create key). See API keys.
2. Call health (no auth):

curl -s https://api.chck.ai/health
# {"status":"ok"}

3. Call account:

curl -s -H "Authorization: Bearer shbx_YOUR_TOKEN" \
  https://api.chck.ai/v1/account

Typical integration flow

1. Register webhook targets for success and failure URLs (Webhooks).
2. When CHCK POSTs a webhook, read grading_session_id from the JSON body.
3. GET /v1/gradings/{id} to load grades, card fields, and presigned image URLs.
4. Optionally GET /v1/cards to sync the user's collection, or GET /v1/cards/{user_card_id} for full card detail.
5. Optionally GET /v1/gradings with cursor pagination to backfill or reconcile.

Next steps

• Authentication — Bearer header format and error codes
• API keys — Creation, storage, and revocation
• Cards — List and detail endpoints
• API reference — Interactive OpenAPI docs