Skip to content
Insight AIInsight AI Docs

API overview

Everything the dashboard does goes through a REST API — which means anything you can click, you can script. Use it to automate ingestion, wire Insight AI into your own tools, or give an AI agent programmatic access to your organization’s knowledge base.

Base URL

Section titled “Base URL”
Environment Base URL
Hosted https://dashboard.insightai.pro/api/v1
Self-hosted http://localhost:8000/api/v1 (adjust host/port to your instance)

All examples in this section use a $BASE variable:

Terminal window
export BASE=https://dashboard.insightai.pro/api/v1

Interactive API explorer

Section titled “Interactive API explorer”

A self-hosted instance serves machine-readable and interactive docs straight from the backend: Swagger UI at /docs, ReDoc at /redoc, and the raw OpenAPI schema at /openapi.json (all at the server root, not under /api/v1). These are the authoritative, always-current reference for every endpoint and schema; the pages here focus on the operations and workflows you’ll actually build against.

Conventions

Section titled “Conventions”
  • Requests and responses are JSON (Content-Type: application/json), with two exceptions: the chat streaming endpoints return NDJSON (application/x-ndjson, one JSON object per line) and the model-pull endpoint returns Server-Sent Events. Yes, those are two different streaming protocols — check the page for the endpoint you’re calling.
  • Every resource is identified by a UUID ("id" fields).
  • Timestamps are ISO-8601.
  • Authentication uses a JWT — sent either as a cookie or a Bearer token — valid for 24 hours. Instances using Clerk sign-in exchange a Clerk session token for the same JWT.
  • Collections and data sources are access-controlled by group membership — see data & ingestion. A resource you can’t access reads as if it doesn’t exist (404).

Errors

Section titled “Errors”

Errors use conventional HTTP status codes with a JSON body:

{ "detail": "Invalid SMB credentials" }
Status Meaning
400 Invalid input — the detail string explains what
401 Missing or expired token
403 Creating a collection in a group you’re not a member of
404 Resource not found — or exists but your groups can’t access it (deliberately indistinguishable)
409 Conflict — e.g. an ingestion is already running, a user is already in a group, or stored credentials could not be decrypted
422 Request body failed validation — detail lists the offending fields
500 Server error — notably "Encryption is misconfigured" on a broken self-hosted key setup
503 An upstream dependency (the SMB server, Google, or an unconfigured Clerk) is unreachable

One quirk worth knowing up front: polling ingestion status on a pipeline that has never run returns 202 with an error-shaped body — see data & ingestion.

Resource map

Section titled “Resource map”
Area Endpoints Covered in
Auth & users /signup, /signin, /signout, /auth/session, /users… Authentication
Groups /user_groups… Data & ingestion
Data sources /data_sources… (SMB and Google Drive) Data & ingestion
Drive integration /integrations/google/drive… Data & ingestion
Collections /collections… Data & ingestion
Pipelines & ingestion /data_pipelines… Data & ingestion
Chat /chats… (blocking and streaming) Chat API
Models /models… Models API