Skip to main content

AI API Overview

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.

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:

  • Chats - Conversation management
  • Messages - Message operations
  • Memories - Context storage and retrieval
  • Models - AI model configuration
  • Providers - Provider management
  • AI Budget - Per-user credit budget status
  • Admin - License Manager sync and maintenance

Related sections: