# Survey API & MCP


# Survey API & MCP

imatic Survey connects to the rest of your stack — pushing responses to your own systems, automating form work, and letting AI agents work with your forms. This page covers the developer surface: API keys, webhooks, the REST API, the MCP server, and email delivery. These features are live today.

![The integrations and developer settings area](/img/screenshots/survey/integrations.png)
*The developer area is where you manage API keys, webhooks, and integrations.*

## API keys

API keys authenticate your own apps and scripts against the Survey **REST API**. Create and manage them under **/developers/api-keys**, where you can issue a key, give it a name, see its usage stats, and revoke it if it's ever exposed.

A key is shown in full only once, at creation — copy it then and store it somewhere safe. After that you'll see only its prefix in the list, alongside its name, scopes, and last-used time.

The API is hosted at `https://surveyapi.imatic.ai`, and keys are `sk_`-prefixed. Send your key as a Bearer token. Endpoints are custom-verb POST requests — for example, to list your forms:

```bash
curl -X POST https://surveyapi.imatic.ai/forms/list \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

:::tip[Keep keys secret]

Treat an API key like a password. Don't commit it to source control, and rotate it if you suspect it has leaked.

:::

## Webhooks

Webhooks push events to a URL you control, so your systems react the moment something happens instead of polling for changes. Configure them under **/developers/webhooks**.

Available events:

- **`response.created`** — fires when a new response is submitted.
- **`response.flagged`** *(planned — not yet emitted)* — when a response is flagged (for example, by fraud or spam checks).
- **`response.updated`** *(planned — not yet emitted)* — when a response is updated or moderated.
- **`form.published`** *(planned — not yet emitted)* — when a form is published.
- **`form.closed`** *(planned — not yet emitted)* — when a form is closed.

Each delivery is signed with an **HMAC-SHA256** signature (sent in the `X-Signature` header, alongside `X-Timestamp`, `X-Event-Id`, and `X-Event-Type`) so your endpoint can verify the request genuinely came from imatic Survey and wasn't tampered with in transit. Failed deliveries are **retried** with exponential backoff before being marked failed.

## REST API

The **REST API** lets you manage forms and responses programmatically. Endpoints use custom-verb POST requests rather than a versioned path prefix — for example, `POST /forms/list` (list forms), `POST /forms/get-for-edit` (read a form's schema), `POST /forms/generate` (generate a form with AI), `POST /forms/duplicate`, and `POST /forms/delete`. It's hosted at `https://surveyapi.imatic.ai` and authenticated with an [API key](#api-keys) — an `sk_`-prefixed Bearer token.

## MCP server for AI agents

The **MCP server** exposes Survey to AI agents through the Model Context Protocol, so an assistant can work with your forms and responses on your behalf. It speaks **JSON-RPC 2.0** over `POST /mcp` and is authenticated with your portal **JWT** (sent as a Bearer token), which scopes every call to your organization.

It ships with **10 tools**:

- **`whoami`** — return the authenticated organization context.
- **`list_forms`** — list your published forms.
- **`get_form`** — read a form's schema and fields.
- **`submit_response`** — submit a response to a form.
- **`list_responses`** — list responses (paginated).
- **`get_response`** — read a single response.
- **`get_response_stats`** — read aggregated response statistics.
- **`create_poll`** — create and publish a single-question poll.
- **`cast_vote`** — cast a vote on a poll.
- **`live_poll_results`** — read live poll tallies.

:::info[Two different credentials]

The **MCP server and webhooks** use your portal **JWT** (org-scoped). The **REST API** uses an **API key** you create under /developers/api-keys. Pick the right credential for the surface you're calling.

:::

## Email delivery

Email delivery (for example, response notifications) is configured under **/settings** on the email-delivery tab. You can connect any of **six providers**:

- **Gmail**
- **Resend**
- **SendGrid**
- **Postmark**
- **Amazon SES**
- **Custom SMTP**

## Next steps

- [Publish and share a form](./publishing-sharing)
- [View responses](./responses)
- [Open analytics](./analytics)
- [Generate a form with AI](./ai-generation)