Management API

The Management API administers your organization’s API keys, projects, routing policies, provider credentials, export destinations, settings, security rules, and usage from code, such as Pulumi, Terraform, or one-off scripts. The endpoint reference in this section has the full schemas.

Base URL and authentication

https://api-gateway.merge.dev

Authenticate with a management key from API keys → Management keys in the dashboard, shown once. It acts only on its own organization and can’t call model endpoints.

Authorization: Bearer mgmt_...

Scopes

A management key’s scopes are dashboard permission names. A new key gets the permissions its creator holds, so it can do through the API what that person can do in the dashboard. A call without the scope it needs returns 403. A key keeps the scopes it was minted with, so mint a new one to pick up permissions granted later.

Keys minted before scopes became permission names hold manage_keys and read_usage, which work as manage_api_keys and view_billing.

Walkthroughs: Management API keys and Projects API. Creating an API key needs a payment method on file, except on the Free plan. There’s no rotate endpoint: create the new key, then delete or disable the old one.

Errors

An error response has a detail field. It’s either a string or an object with a code to branch on and a message; some objects add fields, such as count.

{"detail": {"code": "payment_method_required", "message": "Add a payment method before creating API keys."}}

A request body or query that fails validation returns 422 with detail as a list, one entry per problem, each with loc (where), msg, and type. A missing or invalid key returns 401. See the codes worth branching on.

Next steps