> 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

> Create a project, scope requests to it with a project API key, the X-Project-Id header, or the project_id body field, and see which methods enforce its budget.

A project gives one team, product, or environment its own budget, routing policy, compression, guardrails, vendor controls, and spend reporting.

## Create a project

In [Projects](https://gateway.merge.dev/projects), click **Add project** and fill in **Project details** (name, org-unique slug, description), **Budget** (skippable), and **Routing** (org default or a project policy). All are editable later:

| Tab               | What it holds                                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**      | The project ID (a UUID, used as the `project_id` value), spend, and budget progress                                                |
| **Configuration** | [Budget](/merge-gateway/cost/budgets), [compression](/merge-gateway/cost/context-compression), prompt injection, and DLP overrides |
| **Routing**       | The project's routing policy and **Tag rules**                                                                                     |
| **Controls**      | Project-level [ZDR, vendor, and region](/merge-gateway/security/zero-data-retention#scoped-controls) overrides                     |
| **API keys**      | Keys that attribute every request to this project                                                                                  |
| **Settings**      | Edit the name, slug, and description, or delete the project. Deleting is blocked while active project API keys exist               |

## Scoping requests to a project

Use a project API key when you control the key but not the body (Claude Code, Cursor), and the header when one service sends several projects' traffic on one organization key.

| Method                                                         | Where it works                              | Project budget enforced |
| -------------------------------------------------------------- | ------------------------------------------- | ----------------------- |
| **Project API key**, created on the project's **API keys** tab | Every endpoint                              | Yes                     |
| **`X-Project-Id` header**                                      | Every endpoint                              | Yes                     |
| **`project_id` body field**                                    | `/v1/responses`, `/v1/openai`, `/v1/ai-sdk` | No                      |

For a hard limit, use the key or the header ([how budgets are enforced](/merge-gateway/cost/budgets#how-limits-are-enforced)).

**`cURL`**

```bash title="cURL"
curl https://api-gateway.merge.dev/v1/responses \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "X-Project-Id: 4f8b2c6e-9d1a-4e7a-b3f5-2c8d0a6e1b47" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "input": [
      {"type": "message", "role": "user", "content": "Explain recursion in two sentences."}
    ]
  }'
```

**`OpenAI SDK`**

```python title="OpenAI SDK"
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MERGE_GATEWAY_API_KEY"],
    base_url="https://api-gateway.merge.dev/v1/openai",
    default_headers={"X-Project-Id": "4f8b2c6e-9d1a-4e7a-b3f5-2c8d0a6e1b47"},
)

completion = client.chat.completions.create(
    model="openai/gpt-5.5",
    messages=[{"role": "user", "content": "Explain recursion in two sentences."}],
)
print(completion.choices[0].message.content)
```

When methods combine:

* A project API key locks its project: a header or body value naming another project returns `400 project_mismatch`; a match is accepted
* With an organization key, a body `project_id` wins over the header for attribution and routing, but the budget check uses the header's project
* Combining a project with an [Embedded Routing](/merge-gateway/embedded-routing-stack/overview) `customer` returns `400 customer_project_conflict`

A project request uses the project's [routing policy](/merge-gateway/routing/using-policies), or the org default when it has none.

## Tags

For tag-based routing, send tags as key-value pairs in the request's `tags` body field. Define each pair for your organization first; `GET /v1/tags` lists the available pairs. [Tag rules](/merge-gateway/routing/overview#tag-based-routing) on a project's **Routing** tab select a different strategy when all pairs in a rule match. Extra request tags don't prevent a match, and the first matching rule wins.

## Deactivating a project

Setting `is_active` to `false` through the [Projects API](/merge-gateway/automation/projects-api/projects) doesn't stop traffic; it drops guardrail overrides and blocks new project API keys. To stop traffic, disable or delete the keys or set a hard limit.

## Next steps

#### [Budgets](/merge-gateway/cost/budgets)

Cap a project's spend with soft or hard limits

#### [Routing policies](/merge-gateway/routing/overview)

Give a project its own failover or intelligent routing

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

Create and configure projects from code