# Widget API overview

```
/api/v1/{organisation}/widgets/{widget}/…
```

`{widget}` is the widget's public id. The key you paste into the embed snippet looks like `{organisation}/{widget}`. That public key is safe to put in the browser; it is not a secret.

## Endpoints

| Method | Path | Purpose | Uses answers |
|---|---|---|---|
| `GET` | `/config` | Appearance and behaviour settings | No |
| `POST` | `/search` | Search your content | No |
| `POST` | `/chat` | AI answer (optional streaming) | Yes |
| `POST` | `/summarize` | Short AI summary of top results | Yes |
| `POST` | `/events` | Feedback and click analytics | No |
| `*` | `/conversations…` | History for signed-in visitors | No |

See [Authentication](/docs/authentication) for domain, secret key, and API key rules.

## Config

```
GET /widgets/{widget}/config
```

Responses may be cached for up to five minutes.

```json
{
  "type": "chatbot",
  "name": "Help",
  "variant": "bubble",
  "accent_light": "#18181b",
  "accent_dark": "#fafafa",
  "theme": "auto",
  "branding": true,
  "summary": false,
  "speech_input": false,
  "placeholder": "",
  "greeting": "",
  "prompts": [],
  "avatar": null,
  "debounce": 1000,
  "default_language": "en"
}
```

`prompts` is chat-only: short suggested questions (max 6) rendered as chips on an empty thread.

`branding` reflects your plan. On plans that show the Datalumo badge, clients cannot turn it off by ignoring this field.

## Session ids

Search and chat accept an optional `session_id`. If you omit it, Datalumo creates one and returns it. Reuse the same id from search through clicks and chat so analytics stay connected for that visit.

## When to use the embed instead

The official embed already handles streaming, conversation storage, visitor identity, and falling back to search when answers run out. Prefer it in the browser — see the [Widget SDK](/docs/sdk) for install steps, mount options, headless mode, and the analytics beacon. Call these endpoints directly when you build a custom client or need server-side access.