Zitrabot

Backend Documentation

API Reference

This page focuses on the routes most likely to be used directly by the dashboard, embedded chat clients, and backend integrators. Lower-level route inventories are kept at the bottom as a quick index.

API Conventions

  • Protected owner routes expect `Authorization: Bearer <jwt>`.
  • Some routes can also operate through API key auth because the main auth middleware falls back to `x-api-key`.
  • Most write endpoints accept JSON and return either a resource payload or a top-level `message` plus metadata.

Where To Start

  • If you are building account flows, start with `/auth/*`.
  • If you are creating assistant behavior, start with bots and chat handlers.
  • If you are embedding chat, focus on `POST /api/chat-handlers/:id/chat` and API key validation.

Priority Endpoints

These are the most important route contracts for a developer integrating with Zitrabot.

POST/api/bots

Creates a new bot for the authenticated user and optionally configures external API integrations.

Bearer

Request

  • Common fields: `botName`, `botDescription`, `greeting`, `trainingData`.
  • Optional: `apiIntegration: true` and `apiConfig` for external API tool generation.
  • `apiConfig.endpoints` can contain multiple external endpoints, each with `id`, `name`, `baseUrl`, `authType`, and `endpoint` or `testEndpoint`.

Response

  • `201` returns the created bot payload.
  • When API integration is enabled, the response also includes `toolsInfo` with `multiEndpoint`, `totalEndpoints`, `generated`, `totalToolsCount`, and per-endpoint results.

Common Errors

  • 403 plan bot limit reached
  • 500 creation failure

Notes

  • Bot creation enforces plan-based limits from the payment record before writing anything.
PUT/api/bots/:id

Updates an existing bot, refreshes integration metadata, and can regenerate tool definitions.

Bearer

Request

  • Requires `name` and supports `description`, `trainingData`, `greeting`, `apiIntegration`, and `apiConfig`.
  • If `apiConfig` is present, tool generation is re-run for either single-endpoint or multi-endpoint mode.

Response

  • `200` returns `success`, `message`, `bot`, and `toolsInfo`.
  • The `bot` object includes current integration data, feature assignments, and timestamps.

Common Errors

  • 400 validation failed
  • 400 invalid ID format
  • 404 bot not found
  • 500 update failure
POST/api/chat-handlers/:id/chat

Main public runtime endpoint for browser or widget chat. It creates or resumes a session, evaluates message limits, may hand off to a human agent, and otherwise produces an AI reply.

Public

Request

  • Send `message` and optional `sessionId` as JSON.
  • The route is public by URL, but internal ownership and billing are enforced through the bound chat handler.

Response

  • Standard bot reply returns `reply`, `messageLimit`, `messagesUsed`, `messageCount`, and `sessionId`.
  • If the conversation is handed off, the response can instead return `status: agent_assigned` and `sessionId`.
  • If there is no active subscription, the route returns a fallback assistant message and still persists the conversation.

Common Errors

  • 403 message limit exceeded
  • 400 chat handler inactive
  • 404 chat handler not found
  • 500 processing error
GET/api/user/current

Returns the current authenticated owner profile for dashboard bootstrap.

Bearer

Request

  • No body. Requires bearer token.

Response

  • `200` returns `id`, `fullname`, `email`, `isVerified`, `avatar`, and `firstTimeSignup`.

Common Errors

  • 404 user not found
  • 500 failed to get user information
POST/api/subscription/checkout

Starts the Paystack checkout flow for a selected pricing tier.

Bearer

Request

  • Send `planId` as JSON. Supported values include `lite`, `starter`, `growth`, and `enterprise`.

Response

  • `200` returns `authorizationUrl` and `reference` from Paystack.

Common Errors

  • 400 invalid plan
  • 404 user not found
  • 500 paystack not configured or initialization failed
GET/api/health

Operational health endpoint used for server diagnostics and readiness checks.

Public

Request

  • No request body.

Response

  • `200` returns `status`, `environment`, `timestamp`, `uptime`, memory stats, and Mongo readiness state.

Common Errors

  • 500 only if upstream middleware crashes before the handler

Route Index

This is the broader route map for orientation. Use the pages above for narrative guidance and the cards above for the most important contracts.

/auth

  • POST /auth/register
  • POST /auth/verify
  • POST /auth/resend-verification
  • POST /auth/login
  • GET /auth/logout
  • POST /auth/onboarding/complete
  • POST /auth/forgot-password
  • POST /auth/reset-password
  • GET /auth/google
  • GET /auth/google/callback
  • GET /auth/github
  • GET /auth/github/callback
  • GET /auth/facebook
  • GET /auth/facebook/callback

/agent/auth

  • POST /agent/auth/login
  • GET /agent/auth/logout
  • GET /agent/auth/current
  • POST /agent/auth/change-password

/api/bots

  • GET /api/bots
  • POST /api/bots
  • POST /api/bots/:id/assign-features
  • GET /api/bots/whatsapp-callback
  • GET /api/bots/count
  • GET /api/bots/limits
  • PUT /api/bots/:id
  • DELETE /api/bots/:id
  • POST /api/bots/:id/connect-whatsapp
  • GET /api/bots/instagram-callback
  • POST /api/bots/:id/disconnect-whatsapp
  • GET /api/bots/:id

/api/features

  • GET /api/features
  • POST /api/features
  • PUT /api/features/:id
  • DELETE /api/features/:id

/api/chat-handlers

  • POST /api/chat-handlers/:id/chat
  • GET /api/chat-handlers/agent/chats
  • POST /api/chat-handlers/agent/accept/:sessionId
  • POST /api/chat-handlers/agent/complete/:sessionId
  • POST /api/chat-handlers/agent/status
  • GET /api/chat-handlers
  • POST /api/chat-handlers
  • DELETE /api/chat-handlers/:id
  • PUT /api/chat-handlers/:id

/api/user

  • GET /api/user/current
  • PUT /api/user/profile
  • POST /api/user/avatar
  • GET /api/user/auth/google/status
  • GET /api/user/auth/google/callback
  • GET /api/user/auth/google
  • POST /api/user/auth/google/disconnect

/api/agents

  • GET /api/agents
  • POST /api/agents
  • PUT /api/agents/:id
  • POST /api/agents/:id/reset-password
  • POST /api/agents/:id/assign-bots
  • DELETE /api/agents/:id

/api/subscription

  • GET /api/subscription
  • POST /api/subscription/checkout
  • POST /api/subscription/update-messages
  • GET /api/subscription/verify
  • POST /api/subscription/webhook/paystack

/api/keys

  • GET /api/keys/validate
  • GET /api/keys
  • POST /api/keys
  • DELETE /api/keys/:id

/api

  • POST /api/webhook
  • GET /api/webhook
  • POST /api/instagram
  • GET /api/instagram
  • GET /api/health