API Documentation

Integrate structured thinking into your applications. All endpoints require JWT authentication.

Authentication

Include your JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Or pass it as a cookie named iva_token.

Endpoints

POST /api/think

Send input through a thinking mode and receive structured output.

Request Body

Parameter	Type	Required	Description
input	string	Yes	Your thinking input
mode	string	No	QUESTION, REVIEW, PLAN, DIAGNOSIS, DECISION, SYSTEM_DESIGN, STRATEGY (default: QUESTION)
session_id	int	No	Existing session ID to continue
use_context	bool	No	Include previous messages as context

Example Request

{
  "input": "Should we migrate from REST to GraphQL?",
  "mode": "DECISION",
  "use_context": true
}

Response

{
  "response": "Analysis of the decision...",
  "session_id": 42,
  "mode": "DECISION",
  "provider": "gemini",
  "usage": {
    "used": 1,
    "limit": 100,
    "remaining": 99,
    "tier": "pro"
  }
}

Error Responses

Status	Meaning
400	Missing or invalid input
401	Authentication required
429	Daily rate limit reached
500	LLM provider error

GET /api/sessions

List all thinking sessions for the authenticated user.

Response

[
  {
    "id": 42,
    "title": "Should we migrate to GraphQL?",
    "mode": "DECISION",
    "created_at": "2026-07-25T10:30:00+00:00",
    "updated_at": "2026-07-25T10:30:00+00:00"
  }
]

DELETE /api/session/{id}

Delete a thinking session and all its messages.

GET /api/status

Get current user status, usage, and available providers.

Response

{
  "user": {
    "name": "Navigator",
    "email": "nav@xmbot.ai",
    "tier": "pro"
  },
  "provider": "gemini",
  "providers": [
    {"name": "gemini", "cost_tier": 0.1, "quality": 0.9, "speed": 0.85}
  ],
  "usage": {
    "used": 5,
    "limit": 100,
    "remaining": 95,
    "tier": "pro"
  },
  "modes": ["QUESTION", "REVIEW", "PLAN", "DIAGNOSIS", "DECISION", "SYSTEM_DESIGN", "STRATEGY"]
}

Settings API

POST /api/settings/prompt

Save a custom system prompt for a thinking mode.

{
  "mode": "QUESTION",
  "prompt": "You are a domain expert in finance. Answer questions about financial markets with precision..."
}

DELETE /api/settings/prompt/{mode}

Reset a mode's prompt to the built-in default.

POST /api/settings/memory

Store an encrypted memory entry.

{
  "key": "project-preferences",
  "content": "Always use TypeScript, prefer Vitest over Jest",
  "category": "project"
}

GET /api/settings/memory/{key}/retrieve

Decrypt and retrieve a memory entry.

DELETE /api/settings/memory/{key}

Delete a memory entry.

GET /api/settings/memory/search?q={query}

Search memory keys by name.

GET /api/settings/memory/export

Export all memories as decrypted JSON.

Rate Limits

Tier	Limit	Period
Free	3 sessions	Per day
Pro	100 sessions	Per day
Enterprise	1000 sessions	Per day

Rate limit headers: When a request is rate-limited (429), the response includes usage details in the JSON body.

SDKs & Libraries

Install the Python package:

pip install ivacortex

Use programmatically:

from ivacortex.core.cortex import IVACortex

cortex = IVACortex(provider="gemini")
response = cortex.think("QUESTION", "What is microservices architecture?")
print(response)