Skip to main content

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 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:

curl -X POST https://surveyapi.imatic.ai/forms/list \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
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 — 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.
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​