A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The LaunchDarkly API is how an app or AI agent works with a LaunchDarkly account: listing feature flags, turning a flag on or off in an environment, editing the segments that decide who a flag targets, and reading experiments and the audit log. Access is granted through an access token whose role or policy sets which resources and actions a call can read or write, so a token can be scoped to toggle one set of flags and nothing else. Versions are dated, and LaunchDarkly can push each change to a registered webhook so an integration learns about activity without polling.
How an app or AI agent connects to LaunchDarkly determines what it can reach. There is a route for making calls, a hosted server that exposes LaunchDarkly tools to agents, and a route for receiving events, and each is governed by the token behind it and the role or policy that token carries.
The REST API answers at https://app.launchdarkly.com, with EU and Federal hosts at https://app.eu.launchdarkly.com and https://app.launchdarkly.us. A call authenticates with an access token in the Authorization header, and the LD-API-Version header pins the dated version, currently 20240415.
LaunchDarkly's hosted MCP server at https://mcp.launchdarkly.com/mcp/launchdarkly lets an agent call LaunchDarkly through the Model Context Protocol, authenticating with OAuth so no API key sits in a config file. It exposes feature management tools, and there are companion hosted servers for AgentControl configs and for observability at https://mcp.launchdarkly.com/mcp/observability.
LaunchDarkly also ships a local MCP server, run with npx from the @launchdarkly/mcp-server package, that authenticates with a LaunchDarkly API access token passed as --api-key. It exposes tools for feature flags, environments, AI configs, code references, and the audit log. The source is at github.com/launchdarkly/mcp-server.
A webhook POSTs the events that match its policy to a receiver URL, so an integration learns about changes without polling. A signing secret on the webhook lets the receiver verify the payload came from LaunchDarkly.
A service token is not tied to a person and is the recommended way to authenticate an integration. It is created with a base role of Reader, Writer, or Admin, or with a custom role or inline policy, and it is sent in the Authorization header. The token is shown only once, when it is created.
A personal token is tied to a member and inherits that member's permissions, or a narrower role chosen at creation. It is useful for ad hoc scripts, but it stops working if the member loses access, which makes a service token the steadier choice for a long-running integration.
The hosted MCP server authenticates an AI client with OAuth, which removes the need to place an API key in a config file. The access it grants follows the signed-in member's permissions.
The LaunchDarkly API is split into areas an agent can act on, like feature flags, projects, environments, segments, and experiments. Each area has its own methods, and a write in production can switch a flag on or off for live traffic.
List, read, create, update, copy, and delete feature flags, and read a flag's status across environments.
List, read, create, update, and delete the projects that group flags and environments.
List, read, create, update, and delete the environments inside a project, such as production and staging.
List, read, create, update, and delete the segments that group contexts for targeting.
Search and read the contexts (users, devices, and other entities) a flag is evaluated against, and delete a context instance.
List, read, create, and update experiments and the metrics they measure.
List, read, invite, update, and remove the people in an account.
List, read, create, update, and delete teams, and add members to a team.
List, read, create, update, reset, and delete the API access tokens that authenticate calls.
List, read, create, update, and delete the webhooks that deliver change events.
List, search, and read the audit log entries that record every change in an account.
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 | |
|---|---|---|---|---|---|---|
Feature flagsList, read, create, update, copy, and delete feature flags, and read a flag's status across environments.7 | ||||||
| GET | /api/v2/flags/{projectKey} | List the feature flags in a project. | read | Reader | Current | |
Needs the reader action getFeatureFlags on the flag resource. Any token with at least Reader can call it. Under 20240415 this returns 20 flags per page, up to 100. Acts onfeature flag Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/flags/{projectKey}/{featureFlagKey} | Get a single feature flag. | read | Reader | Current | |
Needs the reader action getFeatureFlag on the flag resource. Acts onfeature flag Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/flags/{projectKey} | Create a feature flag in a project. | write | Writer | Current | |
Needs the writer action createFeatureFlag on the flag resource. A custom role or inline policy can grant this on specific projects only. Acts onfeature flag Permission (capability) WriterVersionAvailable since the API’s base version Webhook event flag-changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/flags/{projectKey}/{featureFlagKey} | Update a feature flag, including turning its targeting on or off in an environment. | write | Writer | Current | |
Toggling a flag is a patch on this endpoint, setting the environment's on field, so it needs the writer action updateOn, or updateFeatureFlag for other fields. Production can be restricted with a custom role. Acts onfeature flag Permission (capability) WriterVersionAvailable since the API’s base version Webhook event flag-changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/flags/{projectKey}/{featureFlagKey} | Delete a feature flag. | write | Writer | Current | |
Needs the writer action deleteFeatureFlag on the flag resource. Irreversible. Acts onfeature flag Permission (capability) WriterVersionAvailable since the API’s base version Webhook event flag-changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/flags/{projectKey}/{featureFlagKey}/copy | Copy a flag's settings from one environment to another. | write | Writer | Current | |
Needs the writer action copyFeatureFlag, and write access to the target environment. Acts onfeature flag Permission (capability) WriterVersionAvailable since the API’s base version Webhook event flag-changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/flag-status/{projectKey}/{featureFlagKey} | Get a flag's status across every environment in a project. | read | Reader | Current | |
Read-only. Status reports whether a flag is new, active, launched, or inactive. Acts onfeature flag Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsList, read, create, update, and delete the projects that group flags and environments.5 | ||||||
| GET | /api/v2/projects | List the projects in an account. | read | Reader | Current | |
Needs the reader action getProjects on the project resource. Acts onproject Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/projects/{projectKey} | Get a single project. | read | Reader | Current | |
Needs the reader action getProject on the project resource. Acts onproject Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/projects | Create a project. | write | Admin | Current | |
Needs the action createProject. The default Writer role cannot create projects; this is an Admin action or must be granted by a custom role. Acts onproject Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/projects/{projectKey} | Update a project's settings. | write | Writer | Current | |
Needs the writer action updateProject on the project resource. Acts onproject Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/projects/{projectKey} | Delete a project and everything in it. | write | Admin | Current | |
Needs the action deleteProject. Removes every flag, environment, and segment in the project, so it is an Admin-level action. Acts onproject Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EnvironmentsList, read, create, update, and delete the environments inside a project, such as production and staging.5 | ||||||
| GET | /api/v2/projects/{projectKey}/environments | List the environments in a project. | read | Reader | Current | |
Needs the reader action getEnvironment on the environment resource. Acts onenvironment Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/projects/{projectKey}/environments/{environmentKey} | Get a single environment. | read | Reader | Current | |
Needs the reader action getEnvironment on the environment resource. Acts onenvironment Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/projects/{projectKey}/environments | Create an environment in a project. | write | Writer | Current | |
Needs the writer action createEnvironment on the environment resource. Acts onenvironment Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/projects/{projectKey}/environments/{environmentKey} | Update an environment's settings. | write | Writer | Current | |
Needs the writer action updateEnvironment on the environment resource. Acts onenvironment Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/projects/{projectKey}/environments/{environmentKey}/apiKey | Reset an environment's server-side SDK key. | write | Writer | Current | |
Needs the writer action updateSdkKey. Rotates the credential that running SDKs use, so it can break live evaluations until they are updated. Acts onenvironment Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SegmentsList, read, create, update, and delete the segments that group contexts for targeting.5 | ||||||
| GET | /api/v2/segments/{projectKey}/{environmentKey} | List the segments in an environment. | read | Reader | Current | |
Needs the reader action getSegments on the segment resource. Under 20240415 this returns 20 segments per page. Acts onsegment Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/segments/{projectKey}/{environmentKey}/{segmentKey} | Get a single segment. | read | Reader | Current | |
Needs the reader action getSegment on the segment resource. Acts onsegment Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/segments/{projectKey}/{environmentKey} | Create a segment in an environment. | write | Writer | Current | |
Needs the writer action createSegment on the segment resource. Acts onsegment Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/segments/{projectKey}/{environmentKey}/{segmentKey} | Update a segment, including the contexts it includes or excludes. | write | Writer | Current | |
Needs the writer action updateSegment. Changing a segment changes which contexts a flag targets. Acts onsegment Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/segments/{projectKey}/{environmentKey}/{segmentKey} | Delete a segment. | write | Writer | Current | |
Needs the writer action deleteSegment on the segment resource. Acts onsegment Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ContextsSearch and read the contexts (users, devices, and other entities) a flag is evaluated against, and delete a context instance.3 | ||||||
| POST | /api/v2/projects/{projectKey}/environments/{environmentKey}/contexts/search | Search for contexts that have been seen in an environment. | read | Reader | Current | |
A read despite the POST verb, used to query contexts. Needs the reader action getContextInstances. Acts oncontext Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/projects/{projectKey}/environments/{environmentKey}/context-instances/{id} | Get the instances of a single context. | read | Reader | Current | |
Needs the reader action getContextInstances on the context resource. Acts oncontext Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/projects/{projectKey}/environments/{environmentKey}/context-instances/{id} | Delete the stored instances of a context. | write | Writer | Current | |
Needs the writer action deleteContextInstances on the context resource. Acts oncontext Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Experiments & metricsList, read, create, and update experiments and the metrics they measure.4 | ||||||
| GET | /api/v2/projects/{projectKey}/environments/{environmentKey}/experiments | List the experiments in an environment. | read | Reader | Current | |
Needs the reader action getExperiment on the experiment resource. Acts onexperiment Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/projects/{projectKey}/environments/{environmentKey}/experiments | Create an experiment. | write | Writer | Current | |
Needs the writer action createExperiment on the experiment resource. Acts onexperiment Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/metrics/{projectKey} | List the metrics in a project. | read | Reader | Current | |
Needs the reader action getMetric on the metric resource. Acts onmetric Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/metrics/{projectKey} | Create a metric. | write | Writer | Current | |
Needs the writer action createMetric on the metric resource. Acts onmetric Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Account membersList, read, invite, update, and remove the people in an account.3 | ||||||
| GET | /api/v2/members | List the members of an account. | read | Reader | Current | |
Needs the reader action getMember on the member resource. Acts onmember Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/members | Invite one or more new members to an account. | write | Admin | Current | |
Needs the action createMember. Adding people to an account is an Admin-level action unless granted by a custom role. Acts onmember Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/members/{id} | Modify a member, including their role. | write | Admin | Current | |
Needs the action updateRole or updateCustomRole. Changing a member's role changes their access, so it is an Admin-level action. Acts onmember Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TeamsList, read, create, update, and delete teams, and add members to a team.3 | ||||||
| GET | /api/v2/teams | List the teams in an account. | read | Reader | Current | |
Needs the reader action getTeam on the team resource. Acts onteam Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/teams | Create a team. | write | Admin | Current | |
Needs the action createTeam. Teams carry custom roles, so creating one is an Admin-level action unless granted by a custom role. Acts onteam Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/teams/{teamKey}/members | Add multiple members to a team by uploading a list. | write | Admin | Current | |
Needs the action updateTeamMembers. Team membership confers the team's roles, so this changes access. Acts onteam Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Access tokensList, read, create, update, reset, and delete the API access tokens that authenticate calls.4 | ||||||
| GET | /api/v2/tokens | List the API access tokens in an account. | read | Admin | Current | |
Needs the action getTokens. Listing all account tokens is an Admin-level action. Under 20240415 this returns 25 tokens per page. Acts onaccess token Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/tokens | Create an API access token with a chosen role or policy. | write | Admin | Current | |
Needs the action createAccessToken. A member can only mint a token at or below their own permissions, so minting an Admin or Writer token needs that level. Acts onaccess token Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/tokens/{id}/reset | Reset an access token, issuing a new secret and revoking the old one. | write | Admin | Current | |
Needs the action resetAccessToken. Invalidates the old secret immediately. Acts onaccess token Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/tokens/{id} | Delete an access token. | write | Admin | Current | |
Needs the action deleteAccessToken. Revokes the token for good. Acts onaccess token Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList, read, create, update, and delete the webhooks that deliver change events.3 | ||||||
| GET | /api/v2/webhooks | List the webhooks in an account. | read | Reader | Current | |
Needs the reader action getWebhook on the webhook resource. Acts onwebhook Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/webhooks | Create a webhook that delivers change events to a URL. | write | Writer | Current | |
Needs the writer action createWebhook. A statements field can scope the webhook to specific resources. Acts onwebhook Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/webhooks/{id} | Delete a webhook. | write | Writer | Current | |
Needs the writer action deleteWebhook on the webhook resource. Acts onwebhook Permission (capability) WriterVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Audit logList, search, and read the audit log entries that record every change in an account.2 | ||||||
| GET | /api/v2/auditlog | List the audit log entries that record changes in an account. | read | Reader | Current | |
Needs the reader action viewAuditLog. Returns who changed what, across the whole account. Acts onaudit log entry Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/auditlog | Search audit log entries with a policy filter. | read | Reader | Current | |
A read despite the POST verb, used to filter entries by resource and action. Needs the reader action viewAuditLog. Acts onaudit log entry Permission (capability) ReaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LaunchDarkly can notify an app or AI agent when something changes, like a flag being toggled or a segment being edited. It posts the change to a webhook URL that has been registered, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
Feature flag change | Fires when a flag is created, updated, toggled on or off, or deleted. The payload carries the audit log entry describing the change, including who made it and the kind and key of what changed. | /api/v2/flags/{projectKey}/api/v2/flags/{projectKey}/{featureFlagKey}/api/v2/flags/{projectKey}/{featureFlagKey}/copy/api/v2/flags/{projectKey}/{featureFlagKey} |
Any policy-matched change | A LaunchDarkly webhook is not a fixed list of named events. It delivers every change whose resource and action match the webhook's policy statements, so it can be scoped to flags in one project, segments, members, or any other resource. | In-app only |
LaunchDarkly limits how fast an app or AI agent can call, through a per-account quota measured over ten-second windows, with some routes carrying their own limit on top.
LaunchDarkly meters requests over rolling ten-second windows rather than by a per-method cost. A global limit caps how many calls the whole account can make per ten seconds, and every personal and service token on the account shares it, so one busy token can slow the others. Some routes carry their own route-level limit on top, and a few use IP-based limiting. Going over returns HTTP 429. The response headers X-Ratelimit-Global-Remaining and X-Ratelimit-Route-Remaining report what is left in each window, X-Ratelimit-Reset gives the reset time, and an IP-limited route returns a Retry-After header. LaunchDarkly does not publish the exact numbers, and sets them per account, so an integration should read the headers and back off rather than assume a fixed ceiling.
Under version 20240415, list endpoints are paginated with limit and offset query parameters, and the response carries an _links object with first, prev, next, and last links to follow rather than building URLs by hand. Default and maximum page sizes vary by endpoint: feature flags return 20 by default up to 100, segments 20 by default up to 50, access tokens 25 by default up to 1,000, and custom roles 20 by default up to 1,000. Several of these endpoints were unpaginated before 20240415.
Responses are JSON. There is no single documented payload size limit across the whole API; per-endpoint page-size caps, such as 100 for feature flags and 50 for segments, bound how much a single list call returns.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request | The request cannot be understood, usually malformed JSON or an invalid body. | Check the JSON syntax and the request body against the endpoint reference, then resend. |
| 401 | unauthorized | The access token is missing, invalid, or expired. | Send a valid token in the Authorization header. |
| 403 | forbidden | The token is valid but its role or policy does not allow this action on this resource. A beta resource called without the LD-API-Version: beta header also returns 403. | Grant the needed action on the resource through the token's role or policy, or add the beta version header. |
| 404 | not_found | The resource does not exist, or the token cannot see it. | Confirm the project, environment, and resource keys in the path. |
| 409 | conflict | The request conflicts with the current state, often a concurrent update to the same resource. | Refetch the resource and retry the change. |
| 422 | unprocessable_entity | The update description cannot be understood, usually a malformed patch or semantic patch instruction. | Check the patch format and the field names, then resend. |
| 429 | too_many_requests | A rate limit was exceeded, either the per-account global limit or a route-level limit. | Wait for the time in the Retry-After header, or until the X-Ratelimit-Reset time, then retry. |
LaunchDarkly versions its API by date through the LD-API-Version header. The current version is 20240415, and a request can opt into beta resources by sending the value beta instead.
Version 20240415 is the current dated version, set through the LD-API-Version header. It paginated several previously unpaginated list endpoints, removed the Users API in favour of the Contexts API, and tightened some response shapes. A request that omits the header uses the default version stored on the token.
Version 20220603 is the prior dated version. It is still supported for existing integrations until 31 December 2026, after which calls pinned to it stop working and should move to 20240415. Most of the differences are the pagination and resource changes introduced by the newer version.
Pin a version and move up on a schedule that suits the integration.
LaunchDarkly API migration guide ↗Bollard AI sits between a team's AI agents and LaunchDarkly. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.