---
title: "Aivastark — API Documentation"
description: "Public REST API summary: base URL, authentication, endpoints for knowledge ingestion, querying, conversations, widgets and webhooks, plus rate limits and error format."
canonical: "https://www.aivastark.com/api"
source: "https://www.aivastark.com/api.md"
updated: "2026-08-12"
---

# Aivastark — API Documentation

> Public REST API summary: base URL, authentication, endpoints for knowledge ingestion, querying, conversations, widgets and webhooks, plus rate limits and error format.

Growth and Enterprise plans include REST API access. Starter customers can request access by emailing support@aivastark.com.

- **Base URL:** `https://api.aivastark.com/v1`
- **Authentication:** Project-scoped API key sent as a Bearer token in the `Authorization` header. Generate and rotate keys in the dashboard under Settings → API keys.
- **Content type:** `application/json`

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

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/projects/{project_id}/sources` | Ingest a knowledge source. `type` is one of `url`, `file`, `drive`, `github`, `raw`. |
| `POST` | `/v1/projects/{project_id}/query` | Ask the agent a question. `stream: true` returns Server-Sent Events; otherwise a JSON object with `answer`, `citations` and `confidence`. |
| `GET` | `/v1/projects/{project_id}/conversations` | List conversations. Cursor-paginated via `limit` and `cursor`. |
| `GET` | `/v1/projects/{project_id}/conversations/{conversation_id}` | Fetch a single conversation with its full message history. |
| `POST` | `/v1/projects/{project_id}/widgets` | Create a widget deployment. `PATCH` and `DELETE` on `/widgets/{widget_id}`. |
| `POST` | `/v1/projects/{project_id}/webhooks` | Subscribe to events. |

### Querying the agent

```json
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 containing `answer`,
`citations` and `confidence`.

### Ingesting knowledge

```json
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`.

## Webhooks

Subscribe with `POST /v1/projects/{project_id}/webhooks`. Events:

- `conversation.escalated`
- `lead.captured`
- `knowledge.updated`
- `low_confidence.detected`

Webhook payloads are signed with HMAC-SHA256 of the request body using your `secret`, sent in the `X-Aivastark-Signature` header.

## Rate limits

| Plan | Limit |
|---|---|
| Growth | 60 requests/minute, 10,000/day |
| Enterprise | Custom — typically 600 requests/minute with no daily cap |

Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

## Error format

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

Include `request_id` when contacting support — it traces the exact call.

## Embed SDK

For browser deployments use the embed SDK rather than calling REST directly.
A single script tag works on any HTML page, and an official React component is
available for single-page apps.

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

Full reference: https://www.aivastark.com/api

---

*Aivastark · https://www.aivastark.com · updated 2026-08-12*

This document is machine-readable documentation for AI assistants and search engines. The complete index is at https://www.aivastark.com/llms.txt and the full corpus at https://www.aivastark.com/llms-full.txt. The human-readable version of this page is https://www.aivastark.com/api.

Questions: support@aivastark.com · Security: security@aivastark.com