A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Kit API is how an app or AI agent works with a creator's email marketing account: listing and creating subscribers, tagging people, adding them to a sequence or form, and sending a broadcast. Access is granted through an OAuth token or a personal API key, and that credential carries either read or write across the whole account rather than per-resource permissions. Kit can also push events to a webhook when something happens, like a subscriber being tagged or a purchase being made.
How an app or AI agent connects to Kit determines what it can reach. There are a few routes, each governed by the key or token behind it and whether that credential carries read or write access.
The v4 REST API answers at https://api.kit.com/v4. It uses cursor-based paging and returns a consistent error shape, and it replaced the v3 API at api.convertkit.com.
Kit runs a first-party MCP server at https://app.kit.com/mcp that lets an AI client read and act on a creator's account through OAuth, exposing 65+ tools across audience, content, and commerce. A separate developer-docs MCP at https://developers.kit.com/mcp answers questions about the API itself.
Webhooks deliver the chosen events to a receiver URL, so an app learns about a new subscriber, a tag change, or a purchase without polling.
OAuth 2.0 is the method for apps that act on behalf of other creators, and it is required to publish an app for public install. It supports the authorization code grant, refresh tokens, and PKCE for single-page and mobile apps. Today it carries two coarse scopes, read and write, with finer-grained scopes stated as coming soon. OAuth-authenticated calls also get the higher 600-per-minute rate limit.
A v4 API key is sent in the X-Kit-Api-Key header and is meant for a developer automating their own account, not for a published app. It is limited to 120 requests per minute and cannot call the endpoints that require OAuth, such as some bulk and purchase-creation methods.
The Kit API is split into areas an agent can act on, such as subscribers, tags, sequences, forms, and broadcasts. Each area has its own methods, and writing to any of them sends real email or changes a creator's audience.
List and read subscribers, create or update one, read the tags on a subscriber, and unsubscribe a subscriber.
List and create tags, list the subscribers on a tag, and add or remove a tag on a subscriber by id or by email address.
List sequences, list the subscribers in a sequence, and add a subscriber to a sequence.
List forms, list the subscribers on a form, and add a subscriber to a form by id or by email address.
List, read, and create broadcasts, the one-off emails sent to a creator's list.
List and create the custom fields that store extra data against each subscriber.
List the webhooks on an account, create a new one for chosen events, and delete a webhook.
Read the authenticated account, including its plan and primary email address.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SubscribersList and read subscribers, create or update one, read the tags on a subscriber, and unsubscribe a subscriber.6 | ||||||
| GET | /v4/subscribers | List subscribers, with filters for state, created and updated dates, and email address. | read | read | Current | |
OAuth scope read, or a v4 API key. v4 currently has two coarse scopes, read and write, and read covers every list and get method. Acts onsubscriber Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v4/subscribers/{id} | Get a single subscriber by id. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts onsubscriber Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/subscribers | Create a subscriber, or update the first name of an existing one matched by email address. | write | write | Current | |
OAuth scope write, or a v4 API key. Creating an already-existing subscriber updates the first name rather than failing. Acts onsubscriber Permission (capability) writeVersionAvailable since the API’s base version Webhook event subscriber-activateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v4/subscribers/{id} | Update a subscriber's email address, first name, or custom field values. | write | write | Current | |
OAuth scope write, or a v4 API key. Acts onsubscriber Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v4/subscribers/{id}/tags | List the tags applied to a subscriber. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts onsubscriber Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/subscribers/{id}/unsubscribe | Unsubscribe a subscriber so they stop receiving email. | write | write | Current | |
OAuth scope write, or a v4 API key. This sets the subscriber's state to unsubscribed for the whole account. Acts onsubscriber Permission (capability) writeVersionAvailable since the API’s base version Webhook event subscriber-unsubscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList and create tags, list the subscribers on a tag, and add or remove a tag on a subscriber by id or by email address.6 | ||||||
| GET | /v4/tags | List the tags on the account. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts ontag Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/tags | Create a tag. | write | write | Current | |
OAuth scope write, or a v4 API key. Acts ontag Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v4/tags/{tag_id}/subscribers | List the subscribers that carry a given tag. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts ontag Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/tags/{tag_id}/subscribers/{id} | Add a tag to a subscriber by subscriber id. | write | write | Current | |
OAuth scope write, or a v4 API key. A tag is the most common trigger for an automation, so this can start a sequence of emails. Acts ontag Permission (capability) writeVersionAvailable since the API’s base version Webhook event tag-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/tags/{tag_id}/subscribers | Add a tag to a subscriber identified by email address rather than id. | write | write | Current | |
OAuth scope write, or a v4 API key. The email address is sent in the request body, which avoids a separate lookup for the subscriber id. Acts ontag Permission (capability) writeVersionAvailable since the API’s base version Webhook event tag-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v4/tags/{tag_id}/subscribers/{id} | Remove a tag from a subscriber by subscriber id. | write | write | Current | |
OAuth scope write, or a v4 API key. Acts ontag Permission (capability) writeVersionAvailable since the API’s base version Webhook event tag-removeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SequencesList sequences, list the subscribers in a sequence, and add a subscriber to a sequence.3 | ||||||
| GET | /v4/sequences | List the sequences on the account. | read | read | Current | |
OAuth scope read, or a v4 API key. Kit calls these sequences in the API and courses in some webhook event names. Acts onsequence Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v4/sequences/{sequence_id}/subscribers | List the subscribers in a sequence. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts onsequence Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/sequences/{sequence_id}/subscribers/{id} | Add a subscriber to a sequence, starting its automated email series for that person. | write | write | Current | |
OAuth scope write, or a v4 API key. This begins real email delivery on the sequence's schedule. Acts onsequence Permission (capability) writeVersionAvailable since the API’s base version Webhook event course-subscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FormsList forms, list the subscribers on a form, and add a subscriber to a form by id or by email address.4 | ||||||
| GET | /v4/forms | List the forms on the account. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts onform Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v4/forms/{form_id}/subscribers | List the subscribers on a form. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts onform Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/forms/{form_id}/subscribers/{id} | Add a subscriber to a form by subscriber id. | write | write | Current | |
OAuth scope write, or a v4 API key. Adding a subscriber to a form can fire that form's automations. Acts onform Permission (capability) writeVersionAvailable since the API’s base version Webhook event form-subscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/forms/{form_id}/subscribers | Add a subscriber to a form identified by email address rather than id. | write | write | Current | |
OAuth scope write, or a v4 API key. The email address is sent in the request body, which creates the subscriber if it does not already exist. Acts onform Permission (capability) writeVersionAvailable since the API’s base version Webhook event form-subscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BroadcastsList, read, and create broadcasts, the one-off emails sent to a creator's list.3 | ||||||
| GET | /v4/broadcasts | List broadcasts on the account. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts onbroadcast Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v4/broadcasts/{id} | Get a single broadcast by id. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts onbroadcast Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/broadcasts | Create a broadcast, the one-off email sent to a list or segment. | write | write | Current | |
OAuth scope write, or a v4 API key. A broadcast created with a send or schedule time delivers real email to subscribers. Acts onbroadcast Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom fieldsList and create the custom fields that store extra data against each subscriber.2 | ||||||
| GET | /v4/custom_fields | List the custom fields defined on the account. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts oncustom field Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/custom_fields | Create a custom field that stores extra data against each subscriber. | write | write | Current | |
OAuth scope write, or a v4 API key. Acts oncustom field Permission (capability) writeVersionAvailable since the API’s base version Webhook event field-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList the webhooks on an account, create a new one for chosen events, and delete a webhook.3 | ||||||
| GET | /v4/webhooks | List the webhooks registered on the account. | read | read | Current | |
OAuth scope read, or a v4 API key. Acts onwebhook Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v4/webhooks | Create a webhook that posts chosen subscriber, purchase, or custom field events to a receiver URL. | write | write | Current | |
OAuth scope write, or a v4 API key. The chosen event and its target, such as a tag id or form id, are set in the request body. Acts onwebhook Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v4/webhooks/{id} | Delete a webhook. | write | write | Current | |
OAuth scope write, or a v4 API key. Acts onwebhook Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountRead the authenticated account, including its plan and primary email address.1 | ||||||
| GET | /v4/account | Get the authenticated account, including its name, plan, and primary email address. | read | read | Current | |
OAuth scope read, or a v4 API key. This is the simplest call to confirm a credential is valid. Acts onaccount Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Kit can notify an app or AI agent when something happens in an account, instead of the app repeatedly asking. Kit posts the event payload to a webhook URL that has been registered for the chosen subscriber, purchase, or custom field events.
| Event | What it signals | Triggered by |
|---|---|---|
subscriber.subscriber_activate | Fires when a subscriber becomes active, having confirmed their subscription. | /v4/subscribers |
subscriber.subscriber_unsubscribe | Fires when a subscriber unsubscribes from the account. | /v4/subscribers/{id}/unsubscribe |
subscriber.subscriber_bounce | Fires when email to a subscriber bounces. | In-app only |
subscriber.subscriber_complain | Fires when a subscriber marks an email as spam. | In-app only |
subscriber.form_subscribe | Fires when a subscriber is added to a chosen form, set by form_id when the webhook is created. | /v4/forms/{form_id}/subscribers/{id}/v4/forms/{form_id}/subscribers |
subscriber.course_subscribe | Fires when a subscriber is added to a chosen sequence, set by sequence_id when the webhook is created. Kit calls a sequence a course in this event. | /v4/sequences/{sequence_id}/subscribers/{id} |
subscriber.course_complete | Fires when a subscriber completes a chosen sequence, set by sequence_id when the webhook is created. | In-app only |
subscriber.link_click | Fires when a subscriber clicks a chosen tracked link, set by initiator_value when the webhook is created. | In-app only |
subscriber.product_purchase | Fires when a subscriber purchases a chosen product, set by product_id when the webhook is created. | In-app only |
subscriber.tag_add | Fires when a chosen tag is added to a subscriber, set by tag_id when the webhook is created. | /v4/tags/{tag_id}/subscribers/{id}/v4/tags/{tag_id}/subscribers |
subscriber.tag_remove | Fires when a chosen tag is removed from a subscriber, set by tag_id when the webhook is created. | /v4/tags/{tag_id}/subscribers/{id} |
purchase.purchase_create | Fires when a purchase is created on the account. | In-app only |
custom_field.field_created | Fires when a custom field is created on the account. | /v4/custom_fields |
custom_field.field_deleted | Fires when a custom field is deleted from the account. | In-app only |
custom_field.field_value_updated | Fires when a chosen custom field's value changes on a subscriber, set by custom_field_id when the webhook is created. | In-app only |
Kit limits how fast an app or AI agent can call, through a rolling per-minute request quota that depends on how the call is authenticated, and it returns a 429 when the quota is exceeded.
Kit limits requests over a rolling 60-second window per credential. An OAuth-authenticated app gets up to 600 requests per minute; a v4 API key gets up to 120 per minute. Exceeding the window returns a 429, and the documented advice is to retry with exponential backoff until the window clears. Bulk and async operations run on a separate queue, and enqueuing too many at once returns a 413.
All v4 list endpoints use cursor-based paging, not page numbers. A response carries a pagination object with has_previous_page, has_next_page, start_cursor, and end_cursor; the next page is fetched with the after parameter set to end_cursor, and the previous page with before set to start_cursor. The per_page parameter sets page size, defaulting to 500 and capped at 1000. A total count is returned only when include_total_count is set to true, which adds latency.
Requests and responses are JSON. The largest page is 1000 records, set with per_page. Bulk endpoints accept many records in one call and process them asynchronously off a queue rather than returning the full result inline.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication is missing or misconfigured: no credential was sent, the wrong method was used, or account access has lapsed. | Send a valid v4 API key in the X-Kit-Api-Key header, or a valid OAuth Bearer token, and confirm the account is still active. |
| 413 | Too many bulk requests | Too many bulk requests were enqueued at once. Kit processes bulk and async jobs on a queue and limits how many can be pending. | Back off and retry, and avoid enqueuing many bulk jobs at the same time. |
| 422 | Bad data | The request was well-formed but a field contains bad data or a required field is missing. | Read the errors array in the body, correct the named field, and resend. |
| 429 | Rate limited | The rolling per-minute request quota was exceeded: 600 per minute with OAuth, 120 per minute with a v4 API key. | Slow down and retry with exponential backoff until the rolling 60-second window clears. |
| 500 | Internal server error | The server is overloaded or hit a bug. | Retry after a short delay, and report it to Kit if it persists. |
Kit numbers its API by major version in the path. The current version is v4, which replaced v3 with cursor-based paging and a single consistent error shape. The older v3 API still answers but is no longer the recommended target.
v4 is the current major version, served at api.kit.com/v4. It replaced the v3 API at api.convertkit.com as part of the rename from ConvertKit to Kit. v4 switched all list endpoints to cursor-based paging, standardized errors to a single JSON object with an errors array of strings, and introduced OAuth 2.0 for apps alongside API keys sent in the X-Kit-Api-Key header. v4 API keys are not compatible with v3, so credentials have to be regenerated when migrating.
v3 is the predecessor API, served at api.convertkit.com under the ConvertKit name. It used page and offset pagination and varied error responses, and it authenticated with v3 API keys and secrets. v3 still answers but is no longer the recommended target, and its keys do not work against v4.
An integration on v3 moves to v4 by switching host and path and adopting cursor paging.
Kit API v4 upgrade notes ↗Bollard AI sits between a team's AI agents and Kit. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.