Public API

Polaris exposes a minimal public API for trusted server-side integrations. The first version focuses on safe, workspace-scoped reads and a chat endpoint without streaming, using API keys, scopes and request auditing.

Authentication

Create an API key from Workspace Settings, then send it as a Bearer token.

curl -H "Authorization: Bearer plr_live_..." \
  https://api.polarisai.mx/api/public/v1/me

Polaris only shows the complete key once. Store it in a secure server environment and revoke it when it is no longer needed. Do not ship API keys in browser code or mobile clients.

Response format

Successful responses include data, a request_id and API metadata.

{
  "data": [],
  "request_id": "req_123",
  "meta": {
    "workspace_id": "workspace_id",
    "api_version": "v1"
  }
}

Errors use a consistent shape and never include stack traces.

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "Missing required scope: chatbots:read",
    "request_id": "req_123"
  }
}

Scopes

Grant only the scopes your integration needs.

The first write endpoint is limited to chatbot messages. Other write scopes are reserved for future API surfaces.

Endpoints

Pagination and filters

List endpoints support limit and page.

curl -H "Authorization: Bearer plr_live_..." \
  "https://api.polarisai.mx/api/public/v1/conversations?limit=20&page=1"

Supported filters:

Examples

List chatbots:

curl -H "Authorization: Bearer plr_live_..." \
  https://api.polarisai.mx/api/public/v1/chatbots

Read usage and limits:

curl -H "Authorization: Bearer plr_live_..." \
  https://api.polarisai.mx/api/public/v1/usage

List messages from a conversation:

curl -H "Authorization: Bearer plr_live_..." \
  https://api.polarisai.mx/api/public/v1/conversations/{conversation_id}/messages

Send a message to a chatbot:

curl -X POST https://api.polarisai.mx/api/public/v1/chatbots/{chatbot_id}/messages \
  -H "Authorization: Bearer plr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"How do I create a chatbot?"}'

Use Idempotency-Key when retrying write requests after a timeout or network failure:

curl -X POST https://api.polarisai.mx/api/public/v1/chatbots/{chatbot_id}/messages \
  -H "Authorization: Bearer plr_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-123" \
  -d '{"message":"How do I create a chatbot?"}'

If the same key and body are sent again, Polaris returns the original response without creating duplicate messages or usage. If the same key is reused with a different body, Polaris returns IDEMPOTENCY_KEY_CONFLICT.

Continue an existing conversation:

curl -X POST https://api.polarisai.mx/api/public/v1/chatbots/{chatbot_id}/messages \
  -H "Authorization: Bearer plr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id":"conversation_id",
    "message":"What should I test before publishing it?",
    "external_user_id":"customer_123",
    "metadata":{"source":"partner_app"}
  }'

Polaris always records API-created conversations as source: public_api. If you send metadata.source, treat it as integration context, such as partner_app or crm_sync. Polaris keeps source=public_api as the canonical attribution for audit, filtering and support.

Conversation source attribution

Conversations created through POST /api/public/v1/chatbots/{chatbot_id}/messages are marked as public_api.

Polaris stores the API key prefix and optional external_user_id for audit and support visibility. The raw API key is never stored.

When you list conversations, the source field helps distinguish API traffic from widget, support, WhatsApp and dashboard conversations.

Chat responses include the assistant answer, safe citations and usage metadata.

{
  "data": {
    "conversation_id": "conversation_id",
    "message_id": "message_id",
    "answer": "Start by creating the chatbot in the correct workspace...",
    "citations": [
      {
        "document_id": "document_id",
        "title": "Create a chatbot",
        "datasource_name": "Polaris Docs",
        "excerpt": "Create the chatbot inside the correct workspace...",
        "score": 0.82,
        "rank": 1
      }
    ],
    "usage": {
      "ai_messages_incremented": true
    }
  },
  "request_id": "req_123",
  "meta": {
    "workspace_id": "workspace_id",
    "api_version": "v1"
  }
}

The chat endpoint does not support streaming yet. It does not expose raw prompts, internal tools, embeddings or full document chunks.

Security notes

• API keys are workspace-scoped.
• Revoked or expired keys stop authenticating immediately.
• Internal prompts, tools, document chunks and system logs are not exposed.
• Chat requests respect the workspace AI message limits and grace/blocked policies.
• Public API writes support Idempotency-Key to make client retries safe.
• Rate limits protect the API from traffic spikes and abuse. Plan limits still control commercial usage and consumption.
• Rate limited responses return RATE_LIMIT_EXCEEDED with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
• Use API keys only from trusted server environments, never from public browser code.
• Every authenticated request is audited with request ID, key prefix, scope, endpoint and status code.