Skip to main content

API Reference

This section provides detailed information about the ZeroinAI Chat Service API endpoints, request/response formats, and error handling.

Core Workflow​

Here's a typical flow for integrating the chat service:

  1. (Optional) Retrieve Chat Configuration Details:

    • You can fetch your chat configuration (branding, welcome messages, etc.) if you need to display or use these details on your client-side.
    • Endpoint: GET /chat-config/

  2. Create a New Chat Session:

    • When a user starts a new conversation, create a chat session. You'll need to specify an initial token_limit for this chat. This limit controls how many interactions (and associated costs) are allowed for this specific chat session.
    • Endpoint: POST /chats/
    • You'll receive a chat_id in the response, which you must use for all subsequent interactions within this session.

  3. Send a Message and Get an AI Response:

    • The user sends a message. You'll post this message to the API, providing the chat_id and the message content.
    • The API will save the user's message, process it, generate an AI response, save the AI's message, and update token usage.
    • Endpoint: POST /chats/messages/
    • The response will be the AI's message.

  4. Retrieve Chat History (Messages):

    • To display the conversation history to the user, you can fetch all messages for a given chat_id. Pagination is supported.
    • Endpoint: GET /chats/{chat_id}/messages/

  5. (Optional) Add More Tokens to a Chat:

    • If a chat session is about to exceed its token_limit, or if you want to allow for a longer conversation, you can add more tokens.
    • Endpoint: PUT /chats/{chat_id}/tokens/

  6. (Optional) List All Chat Sessions for Your Configuration:

    • To get an overview of all active chat sessions initiated under your API key (your configuration).
    • Endpoint: GET /chats/by-config-id

  7. (Optional) Delete a Chat Session:

    • If a user explicitly ends a chat or if it's no longer needed, you can mark it as deleted. This doesn't physically remove the data but flags it.
    • Endpoint: DELETE /chats/{chat_id}

Available Endpoints​

Error Handling​

  • 400 Bad Request: The request was malformed (e.g., missing required fields in the JSON body, invalid JSON). The response body may contain more details.
  • 401 Unauthorized: The X-API-Key header is missing, invalid, or the key does not have permission for the requested resource.
  • 402 Payment Required: Specifically used when a chat runs out of tokens.
  • 404 Not Found: The requested resource (e.g., a specific chat ID or config) could not be found.
  • 422 Unprocessable Entity: The request was well-formed but contained semantic errors (e.g., invalid data types for fields, missing required fields).
  • 500 Internal Server Error: An unexpected error occurred on the server. If this persists, please contact support.