Skip to main content

AI API Overview

Looking for the product view?
The Help Center explains this surface as users see it: AI Features.

The Informer AI API provides endpoints for AI-powered conversations, models, providers, and per-user credit budgets. All routes are prefixed with /api.

Billing and governance — credit pools, usage profiles, entity budgets, and subscriptions — are covered in Usage & Credits and Subscriptions.

Features​

  • Chats - Create and manage AI conversations with streaming responses
  • Messages - Access and manipulate chat message history
  • Memories - Store and search conversation context using vector embeddings
  • Models - Configure AI models from multiple providers
  • Providers - Manage AI service provider credentials
  • AI Budget - The authenticated user's credit budget and usage profile status
  • Admin - License Manager sync and entitlement maintenance

Authentication​

All AI API endpoints require authentication via session cookies or API tokens. AI-specific endpoints additionally verify the caller's AI entitlement.

Common Authorization Patterns​

  • User endpoints - Require AI access (verified by the ai.verify pre-block: AI enabled on the tenant and an ai credential for the user)
  • Metered endpoints - Run the credit enforcer before processing; consume credits subject to the caller's usage profile (skipped under BYOK)
  • Admin endpoints - Require permission.ai.manage or permission.tenant.superuser
  • Billing endpoints - Require permission.billing.manage (see Usage and Subscriptions)

Credits & enforcement​

Metered AI activity (chat, direct model invocation, image generation, embeddings) consumes credits from the tenant's credit pool. Before a metered request runs, the enforcer evaluates entitlement, the caller's usage-profile model-tier access, their monthly credit cap, any entity budget, and the pool balance. The first failing check returns 402 Payment Required with a machine-readable code. See the enforcement flow for the full order and codes.

When the tenant supplies its own provider keys (BYOK), AI calls do not draw from the pool — only tier and entitlement checks apply.

Streaming Responses​

Several endpoints return Server-Sent Events (SSE) streams:

  • POST /api/chats/{id} - Chat message stream
  • POST /api/models/{id}/_chat - Direct model chat stream
  • POST /api/models/{id}/_completion - Text completion stream
  • POST /api/chats/{id}/messages/{messageId}/_explain - Message explanation stream

SSE responses use Content-Type: text/event-stream and support abort signals for cancellation. Each event is an id: line and a data: line carrying one JSON chunk, with CRLF line endings. A client reading the stream should also expect:

  • Keepalive comments. Every 15 seconds for as long as the stream is open, the server writes a comment line (: keepalive) so that proxies don't close the connection while the model is thinking or a tool is running. Comment lines carry no data; standard SSE parsers skip them, and a hand-written parser should skip any line that starts with :.
  • Errors inside the stream. Once streaming has started, a failure arrives as a final error event ({"type":"error","errorText":"..."}) and the stream then ends normally. It is never an HTTP error status, because the 200 has already been sent.
  • No proxy buffering. Responses carry Cache-Control: no-cache, no-transform and X-Accel-Buffering: no, so reverse proxies such as nginx pass each chunk through as it arrives.

POST /api/models/{id}/_object is the exception: it returns a plain JSON body. See Choosing an endpoint for the trade-off it makes.

Error Responses​

Standard HTTP status codes:

  • 200 - Success
  • 400 - Bad request (validation error)
  • 402 - Payment required (a credit cap, entity budget, or the credit pool was exhausted — see the code field)
  • 403 - Forbidden (insufficient permissions or AI not enabled for the user)
  • 404 - Resource not found
  • 500 - Internal server error

A credit-enforcement denial looks like:

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Monthly credit limit reached",
  "code": "CREDIT_LIMIT",
  "profileRemaining": 0,
  "poolRemaining": 37660
}

Next Steps​

Explore the specific endpoint categories:

Related sections: