Create a group

Create a Frontier Gateway group with its model set, per-model limits, and a place in the hierarchy.

curl

curl --request POST \
  --url https://api.baseten.co/v1/gateway/groups \
  --header "Authorization: Api-Key $BASETEN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "metadata": {
      "name": "Acme prod",
      "external_entity_id": "cust_42"
    },
    "models": [
      {
        "slug": "your-org/your-model",
        "rate_limits": [
          { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000 },
          { "type": "REQUEST", "unit": "MINUTE", "threshold": 100 }
        ],
        "usage_limits": [
          { "type": "TOKEN", "unit": "DAY", "threshold": 10000000 }
        ]
      }
    ],
    "hierarchy": {
      "limit_enforcement": "INDEPENDENT",
      "parent_group_id": null
    }
  }'

200

{
  "id": "abc123hash",
  "metadata": {
    "name": "Acme prod",
    "external_entity_id": "cust_42"
  },
  "models": [
    {
      "slug": "your-org/your-model",
      "rate_limits": [
        { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000 },
        { "type": "REQUEST", "unit": "MINUTE", "threshold": 100 }
      ],
      "usage_limits": [
        { "type": "TOKEN", "unit": "DAY", "threshold": 10000000 }
      ]
    }
  ],
  "effective_models": [
    {
      "slug": "your-org/your-model",
      "rate_limits": [
        { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000, "source_group": "abc123hash" },
        { "type": "REQUEST", "unit": "MINUTE", "threshold": 100, "source_group": "abc123hash" }
      ],
      "usage_limits": [
        { "type": "TOKEN", "unit": "DAY", "threshold": 10000000, "source_group": "abc123hash" }
      ]
    }
  ],
  "hierarchy": {
    "limit_enforcement": "INDEPENDENT",
    "parent_group_id": null
  },
  "created_at": "2026-05-13T12:00:00Z"
}

Create a Frontier Gateway group. Groups own the external identifier, the model set, the rate and usage limits, and the inheritance mode. API keys are minted under groups in a separate call. For the conceptual walkthrough, see Manage groups and API keys.

Errors

Status	Meaning
400 Bad Request	Invalid payload, duplicate external_entity_id, mixed enforcement modes in the same hierarchy, hierarchy exceeds five levels, or a cascading child whose threshold exceeds an ancestor’s.
403 Forbidden	Workspace isn’t onboarded to Frontier Gateway, or the caller doesn’t have management scope.
404 Not Found	hierarchy.parent_group_id references a group that doesn’t exist or isn’t visible to your workspace.

curl

curl --request POST \
  --url https://api.baseten.co/v1/gateway/groups \
  --header "Authorization: Api-Key $BASETEN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "metadata": {
      "name": "Acme prod",
      "external_entity_id": "cust_42"
    },
    "models": [
      {
        "slug": "your-org/your-model",
        "rate_limits": [
          { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000 },
          { "type": "REQUEST", "unit": "MINUTE", "threshold": 100 }
        ],
        "usage_limits": [
          { "type": "TOKEN", "unit": "DAY", "threshold": 10000000 }
        ]
      }
    ],
    "hierarchy": {
      "limit_enforcement": "INDEPENDENT",
      "parent_group_id": null
    }
  }'

200

{
  "id": "abc123hash",
  "metadata": {
    "name": "Acme prod",
    "external_entity_id": "cust_42"
  },
  "models": [
    {
      "slug": "your-org/your-model",
      "rate_limits": [
        { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000 },
        { "type": "REQUEST", "unit": "MINUTE", "threshold": 100 }
      ],
      "usage_limits": [
        { "type": "TOKEN", "unit": "DAY", "threshold": 10000000 }
      ]
    }
  ],
  "effective_models": [
    {
      "slug": "your-org/your-model",
      "rate_limits": [
        { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000, "source_group": "abc123hash" },
        { "type": "REQUEST", "unit": "MINUTE", "threshold": 100, "source_group": "abc123hash" }
      ],
      "usage_limits": [
        { "type": "TOKEN", "unit": "DAY", "threshold": 10000000, "source_group": "abc123hash" }
      ]
    }
  ],
  "hierarchy": {
    "limit_enforcement": "INDEPENDENT",
    "parent_group_id": null
  },
  "created_at": "2026-05-13T12:00:00Z"
}

Authorizations

Authorization · string · header · required

Send Authorization: Bearer <api_key>. The legacy Authorization: Api-Key <api_key> scheme is also accepted.

Body

application/json

metadata · GroupMetadataV1 · object · required

Group identity + display metadata.

Show child attributes

models · ModelConfigV1 · object[] · required

Per-model rate and usage limit configuration. Defines the group's complete model set. Must be non-empty.

Minimum array length: 1

Show child attributes

Example:

[{ "slug": "my-org/claude" }]

hierarchy · CreateGroupHierarchyV1 · object · required

Parent linkage and limit enforcement mode. Immutable after creation.

Show child attributes

Response

200 - application/json

id · string · required

Internal Baseten ID for the group.

metadata · GroupMetadataV1 · object · required

Group identity + display metadata.

Show child attributes

hierarchy · GroupHierarchyV1 · object · required

Parent linkage and limit enforcement mode. Parent is null for root groups.

Show child attributes

created_at · string<date-time> · required

When this group was created.

models · ModelConfigV1 · object[]

Show child attributes

effective_models · EffectiveModelConfigV1 · object[]

Show child attributes