API reference

The API gives a trusted backend access to a project's funnels, experiments, funnel users, subscriptions, Stripe transactions and lifecycle email. Every request is server-to-server. Never call it from a browser, a published funnel or a mobile app.

https://sdk-api.funnelsgrove.com/integration/v1

Paths on the resource pages are relative to this base URL.

For the client-side API that runs a published funnel with a publishable key, see the Funnel SDK.

Authentication

Two credentials open the same API. Choose by how much a caller should reach.

	Project secret key	API key
Reaches	Everything in one project	The scopes and projects you grant
Created in	Project Settings	Organization Settings → API Keys
Looks like	the project's SDK secret key	fg_key_…
projectId	Optional; read and subscription endpoints return 403 for another project	Required on every request except GET /projects
Revocation	Rotating the key stops the old key immediately	A revoked key can keep working for up to one minute

Project secret key

Projects created before API keys have an SDK secret key in Project Settings. It authorizes every endpoint of its project and also signs their project webhooks. Rotating it stops the old key immediately and rotates webhook signing. Newer projects have no visible secret key: use API keys.

API keys

Workspace owners and admins create API keys in Organization Settings → API Keys → Create key and choose:

1. Permissions: No access, Read or Write for each area of the scopes below. Read starts on; Write is opt-in and includes Read.
2. Name, description and projects: who uses the key and why, and All projects (including projects created later) or a fixed list.

The key value is shown once. Store it in your backend secrets. Keys cannot be edited: to change projects or permissions, create a new key and revoke the old one. Use an API key when a partner or an internal service should reach several projects, or less than a whole project.

Headers

Send either credential in one of these headers. Use one header consistently.

Authorization: Bearer <key>

X-SDK-Secret-Key: <key>

POST /subscriptions/:subscriptionId/cancel and /renew read the key from X-SDK-Secret-Key only.

With an API key, name the project with a projectId query parameter on every request except GET /projects:

curl "https://sdk-api.funnelsgrove.com/integration/v1/funnels?projectId=<project-id>" \
  -H "Authorization: Bearer <api-key>"

Scopes

An API key reaches only the endpoints of its scopes and only projects within its Project Access. The project secret key needs no scopes.

Scope	Endpoints
—	GET /projects
funnels:read	GET /funnels
experiments:read	GET /experiments
funnel_users:read	GET /funnel-users, GET /funnel-users/list
subscriptions:read	GET /subscriptions/list
subscriptions:write	POST /subscriptions/:subscriptionId/cancel, POST /subscriptions/:subscriptionId/renew
transactions:read	POST /transactions/search
email_templates:read	GET /email/templates, GET /email/templates/:templateId, POST /email/templates/:templateId/validate, POST /email/templates/:templateId/preview
email_templates:write	POST /email/templates, PATCH /email/templates/:templateId, POST /email/templates/:templateId/test-send, POST /email/templates/:templateId/publish
email_sequences:read	GET /email/sequences, GET /email/sequences/:sequenceId, POST /email/sequences/:sequenceId/validate
email_sequences:write	POST /email/sequences, PATCH /email/sequences/:sequenceId, POST /email/sequences/:sequenceId/steps, POST /email/sequences/:sequenceId/publish, /enable, /disable, POST /email/sequences/:sequenceId/enrollments/:funnelEndUserId/cancel
email_deliveries:read	GET /email/deliveries/:deliveryId
email_deliveries:write	POST /email/deliveries, PATCH /email/deliveries/:deliveryId/variables

Errors

Errors return a JSON body with an error message. Resource pages list the statuses specific to each endpoint; these apply everywhere.

Status	Meaning
400	The request is invalid, or an API key request is missing projectId.
401	The key is missing, unknown or revoked.
403	The API key lacks the endpoint's scope, or the project is outside its Project Access.
429	More than 120 requests per minute from one IP address. Wait for Retry-After.

Resources

Resource	Use it to
Projects	List the projects a key can use.
Funnels	List a project's funnels and their production URLs.
Experiments	List experiments, variants and traffic splits.
Funnel users	Read one funnel user, page through a funnel, or sync a project incrementally.
Subscriptions	List funnel subscriptions; cancel at period end or remove a scheduled cancellation.
Transactions	Search Stripe payment evidence.
Email templates	Author, validate, preview and publish templates.
Email sequences	Author, publish, enable and disable lifecycle sequences.
Email deliveries	Send a published template, read its status, personalize before sending.