Merge API Documentation

A project groups related traffic: it can carry its own routing policy, a budget, and project-scoped API keys, and its spend is reported separately in usage.

Path: /v1/projects. Requires the manage_projects scope.

Fields

Field	Description	Type
`id`	Merge UUID	string
`name`	Project name	string
`slug`	URL-safe identifier, derived from `name`, unique per organization	string
`description`	Optional free-text description	string, nullable
`is_active`	Whether the project is active	boolean
`uses_organization_default_routing`	`true` when the project routes via the org default policy	boolean
`routing_policy`	The project’s scoped routing policy (null when using the org default)	object, nullable
`budget_config`	Spending limit (null when unlimited)	object, nullable
`created_at`, `updated_at`	Timestamps for the project object itself (the embedded policy carries its own `modified_at`)	datetime

Unknown fields in request bodies are rejected with 422 rather than silently dropped, so IaC callers learn about typos instead of losing config.

Create a project

$ curl -X POST https://api-gateway.merge.dev/v1/projects \
>   -H "Authorization: Bearer mgmt_<your_management_key>" \
>   -H "Content-Type: application/json" \
>   -d '{ "name": "Internal Tools" }'

slug is derived from name (Internal Tools becomes internal-tools) and suffixed -2, -3 on collision. To create the project with its own routing or a budget, see Project routing and Budgets.

List and get projects

Lists are keyset-paginated: pass limit (default 20, max 100) and the next cursor from the previous response.

$ curl "https://api-gateway.merge.dev/v1/projects?limit=20" \
>   -H "Authorization: Bearer mgmt_<your_management_key>"

Update a project

PATCH updates only the fields you send.

$ curl -X PATCH https://api-gateway.merge.dev/v1/projects/{project_id} \
>   -H "Authorization: Bearer mgmt_<your_management_key>" \
>   -H "Content-Type: application/json" \
>   -d '{ "name": "Renamed", "description": "Batch pipelines" }'

Delete a project

Deleting a project also deletes its scoped routing policy and budget. The delete is blocked with 409 (PROJECT_HAS_ACTIVE_API_KEYS) while active project-scoped API keys exist. Revoke those first. If the deletion check cannot be completed, the request fails with 503 rather than deleting a project that may still have live keys.

$ curl -X DELETE https://api-gateway.merge.dev/v1/projects/{project_id} \
>   -H "Authorization: Bearer mgmt_<your_management_key>"