Every Code</>sensei action available in the dashboard is also reachable over a JSON REST API. The endpoints are mounted under /api/v1/ on the same domain as the web UI, share the session cookie for authentication, and respect the same per-account authorization checks.

The API surface is contributed by the open-source nungaasia packages this site depends on. Each section below lists the endpoints exposed by one of those packages; for the full DRF schema, point a tool like httpie or curl at the path and inspect the response.

Account — /api/v1/account/

User registration, sign-in/sign-out, email verification, password reset, OTP verification, profile read/write, and the follow / block social-graph endpoints.

POST   /api/v1/account/auth/register/
POST   /api/v1/account/auth/login/
POST   /api/v1/account/auth/logout/
POST   /api/v1/account/auth/password-reset/
GET    /api/v1/account/users/me/
GET    /api/v1/account/users/<uuid>/

Alert — /api/v1/alert/

Per-user notification list, mark-read / mark-all-read, and device token registration for mobile push.

GET    /api/v1/alert/
PATCH  /api/v1/alert/<uuid>/read/
POST   /api/v1/alert/mark-all-read/
DELETE /api/v1/alert/<uuid>/
POST   /api/v1/alert/devices/register/
DELETE /api/v1/alert/devices/unregister/

Advertise — /api/v1/advertise/

Ad zones, the weighted-random pick for a zone, and the impression / click tracking endpoints. Used today for in-product house ads (e.g. surfacing relevant docs to the dashboard) — not for third-party ad delivery.

GET    /api/v1/advertise/zones/
GET    /api/v1/advertise/ads/
GET    /api/v1/advertise/ads/random/<zone-slug>/
POST   /api/v1/advertise/ads/<uuid>/impression/
POST   /api/v1/advertise/ads/<uuid>/click/

Payment — /api/v1/payment/

Wallet balance, transaction history, and the Stripe-backed web-checkout endpoints used by the dashboard's Get started buttons. Cashout, agent locator, settlement, and compliance endpoints are exposed for completeness; the production deployment of codesensei.cloud uses only the web-checkout and webhook routes.

GET    /api/v1/payment/balance/
GET    /api/v1/payment/transactions/
POST   /api/v1/payment/web/checkout/
POST   /api/v1/payment/web/webhook/

Subscription — /api/v1/subscription/

List available tiers, subscribe to one, fetch the current subscription, cancel it, or check a per-feature gate by key.

GET    /api/v1/subscription/tiers/
POST   /api/v1/subscription/subscribe/
GET    /api/v1/subscription/current/
POST   /api/v1/subscription/cancel/
GET    /api/v1/subscription/check/?feature=max_servers

Authentication

All endpoints share the web session cookie. Sign in via the web UI, then hit the API from the same browser context with the same sessionid cookie. Token authentication is not enabled by default on this deployment; if you need it for a server-to-server integration, contact reach-us@codesensei.cloud.

Rate limits

DRF's throttle classes are not currently enforced on the public endpoints; abuse is caught at the edge proxy via per-IP request budgets documented in the operator runbook. Treat the API as best-effort for now and avoid running tight polling loops against it.

Response shape

Every endpoint returns JSON with the following envelope shape on success:

{
  "ok": true,
  "data": <endpoint-specific payload>,
  "meta": {"count": 12, "page": 1, "page_size": 20}
}

On error, the same envelope carries an errors array instead of a data field, with each entry carrying a code, a message, and an optional field when the error is form-validation-shaped. Treat ok: false as the canonical "this request did not succeed" flag in client code rather than relying on HTTP status — DRF returns 200 for some validation errors and the envelope normalises the distinction.

Content type and CSRF

Endpoints accept application/json and application/x-www-form-urlencoded request bodies. JSON is the recommended shape for non-trivial payloads. The CSRF token middleware is active on this deployment because the same session cookie is used across the web UI and the API — read the X-CSRFToken header from the csrftoken cookie that Django sets on first GET and echo it back on every state-changing request.

Pagination

List endpoints paginate with the standard DRF ?page=<n>&page_size=<n> query parameters. Default page size is twenty; the maximum is one hundred. The meta block on the response envelope carries count (total rows matching the filter, across all pages), page (the current page index, 1-based), and page_size (the effective page size after clamping to the hundred-row ceiling). Iterate by incrementing page until the returned data array is shorter than the requested page size.

Versioning policy

The /api/v1/ prefix is the long-term stable surface. We add fields, never remove them, and never change the meaning of an existing field. New endpoints are added under /api/v1/ without a version bump; breaking changes — should any ever ship — would land under /api/v2/ and run alongside the v1 surface for at least twelve months before v1 is sunset. If you build against v1 today, your client will continue to work tomorrow.

Webhooks for deploy events

Deploy lifecycle events — queued, started, succeeded, failed — can be forwarded to a URL of your choice via the project settings page. The webhook payload is the deployment row's JSON representation, signed with an HMAC-SHA-256 header (X-CodeSensei-Signature) over the request body using the per-project webhook secret you configure. Verify the signature on receipt; otherwise an attacker who guesses your endpoint can fake deploy notifications.

Programmatic deploys

A common integration pattern is to trigger a deploy from your own CI pipeline after tests pass. The deploy-create endpoint takes a project ID, a deployment type (update or initial), and an optional branch override, and returns the deployment row immediately while the actual work happens asynchronously on the platform's worker. Poll the deployment-detail endpoint or wait for the webhook to learn whether it succeeded.

Filtering and search

List endpoints accept the standard DRF filtering and ordering query parameters. Common patterns:

  • ?ordering=-created_at — sort descending by creation time. Default ordering is endpoint-specific; the response envelope's meta.ordering field documents the active sort.
  • ?search=<term> — case-insensitive search across the endpoint's documented search fields. Server, project, and deployment list endpoints each declare their search fields in the endpoint summary (hit the endpoint without parameters to see them).
  • ?status=succeeded — field equality filter. Any indexed field on the underlying model is filterable this way.

Error handling and retries

Treat the API as you would any HTTP service. Retry on 503 (service temporarily unavailable) and on connection errors with exponential back-off; treat 4xx as terminal client errors that retrying will not fix. The platform's worker queue processes deploys idempotently — if you accidentally fire two deploy-create requests for the same project within a second, the worker de-duplicates on the project ID + commit SHA pair and you get a single deploy.