DocsDevelopersCustom API

Custom API

Connect Alpheris directly to your own systems: programmatic access to your inbox, tickets, leads and customers through an HTTP API with API-key authentication. Available on the Business and Enterprise plans.

What is the Custom API for?

Most merchants get by without any code at all: embed the widget, let it crawl your domain, run the inbox from the dashboard. The Custom API is meant for the cases where you want to integrate Alpheris into your own software:

Mirror conversations and tickets into your existing CRM or helpdesk.
Reply to a thread from your own backend.
Write captured leads automatically into your sales pipeline.
Check a workspace's shop/plan context server-side.

The API speaks JSON, runs over your regular Alpheris domain and uses the same data store as the dashboard.

Plan requirement: API keys are only active on the Business and Enterprise plans. On Free, Trial and Basic, the endpoints return status 402 plan required in API-key mode. Details under Plans & Billing.

Basics

Item	Value
Base URL	`https://console.alpheris.com` or your own address (Enterprise)
Format	JSON over HTTPS (`Content-Type: application/json`)
Auth	`Authorization: Bearer <API_KEY>` or `X-API-Key: <API_KEY>`
Key format	starts with `sb_live_…`
Plan	Business & Enterprise

Each key is permanently bound to exactly one workspace (shop). There are no cross-account keys — a request only ever sees the data of the workspace the key belongs to.

Create an API key

You manage API keys in the dashboard. A detailed guide including all endpoints and error codes can be found in the API Reference.

Open the dashboard

In the Console, go to API Keys (/dashboard/api-keys). The section is unlocked on Business/Enterprise.

Generate a key

Give it a descriptive name (e.g. Backend-Prod) and create the key. It starts with sb_live_.

Copy it immediately

The full key is shown only once, when it is created — after that it is only visible masked. Store it securely right away.

Store it server-side

Store the key as an environment variable in your backend. Never ship it in the browser frontend or in client code.

bash

# Store the key server-side as an ENV variable
export ALPHERIS_API_KEY="sb_live_xxxxxxxxxxxxxxxxxxxxxxxx"
export ALPHERIS_BASE_URL="https://console.alpheris.com"

Test authentication

First check with GET /api/me whether the key, workspace and plan are correct. Only after that should you call business endpoints.

bash

curl -sS "$ALPHERIS_BASE_URL/api/me" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

python

import os, requests

base_url = os.environ["ALPHERIS_BASE_URL"]
api_key  = os.environ["ALPHERIS_API_KEY"]

r = requests.get(
    f"{base_url}/api/me",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
print(r.status_code, r.json())

Key endpoints

The inbox endpoints accept both the dashboard session and an API key — ideal for your own CRM and ops flows. The full list with all parameters is in the API Reference.

Endpoint	Method	Purpose
`/api/me`	GET	Check auth, workspace and plan context
`/api/inbox/threads`	GET	Load conversations
`/api/inbox/threads/{conversation_id}/reply`	POST	Send a reply into an existing thread
`/api/inbox/tickets`	GET / POST	Read or create tickets
`/api/inbox/leads`	GET / POST	Read or create leads
`/api/inbox/customers`	GET / POST	Read or create customer records

Example: send a reply into a thread

Always send a unique client_msg_id along with each send. That way Alpheris recognizes retries (for example after a timeout) as the same operation and does not create a duplicate message.

bash

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/threads/abc123/reply" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hi, we will get back to you directly.",
    "client_msg_id": "reply-2026-06-18-001"
  }'

Optional control endpoints

The API also lets you control individual chatbot and Shopify features server-side. These endpoints accept an API key or a session as well:

Endpoint	Method	Purpose
`/api/chatbot/settings`	GET / POST	Read & set chatbot/e-commerce switches (e.g. Shopify store on/off, order tracking, address-change mode)
`/api/chatbot/menu/regenerate`	POST	Regenerate the chatbot's menu buttons from the crawl
`/api/integrations/shopify/order-lookup`	POST	Look up order status & tracking by order number + email
`/api/integrations/shopify/resync-catalog`	POST	Re-sync the product catalog from Shopify
`/api/integrations/health`	GET	Check the workspace's integration and configuration status

bash

curl -sS -X POST "$ALPHERIS_BASE_URL/api/chatbot/settings" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shopify_store_enabled": true,
    "shopify_chat_order_tracking_enabled": true
  }'

Error codes

Status	Meaning	Action
`401`	Key missing or invalid	Check the header and the active key
`402`	Plan gate active (`plan required`)	Activate Business or Enterprise
`403`	Workspace inactive or permission missing	Check workspace status / permissions
`5xx`	Temporary server error	Retry with backoff and the same `client_msg_id`

On 401 or 402, never retry blindly — fix the auth or plan first. A retry with backoff (e.g. 2 s, 5 s, 15 s) only makes sense for 5xx/network errors.

Best practices

Use keys server-side only, never in the frontend or in public code.
One key per integration with a descriptive name — that way you can rotate or revoke individual keys precisely.
Key rotation: plan for it regularly and revoke unused keys in the dashboard.
Idempotency: send a unique client_msg_id with every send request.
/api/me first, then the rest: this cleanly separates auth/plan issues from business errors.

Data protection: All processing runs within the EU (hosting in Germany). For your own integrations involving personal data, the data processing agreement applies, available at alpheris.com/avv.