> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/merge-gateway/automation/projects-api/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Projects API

> Manage projects over /v1/projects with a management key: project-scoped routing policies, budgets, guardrail and vendor-control overrides, and spend rollups, built for infrastructure-as-code.

The Projects API creates and deletes your organization's [projects](/merge-gateway/cost/projects), sets each one's routing policy, budget, and guardrails, and reads their spend. Use it to drive configuration from Terraform, Pulumi, or scripts.

Send requests to `https://api-gateway.merge.dev` with a [management key](/merge-gateway/automation/api-keys#management-keys) as the bearer token; the organization comes from the key, and IDs are UUIDs. Unknown body fields return `422`, so a typo fails loudly instead of dropping config.

## Endpoints by task

Every endpoint needs the `manage_projects` scope except the usage endpoints: project usage accepts `read_usage` or `manage_projects`, and organization usage needs `read_usage`.

| Task                                      | Endpoint                                                    | Guide                                                                              |
| ----------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Create, list, update, or delete a project | `/v1/projects`, `/v1/projects/{project_id}`                 | [Projects](/merge-gateway/automation/projects-api/projects)                        |
| Give a project its own routing policy     | `routing_policy` on create or `PATCH`                       | [Project routing](/merge-gateway/automation/projects-api/project-routing)          |
| Cap a project's spend                     | `budget_config` on create or `PATCH`                        | [Budgets](/merge-gateway/automation/projects-api/budgets)                          |
| Override prompt injection or DLP policy   | `/v1/projects/{project_id}/pi-settings`, `/dlp-settings`    | [Guardrails](/merge-gateway/automation/projects-api/guardrails)                    |
| Override ZDR, vendor, or region controls  | `/v1/projects/{project_id}/controls`                        | [Zero data retention](/merge-gateway/security/zero-data-retention#scoped-controls) |
| List the models a project can route to    | `GET /v1/projects/{project_id}/models`                      | [API reference](/merge-gateway/management-api)                                     |
| Read spend                                | `/v1/projects/{project_id}/usage`, `/v1/organization/usage` | [Usage](/merge-gateway/automation/projects-api/usage)                              |

To create a project API key, call [`POST /v1/keys`](/merge-gateway/automation/api-keys) with `project_id`.

## Example: a project with routing and a budget

```bash
curl -X POST https://api-gateway.merge.dev/v1/projects \
  -H "Authorization: Bearer $MERGE_GATEWAY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Field Mappings",
    "uses_organization_default_routing": false,
    "routing_policy": {
      "strategy": "PRIORITY",
      "priority_order": [
        { "model": "openai/gpt-5.5", "priority": 1 },
        { "model": "anthropic/claude-opus-4-8", "priority": 2 }
      ]
    },
    "budget_config": {
      "amount": 100,
      "period": "monthly",
      "enforcement_mode": "hard_limit",
      "alert_thresholds": [80, 90]
    }
  }'
```

The response is the project object with its `id`. Scope inference requests with a project API key or `X-Project-Id` header set to that ID so the [budget applies](/merge-gateway/cost/budgets#how-limits-are-enforced).

## Next steps

#### [Projects](/merge-gateway/automation/projects-api/projects)

Create, list, update, and delete projects

#### [Budgets](/merge-gateway/automation/projects-api/budgets)

Set a project's spend limit and alerts

#### [Management API reference](/merge-gateway/management-api)

Full request and response schemas

> Build once. Connect to every API, tool, and LLM. Ship products and agents to production without owning the integration stack.

## Docs

- [Projects](https://docs.merge.dev/merge-gateway/automation/projects-api/projects.md): Project CRUD over /v1/projects: the project object, cursor pagination, updates, deactivation, and the delete guard for active project API keys.
- [Project routing](https://docs.merge.dev/merge-gateway/automation/projects-api/project-routing.md): Attach a project-scoped routing policy with uses_organization_default_routing and routing_policy: ranked Priority or Intelligent strategies, replaced in place with a stable ID.
- [Budgets](https://docs.merge.dev/merge-gateway/automation/projects-api/budgets.md): Configure budget_config on a project: amount, period, hard or soft enforcement, alert thresholds, and recipients, and how PATCH replaces the whole object.
- [Guardrails](https://docs.merge.dev/merge-gateway/automation/projects-api/guardrails.md): Per-project prompt injection and DLP overrides over the API: sparse overrides on top of the organization policy, the tighten-only rule for client-named projects, and write limits.
- [Usage](https://docs.merge.dev/merge-gateway/automation/projects-api/usage.md): Read spend over /v1/organization/usage and /v1/projects/{project_id}/usage: date ranges, managed vs BYOK vs web search spend, per-model breakdowns, and group_by dimensions.