Projects API

The Projects API creates and deletes your organization’s 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 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.

To create a project API key, call POST /v1/keys with project_id.

Example: a project with routing and a budget

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.

Next steps