> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/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 these: project usage accepts `view_billing` or `manage_projects`, organization usage needs `view_billing`, and the guardrail overrides also accept `manage_security_rules` (reads also `view_security_rules`). See [scopes](/merge-gateway/management-api#scopes).

| 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