# Not AI Public REST API ## Description Read-only, customer-facing REST API for the Not AI AI-agent detection platform. Authenticate every request with the aik_v1_ API key minted in the Not AI dashboard, via 'Authorization: Bearer aik_v1_...' or the 'x-api-key' header. All routes are versioned under /v1 and return stable, self-describing JSON. ## Servers - https://stg-api.isnotai.com: Staging (US) - https://stg-api-eu.isnotai.com: Staging (EU) ## Endpoints and operations ### [Analytics](/developers/analytics.md) - [Aggregated analytics for the integration](/developers/analytics/getanalytics.md) ### [Courses](/developers/courses.md) - [List LMS courses extracted from session URLs](/developers/courses/listcourses.md) ### [Health](/developers/health.md) - [Health probe](/developers/health/health.md) ### [Self](/developers/self.md) - [Get the integration this API key resolved to](/developers/self/getintegration.md) ### [Sessions](/developers/sessions.md) - [Get a single tracking session by id](/developers/sessions/getsession.md) - [Get detailed session data (timeline + event counts + page history)](/developers/sessions/getsessiondetails.md) - [List event-level metadata for a session](/developers/sessions/listevents.md) - [List tracking sessions for the caller's integration](/developers/sessions/listsessions.md) - [Label a session as bot or human](/developers/sessions/labelsession.md) ### [Settings](/developers/settings.md) - [Read the integration's risk-classification cutpoints](/developers/settings/getriskthresholds.md) - [Replace the integration's risk-classification cutpoints](/developers/settings/putriskthresholds.md) ### [Stats](/developers/stats.md) - [Get high-level integration stats](/developers/stats/getstats.md) ### [Usage](/developers/usage.md) - [Get API consumption metrics for the integration over a date range](/developers/usage/getusage.md) ### [Users](/developers/users.md) - [Get sessions for an LMS user (paginated)](/developers/users/getusersessions.md) - [List LMS users correlated with sessions](/developers/users/listusers.md) - [Confirm a (userId, fingerprint) pair as a legitimate device](/developers/users/confirmdevice.md) ### [Webhooks](/developers/webhooks.md) - [List webhook subscriptions for your integration](/developers/webhooks/listwebhooksubscriptions.md) - [Create a webhook subscription](/developers/webhooks/createwebhooksubscription.md) - [Get a single webhook subscription](/developers/webhooks/getwebhooksubscription.md) - [Update a webhook subscription](/developers/webhooks/updatewebhooksubscription.md) - [Delete a webhook subscription](/developers/webhooks/deletewebhooksubscription.md) - [Rotate the signing secret for a webhook subscription](/developers/webhooks/rotatewebhooksubscriptionsecret.md) - [Fire a synthetic test event for a webhook subscription](/developers/webhooks/testwebhooksubscription.md) --- # Introduction The Not AI Public REST API is a customer- and AI-agent-facing surface on top of the data the Not AI platform collects. If your application or agent needs to read sessions, users, courses, events, or analytics — or act on a finding by configuring an outbound webhook so Not AI pushes events the moment they fire — this is the surface to call. Not AI is an AI-agent detection platform. The browser pixel collects behavioral signals, the edge and ingest tiers score them, and the dashboard at `dash.isnotai.com` lets your team review what was detected. This API exposes the scored data over standard HTTPS + JSON and lets you close the loop on what's been flagged. ## What it does The v1 surface exposes the following resources: - **Sessions**. `GET /v1/sessions`, `/v1/sessions/{id}`, `/v1/sessions/{id}/details`, `/v1/sessions/{id}/events`. Plus `POST /v1/sessions/{id}/label` to confirm a scored session as bot or human, with optional `confidence` (`high` / `medium` / `low`) and `notes` (free-form, max 1000 chars) — closes the loop on a finding without round-tripping through the dashboard. - **Users**. `GET /v1/users` and `/v1/users/{id}/sessions`. Plus `POST /v1/users/{id}/devices/{fingerprint}/confirm` to mark a `(userId, fingerprint)` pair as a legitimate device for the user — suppresses future shared-device and device-switch anomalies on that pair. - **Courses**. `/v1/courses` (extracted from session URLs). - **Analytics**. `/v1/analytics` (time-series + summary). - **Stats**. `/v1/stats` (high-level integration counters). - **Usage**. `/v1/usage` (your own API consumption). - **Webhooks**. `GET / POST / PATCH / DELETE /v1/webhooks` plus `/rotate-secret` and `/test`. Register HTTP(S) endpoints that receive signed deliveries when bot detections, anomalies, or scored events fire. - **Risk thresholds**. `GET /v1/settings/risk-thresholds` and `PUT /v1/settings/risk-thresholds` to read and replace the integration's risk-classification cutpoints (`mediumAt` and `botAt`, both integers in `[0, 100]` with a minimum gap of 5). - **Self**. `/v1/integration` (the integration the presented key resolved to). - **Health**. `/health` (unauthenticated liveness probe). - **Spec**. `/openapi/v3.json` and `/swagger` (OpenAPI 3 document and UI). Every authenticated route is prefixed with `/v1/`. The full path list and response schemas live in the [OpenAPI document](/developers/spec/swagger.json). ## What it does not do - Provision API keys, configure notification preferences, or onboard integrations. Those flows live in the dashboard at `dash.isnotai.com`. - Authenticate end-users. API keys are integration-scoped. One key represents one customer integration, not a single human. - Expose internal fields. Anything not in the OpenAPI document stays on the dashboard side. ## Staging servers ``` https://stg-api.isnotai.com Staging (US) https://stg-api-eu.isnotai.com Staging (EU) ``` The two apexes are fully isolated stacks. EU and US data never share storage. An API key minted in the US dashboard works only against `https://stg-api.isnotai.com`; an EU key works only against `https://stg-api-eu.isnotai.com`. Pick the base URL that matches the region your integration was provisioned in. The region toggle at the top of these docs rewrites the `https://stg-api.isnotai.com` placeholder in every code sample on the site. ## Design principles These are locked for v1. They are not subject to negotiation inside the v1 series. - **Versioned.** Every authenticated route is under `/v1/`. Adding fields is non-breaking; removing or renaming a field requires `/v2/`. - **JSON only.** Request and response bodies are `application/json`. Field names are camelCase, timestamps are ISO-8601, enums are strings. - **Uniform envelopes.** Single items are `{ "data": { ... } }`. Collections are `{ "data": [...], "pagination": { ... } }`. Errors are `{ "error": { "code", "message", "details" } }`. - **Key implies integration.** The integration is resolved from the validated `aik_v1_*` key. There is no `{integrationHash}` segment in any URL. - **OpenAPI is the contract.** The spec at `/openapi/v3.json` is generated from source. The copy on this site is the artifact published by the release pipeline. - **Standard HTTP semantics.** 200/201/204 for success, 400/401/403/404/409/429 for client problems, 5xx for server problems. Codes are stable strings, not numeric ids. - **Predictable writes.** Mutating endpoints follow REST conventions: `POST` to create, `PUT` for full replace, `PATCH` for partial update, `DELETE` to remove. Side effects are documented per endpoint in the spec. ## Where to go next - [Getting Started](/developers/getting-started). Call the API end-to-end in five minutes. - [Authentication](/developers/authentication). How `aik_v1_*` keys are presented and validated. - [Pagination](/developers/pagination). The cursor envelope used by every list endpoint. - [Error Handling](/developers/error-handling). The error envelope and the stable code list. - [Rate Limits](/developers/rate-limits). Per-tier quotas, the `x-isnotai-tier` echo header, and backoff guidance.