API Reference

Aivastark exposes a REST API for everything you can do in the dashboard · and a few things you can't. Every Growth and Enterprise plan includes API access; Starter customers can request access by emailing support@aivastark.com.

Base URL & authentication

All requests go to https://api.aivastark.com/v1. Authenticate with a project-scoped API key in the Authorization header. Generate keys from the dashboard at Settings → API keys.

Authorization: Bearer akv_live_••••••••••••
Content-Type: application/json

Ingest knowledge sources

Push content into a project's knowledge base programmatically. Useful for syncing a CMS, docs pipeline, or product catalog on every change.

POST /v1/projects/{project_id}/sources

{
  "type": "url",
  "url": "https://docs.example.com/getting-started",
  "title": "Getting started",
  "tags": ["docs", "onboarding"]
}

Supported type values: url, file (multipart upload), drive, github, raw (post text directly).

Query the chatbot

Run a query against a project's knowledge base from your own backend - skip the embedded widget when integrating with email, SMS, or a custom UI.

POST /v1/projects/{project_id}/query

{
  "message": "How do I reset my password?",
  "session_id": "sess_abc123",
  "stream": true
}

With stream: true the response is a Server-Sent Events stream of token deltas. Without it, you receive a JSON object with answer, citations, and confidence.

Retrieve conversations

Pull conversation history for analytics, audits, or for replaying into another tool.

GET /v1/projects/{project_id}/conversations?limit=50&cursor=...
GET /v1/projects/{project_id}/conversations/{conversation_id}

Manage widgets

Programmatically create or update a deployment of the embed widget. Useful for agencies onboarding clients or platforms creating tenant instances.

POST /v1/projects/{project_id}/widgets
PATCH /v1/projects/{project_id}/widgets/{widget_id}
DELETE /v1/projects/{project_id}/widgets/{widget_id}

Webhooks

Subscribe to events that matter to your workflow. Webhooks deliver a signed POST request to your URL.

POST /v1/projects/{project_id}/webhooks

{
  "url": "https://your-app.example.com/aivastark/hook",
  "events": [
    "conversation.escalated",
    "lead.captured",
    "knowledge.updated",
    "low_confidence.detected"
  ],
  "secret": "whsec_..."
}

Verify webhook signatures using HMAC-SHA256 of the request body with the secret you provided. The signature is sent in the X-Aivastark-Signature header.

Rate limits

• Growth plan: 60 requests/min, 10,000/day
• Enterprise plan: custom · typically 600/min, no daily cap

Rate-limit headers are returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error format

{
  "error": {
    "code": "invalid_request",
    "message": "source.url is required for type=url",
    "request_id": "req_01HW..."
  }
}

Always include the request_id when contacting support · it lets us trace the exact call in our logs.

Embed SDK

For browser-based deployments, use the embed SDK instead of calling the REST API directly. A single script tag works on any HTML page; an official React component is available for SPAs.

<script src="https://cdn.aivastark.com/widget.js" data-key="YOUR_EMBED_KEY" defer></script>

Get full access

Building something specific? Email support@aivastark.com with a sentence on what you're integrating · we'll provision API keys and put you in touch with an engineer who can help you ship faster.