Developer reference

Aivastark has one REST API, for support tickets, plus signed webhooks, a configurable website widget, server-side Visitor Lenz endpoints and two ways for the agent to call your own systems. There is no general REST API for querying the agent, adding knowledge or reading conversations.

Ticket API

A REST API for support tickets, available from the Starter plan. Use it to open tickets from your own forms or apps, sync them with another system, or post replies.

• Base URL: https://xckrihmmdwddvcwohvaz.supabase.co/functions/v1/tickets-public-api
• Authentication: Authorization: Bearer ask_live_…
• Create a key in the dashboard under Tickets → Settings → API keys. It is shown once; Aivastark stores only a hash of it. Each key belongs to one project and can be revoked at any time.

Endpoints

Ticket object

id, number, subject, description, status, priority, type, category, channel, tags, requester { name, email }, assignee_name, created_by_ai, sla { first_response_due_at, resolution_due_at, first_response_at, breached_at }, csat_score, external_refs, custom_fields, created_at, updated_at, resolved_at

Example: create a ticket

curl -X POST "https://xckrihmmdwddvcwohvaz.supabase.co/functions/v1/tickets-public-api/tickets" \
  -H "Authorization: Bearer $AIVASTARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Order 1182 arrived damaged","requester_email":"ada@example.com","priority":"high"}'

Errors

• 400 invalid_json, invalid_request
• 401 unauthorized
• 402 plan_upgrade_required (writes need Starter or above; reads keep working)
• 403 insufficient_scope
• 404 not_found
• 405 method_not_allowed
• 500 internal_error, query_failed

• Errors return { "error": "<code>", "message": "…" }.
• Creating a ticket with the same requester email and subject as an open ticket from the last 24 hours adds a comment to that ticket instead, and returns deduplicated: true.
• When listing with updated_since, more than `limit` changes between two polls can be missed. Poll with limit=200, and often enough that fewer than 200 tickets change in between.
• No rate limits are published.

Webhooks

Website widget

Add the widget to any page with two script tags:

<script>
  window.AivastarkConfig = { key: "YOUR_WIDGET_KEY" };
</script>
<script src="https://www.aivastark.com/widget.js" async></script>

Configuration keys:

• key: your widget key (required).
• user, or getUser(): the signed-in visitor as { id, name, email, plan, company, traits, signature }. id is required.
• userToken, or getUserToken(): the visitor's own auth token, forwarded only to MCP servers you set to act on the visitor's behalf.
• shop: the Shopify store domain, set by the Shopify app embed.

Verified visitor identity

window.AivastarkConfig = {
  key: "YOUR_WIDGET_KEY",
  user: {
    id: "user_123",
    email: "ada@example.com",
    // hex HMAC-SHA256 of the id, computed on your server
    signature: "<64 hex characters>",
  },
};

Visitor identity: compute signature = hex(HMAC-SHA256(signing secret, user id)) on your server, never in the browser. The signing secret is under Integrations → Logged-in visitors → User Identity, with snippets for common auth providers. A visitor with a missing or wrong signature is treated as unverified, not rejected. Listed on the Growth plan.

• The widget has no JavaScript method API (open, close or send).
• Configure it with window.AivastarkConfig before the script loads; data- attributes are not read.

Visitor Lenz server endpoints

Server-to-server calls that enrich Visitor Lenz. Sign requests on your server, never in the browser.

• POST https://www.aivastark.com/api/v1/identify. Auth: key (widget key) and signature over userId. userId, name, email, plan, company, traits. Updates a visitor already seen in the browser.
• POST https://www.aivastark.com/api/v1/revenue. Auth: key and signature over orderId. orderId, amount, currency, email, userId, provider (stripe, shopify, lemonsqueezy, paddle, polar, manual), status (paid or refunded), occurredAt.
• POST https://www.aivastark.com/api/v1/ai-crawl. Auth: t: your server ingest token. { t, ua, path }, or { t, hits: [{ ua, path, ts }] } with up to 500 hits. Reports AI crawler visits your server saw.

Let the agent call your systems

Install options

• Any website: the two script tags above.
• WordPress: the official plugin, or the shortcode [aivastark key="…"].
• Shopify: the official app's App Embed.
• Google Tag Manager: a tag template.
• Next.js: the snippet with next/script, from the dashboard.
• GitHub (Starter): a one-click pull request that adds the snippet to a Next.js or React app.

Not available

• A general REST API to query the agent, add knowledge sources, read conversations or manage widgets.
• JavaScript methods to open, close or message the widget.
• A React component or SDK package; use the snippet.
• Published rate limits.

Need something that isn't here? Email support@aivastark.com.