Open in ChatGPT
View as Markdown

Introduction

Base URL 
https://api.isnotai.com

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.

This is version 1.0.21.0 of this API documentation. Last update on Jul 7, 2026.

Available Regions 2 regions
Try it in Postman

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.

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. Call the API end-to-end in five minutes.
  • Authentication. How aik_v1_* keys are presented and validated.
  • Pagination. The cursor envelope used by every list endpoint.
  • Error Handling. The error envelope and the stable code list.
  • Rate Limits. Per-tier quotas, the x-isnotai-tier echo header, and backoff guidance.