> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/api-and-webhooks/getting-started.md). # Getting started with the API The BAI Analytics API does one job well: it moves feedback between your systems and your Feedback Groups. You push feedback in, the platform analyses it exactly as if it had arrived through a survey or upload, and you read the results back (or let a webhook tell you when they're ready). Everything runs over HTTPS against: ``` https://app.boundary-ai.com ``` This walkthrough goes from nothing to analysed feedback. It uses the recommended vocabulary (`feedback_group` / `source` / `field`); see [Concepts & naming](/boundaryai-docs/api-and-webhooks/concepts-and-naming.md) for how that maps to what you see in the app. *** ### Step 1: Create an API key In the dashboard, open the **Integrations Hub** and go to **API Keys** (admin-only). Create a key, pick a permission scope, and copy the secret. It looks like `inpk_live_...` and is shown once. Pass it on every call: ``` Authorization: Bearer inpk_live_... ``` Verify it works: ```bash curl https://app.boundary-ai.com/api/input/me \ -H "Authorization: Bearer $BAI_API_KEY" ``` `GET /me` returns your key's permissions, rate limits, credit status, and the webhook events you can subscribe to. Details in [Authentication & API keys](/boundaryai-docs/api-and-webhooks/authentication.md). ### Step 2: Create a feedback group and a source A **feedback group** is the project container; a **source** is one stream of feedback inside it, with typed **fields**. ```bash curl -X POST https://app.boundary-ai.com/api/input/feedback_groups/create \ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \ -d '{"name": "Customer Support EU"}' curl -X POST https://app.boundary-ai.com/api/input/sources/create \ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \ -d '{ "feedback_group_id": "1842", "source_title": "Support tickets (CRM sync)", "feedback_type": "support_ticket", "fields": [ {"field_title": "What was the issue?", "field_type": "DEPTH_TEXT"}, {"field_title": "How likely are you to recommend us?", "field_type": "NPS"} ] }' ``` Sources are created in draft mode. Publish to start pushing: ```bash curl -X POST https://app.boundary-ai.com/api/input/sources/publish \ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \ -d '{"source_id": 9021, "feedback_group_id": 1842}' ``` ### Step 3: Push feedback ```bash curl -X POST https://app.boundary-ai.com/api/input/feedback/push \ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: 2c1f7c9e-batch-0712" \ -d '{ "feedback_group_id": "1842", "source_id": "9021", "field": { "field_id": "31245", "content": [ "The new dashboard is great, but exports are slow.", {"text": "Support resolved my issue in one call.", "external_id": "ticket-58121", "rating": 5, "occurred_at": "2026-07-12T09:30:00Z"} ] } }' ``` Items can be bare strings or structured objects. Three fields are worth using from day one: * **`external_id`**: your stable ID for the item. Retried pushes with the same `external_id` never double-write; the response reports them as `skipped_duplicates`. * **`occurred_at`**: when the feedback actually happened. It back-dates the item so time-tracked groups put it in the right period. * **`Idempotency-Key`** header: makes the whole request safe to retry for 24 hours. For backfills, use `POST /feedback/push/bulk` (async, returns a `task_id` and a status URL) or `POST /feedback/upload` with a CSV/XLSX file. ### Step 4: Read the analysis (or let a webhook tell you) Analysis runs automatically after content lands. Read it back: ```bash curl https://app.boundary-ai.com/api/input/sources/9021/analysis \ -H "Authorization: Bearer $BAI_API_KEY" ``` You get the sentiment distribution, themes, and Custom Monitoring matches. Rather than polling, subscribe to the `analysis.completed` event; see [Webhooks](/boundaryai-docs/api-and-webhooks/webhooks.md). *** ### Conventions to know * **Success envelope**: every 2xx response wraps its payload as `{"data": {...}}`. * **Error envelope**: failures return `{"error": {"code": "...", "message": "..."}}` with a stable machine-readable `code`. * **Rate limits**: 60 requests/minute per key and 1,000/minute per organisation by default; 429 responses carry a `Retry-After` header. Your key's exact limits are in `GET /me`. * **Pagination**: list endpoints are cursor-based; pass back `next_cursor` until `has_more` is false. * **Test keys**: `inpk_test_...` keys behave identically but are meant for staging integrations; keep them out of production traffic. {% hint style="success" %} Anything you push participates fully in the product: group monitors with auto-coverage watch API sources automatically ([Custom Monitoring](/boundaryai-docs/analysing-your-feedback/custom-monitoring.md)), and API data lands in Grouped Themes, Evolution periods, and reports like any other source. {% endhint %} *** ### Going deeper * [Pushing feedback](/boundaryai-docs/api-and-webhooks/pushing-feedback.md): bulk backfills, file ingest, deduplication, back-dating, erasure. * [Sending invites (email API)](/boundaryai-docs/api-and-webhooks/sending-invites.md): trigger personalized survey invites from your own workflow. * [Webhooks](/boundaryai-docs/api-and-webhooks/webhooks.md): act on events instead of polling. * [Connect AI assistants (MCP)](/boundaryai-docs/api-and-webhooks/mcp.md): let an assistant query the results. ### What's deliberately not in the API Some things are dashboard-only on purpose, so if you're hunting for an endpoint that doesn't exist, this is probably why: * **Survey and template building**: what respondents and invitees see is designed, previewed, and reviewed in the platform; the API triggers it but can't rewrite it. A leaked key can never change what your customers receive. * **Webhook subscription management**: creating subscriptions and reading signing secrets happens in the Integrations Hub, so an API key can't redirect your event stream to a new URL. * **Email sending configuration**: sender domains and sending tiers are organisation settings ([Settings](/boundaryai-docs/account-and-administration/updating-settings.md#email-sending)); the API sends *through* them but can't alter them. * **Members, billing, plan management**: admin actions stay with admins. If your use case genuinely needs one of these programmatically, tell us at ; we'd rather hear the case than have you build around it.