Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.insito.app/llms.txt

Use this file to discover all available pages before exploring further.

The Insito API has two authentication modes — one for SDK traffic from your mobile app, one for dashboard traffic from the admin.insito.app web UI. They never overlap.

​
SDK: project API keys

All /v1/sdk/* routes require a Bearer token in the Authorization header. The token is your project’s API key from admin.insito.app → Project → Settings → API key. 
POST /v1/sdk/event HTTP/1.1
Host: api.insito.app
Content-Type: application/json
Authorization: Bearer proj_e014b2efbf474530955c48d40c5bb794

{ "event": "checkout_completed", "userId": "user-123" }
API keys:
  • Format: proj_xxx where xxx is a 32-char random hex string.
  • One key per project — rotating creates a new key and invalidates the old one immediately.
  • Scoped to one project’s data. Reads and writes outside that project return 404.
API keys are project secrets. Treat them like a database password — never commit to public repos, never hard-code into your app source. For React Native, use react-native-config or expo-constants’s extra field.

​
Dashboard: Supabase JWTs

/v1/dashboard/* routes require a Supabase auth JWT in the same Authorization: Bearer shape. 
GET /v1/dashboard/projects HTTP/1.1
Host: api.insito.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Get one by signing in via Supabase Auth against the same project the dashboard uses. The JWT is short-lived (1 hour by default) — refresh via the refresh token flow. Routes apply per-org RLS based on the JWT’s sub (user ID) and the member table. Cross-org access returns 404.

​
Rate limits

Per-endpoint, per-key/JWT. See Plan limits for response caps. Other endpoints (identify, event, impression) have generous limits — ~100 req/s burst, ~10 req/s sustained per project. Going above returns 429 Too Many Requests with a Retry-After header.

​
Error shape

Every non-2xx response looks like: 
{
  "error": "error_code",
  "details": { /* optional, context-specific */ }
}
Common codes:
CodeHTTPMeaning
unauthorized401Missing or malformed Authorization header
invalid_token401Token recognized as ours but rejected (rotated, deleted)
forbidden403Token is valid but the action isn’t allowed
not_found404Resource doesn’t exist OR exists in a different org (deliberately ambiguous)
validation_failed400Body failed zod schema validation
rate_limited429Rate limit hit; honor Retry-After
response_limit_reached402Plan exhausted; payload includes upgradeUrl
internal_error500Bug on our end; included requestId for support

​
Versioning

The API is versioned via URL prefix (/v1). We bump major versions for breaking changes; backwards-compatible additions never get a new version. Deprecation notices ship in the Sunset and Deprecation HTTP headers per RFC 8594 at least 6 months ahead of removal.