API Reference

Generated endpoint reference from the FastAPI OpenAPI schema.

Base URL in local development: http://localhost:8000. Production writes use Authorization: Bearer il_...; read routes also accept signed dashboard cookie where noted.

#Gate

#POST /v1/gate

Gate

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no

JSON body

Field	Type	Required
`request`	`string` (min length 1, max length 20000)	yes
`session_id`	`string` (min length 1, max length 120)	yes
`context`	`object` or `null`	no
`clarification_response`	`string` (max length 20000) or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

Example

result = intentlayer.gate("cancel it", "session-42")

#Events

#POST /v1/events

Ingest Event

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no

JSON body

Field	Type	Required
`session_id`	`string` (min length 1, max length 120)	yes
`event`	`rephrase`	`accept`	`regenerate`	`abandon`	`correction`	yes
`detail`	`string`	no
`created_at`	`string` or `null`	no
`gate_caught`	`boolean`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

Example

intentlayer.record_outcome("session-42", "correction", detail="I meant order A1002")

#Playground

#POST /v1/playground

Playground

JSON body

Field	Type	Required
`request`	`string` (min length 1, max length 500)	yes

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#Failures

#GET /v1/failures

Failures

Parameters

Name	In	Type	Required
`page`	query	`integer` (min 1)	no
`page_size`	query	`integer` (min 1, max 100)	no
`authorization`	header	`string` or `null`	no
`intentlayer_session`	cookie	`string` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#Report

#GET /v1/report

Report

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no
`intentlayer_session`	cookie	`string` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#GET /v1/report.html

Report Html

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no
`intentlayer_session`	cookie	`string` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#Overview

#GET /v1/overview

Overview

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no
`intentlayer_session`	cookie	`string` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#Evals

#GET /v1/evals

Export Evals

Parameters

Name	In	Type	Required
`since`	query	`string` or `null`	no
`cluster`	query	`string` or `null`	no
`dimension`	query	`goal`	`output_format`	`scope`	`constraints` or `null`	no
`authorization`	header	`string` or `null`	no
`intentlayer_session`	cookie	`string` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#POST /v1/evals/{eval_id}/status

Set Eval Status

Parameters

Name	In	Type	Required
`eval_id`	path	`string`	yes
`authorization`	header	`string` or `null`	no

JSON body

Field	Type	Required
`status`	`accept`	`mute`	yes

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#Experiment

#GET /v1/experiment

Get Experiment

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no
`intentlayer_session`	cookie	`string` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#Config

#GET /v1/config

Get Config

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no
`intentlayer_session`	cookie	`string` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#PUT /v1/config

Put Config

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no

JSON body

Field	Type	Required
`ambiguity_threshold`	`number` (min 0.0, max 1.0) or `null`	no
`dimension_threshold`	`number` (min 0.0, max 1.0) or `null`	no
`failure_cost`	`number` or `null`	no
`ask_friction`	`number` (min 0.0) or `null`	no
`answered_fatigue_multiplier`	`number` (min 1.0) or `null`	no
`high_fatigue_multiplier`	`number` (min 1.0) or `null`	no
`request_length_friction`	`number` (min 0.0) or `null`	no
`request_length_reference`	`integer` or `null`	no
`mode_default`	`observe`	`suggest`	`auto` or `null`	no
`experiment`	`object` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#Auth

Dashboard Login

JSON body

Field	Type	Required
`api_key`	`string` (min length 4, max length 200)	yes

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#POST /v1/dashboard/logout

Dashboard Logout

Responses

Status	Meaning
`200`	Successful Response

#Operations

#GET /health

Health

Responses

Status	Meaning
`200`	Successful Response

#POST /v1/clusters/run

Run Clusters

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#GET /v1/questions/stats

Get Question Stats

Parameters

Name	In	Type	Required
`authorization`	header	`string` or `null`	no
`intentlayer_session`	cookie	`string` or `null`	no

Responses

Status	Meaning
`200`	Successful Response
`422`	Validation Error

#Authentication

Writable production routes require bearer keys beginning with il_. Read routes accept same bearer key or signed intentlayer_session cookie. Local development can disable auth. Hosted demo rejects write routes with 403 except public playground.

#Rate limits

POST /v1/playground: 10 requests/minute/IP.
POST /v1/gate: 120 requests/minute/key when auth is enabled.
Limits use in-memory sliding windows per backend process. 429 includes Retry-After.

#Error codes

Status	Meaning
`401`	Missing, invalid, or expired API credential/session.
`403`	Write rejected in hosted demo mode.
`404`	Eval ID not found for tenant.
`422`	FastAPI request validation failed.
`429`	In-process rate limit exceeded.

Source truthbackend/app/main.pybackend/app/evals.pybackend/app/schemas.py

API Reference

#Gate

#POST /v1/gate

#Events

#POST /v1/events

#Playground

#POST /v1/playground

#Failures

#GET /v1/failures

#Report

#GET /v1/report

#GET /v1/report.html

#Overview

#GET /v1/overview

#Evals

#GET /v1/evals

#POST /v1/evals/{eval_id}/status

#Experiment

#GET /v1/experiment

#Config

#GET /v1/config

#PUT /v1/config

#Auth

#POST /v1/dashboard/login

#POST /v1/dashboard/logout

#Operations

#GET /health

#POST /v1/clusters/run

#GET /v1/questions/stats

#Authentication

#Rate limits

#Error codes