> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a group
> Create a Frontier Gateway group with its model set, per-model limits, and a place in the hierarchy.
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](/frontier-gateway/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. |
```bash curl theme={"system"}
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
}
}'
```
```json 200 theme={"system"}
{
"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"
}
```
## OpenAPI
````yaml post /v1/gateway/groups
openapi: 3.1.0
info:
description: REST API for management of Baseten resources
title: Baseten management API
version: 1.0.0
servers:
- url: https://api.baseten.co
security:
- BearerAuth: []
paths:
/v1/gateway/groups:
post:
summary: Creates a group
description: Creates a group and its endpoint configuration.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGroupRequestV1'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GroupV1'
x-codeSamples:
- lang: bash
source: |-
curl --request POST \
--url https://api.baseten.co/v1/gateway/groups \
--header "Authorization: Bearer $BASETEN_API_KEY" \
--data '{
"metadata": {
"name": "Acme prod",
"external_entity_id": "cust_42"
},
"models": [
{
"slug": "my-org/claude"
}
],
"hierarchy": {
"limit_enforcement": "INDEPENDENT",
"parent_group_id": "abc123"
}
}'
- lang: python
source: |-
import requests
import os
API_KEY = os.environ.get("BASETEN_API_KEY", "")
url = "https://api.baseten.co/v1/gateway/groups"
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.request(
"POST",
url,
headers=headers,
json={'metadata': {'name': 'Acme prod', 'external_entity_id': 'cust_42'}, 'models': [{'slug': 'my-org/claude'}], 'hierarchy': {'limit_enforcement': 'INDEPENDENT', 'parent_group_id': 'abc123'}}
)
print(response.text)
components:
schemas:
CreateGroupRequestV1:
properties:
metadata:
$ref: '#/components/schemas/GroupMetadataV1'
description: Group identity + display metadata.
models:
description: >-
Per-model rate and usage limit configuration. Defines the group's
complete model set. Must be non-empty.
examples:
- - slug: my-org/claude
items:
$ref: '#/components/schemas/ModelConfigV1'
minItems: 1
title: Models
type: array
hierarchy:
$ref: '#/components/schemas/CreateGroupHierarchyV1'
description: Parent linkage and limit enforcement mode. Immutable after creation.
required:
- metadata
- models
- hierarchy
title: CreateGroupRequestV1
type: object
GroupV1:
properties:
id:
description: Internal Baseten ID for the group.
title: Id
type: string
metadata:
$ref: '#/components/schemas/GroupMetadataV1'
description: Group identity + display metadata.
models:
items:
$ref: '#/components/schemas/ModelConfigV1'
title: Models
type: array
effective_models:
items:
$ref: '#/components/schemas/EffectiveModelConfigV1'
title: Effective Models
type: array
hierarchy:
$ref: '#/components/schemas/GroupHierarchyV1'
description: >-
Parent linkage and limit enforcement mode. Parent is null for root
groups.
created_at:
description: When this group was created.
format: date-time
title: Created At
type: string
required:
- id
- metadata
- hierarchy
- created_at
title: GroupV1
type: object
GroupMetadataV1:
properties:
name:
anyOf:
- maxLength: 255
type: string
- type: 'null'
default: null
description: Optional display name for the group.
examples:
- Acme prod
title: Name
external_entity_id:
description: >-
External-system identifier for this group. Unique within the
caller's org.
examples:
- cust_42
maxLength: 255
minLength: 1
title: External Entity Id
type: string
required:
- external_entity_id
title: GroupMetadataV1
type: object
ModelConfigV1:
properties:
slug:
description: Shared endpoint slug.
title: Slug
type: string
rate_limits:
items:
$ref: '#/components/schemas/RateLimitV1'
title: Rate Limits
type: array
usage_limits:
items:
$ref: '#/components/schemas/UsageLimitV1'
title: Usage Limits
type: array
required:
- slug
title: ModelConfigV1
type: object
CreateGroupHierarchyV1:
properties:
limit_enforcement:
anyOf:
- $ref: '#/components/schemas/LimitEnforcementV1'
- type: 'null'
default: null
description: >-
Limit behavior. Child groups inherit their parent's behavior when
omitted; root groups default to Independent for backwards
compatibility.
examples:
- INDEPENDENT
parent_group_id:
anyOf:
- type: string
- type: 'null'
default: null
examples:
- abc123
title: Parent Group Id
title: CreateGroupHierarchyV1
type: object
EffectiveModelConfigV1:
properties:
slug:
description: Shared endpoint slug.
title: Slug
type: string
rate_limits:
items:
$ref: '#/components/schemas/EffectiveRateLimitV1'
title: Rate Limits
type: array
usage_limits:
items:
$ref: '#/components/schemas/EffectiveUsageLimitV1'
title: Usage Limits
type: array
required:
- slug
title: EffectiveModelConfigV1
type: object
GroupHierarchyV1:
properties:
limit_enforcement:
$ref: '#/components/schemas/LimitEnforcementV1'
examples:
- CASCADING
- INDEPENDENT
parent_group_id:
anyOf:
- type: string
- type: 'null'
default: null
examples:
- abc123
title: Parent Group Id
required:
- limit_enforcement
title: GroupHierarchyV1
type: object
RateLimitV1:
properties:
type:
$ref: '#/components/schemas/LimitTypeV1'
description: The type of the rate limit
examples:
- TOKEN
- REQUEST
unit:
$ref: '#/components/schemas/RateLimitUnitV1'
description: The unit of the rate limit
examples:
- SECOND
- MINUTE
threshold:
description: The threshold for the rate limit
examples:
- 1000
- 50000
minimum: 0
title: Threshold
type: integer
required:
- type
- unit
- threshold
title: RateLimitV1
type: object
UsageLimitV1:
properties:
type:
$ref: '#/components/schemas/LimitTypeV1'
description: The type of the usage limit
examples:
- REQUEST
- TOKEN
unit:
$ref: '#/components/schemas/UsageLimitUnitV1'
description: The unit of the usage limit
examples:
- DAY
threshold:
description: The threshold for the usage limit
examples:
- 10000000
minimum: 0
title: Threshold
type: integer
required:
- type
- unit
- threshold
title: UsageLimitV1
type: object
LimitEnforcementV1:
enum:
- CASCADING
- INDEPENDENT
title: LimitEnforcementV1
type: string
EffectiveRateLimitV1:
properties:
type:
$ref: '#/components/schemas/LimitTypeV1'
description: The type of the rate limit
examples:
- TOKEN
- REQUEST
unit:
$ref: '#/components/schemas/RateLimitUnitV1'
description: The unit of the rate limit
examples:
- SECOND
- MINUTE
threshold:
description: The threshold for the rate limit
examples:
- 1000
- 50000
minimum: 0
title: Threshold
type: integer
source_group:
description: ID of the group in the hierarchy this limit is anchored to.
examples:
- abc123
title: Source Group
type: string
required:
- type
- unit
- threshold
- source_group
title: EffectiveRateLimitV1
type: object
EffectiveUsageLimitV1:
properties:
type:
$ref: '#/components/schemas/LimitTypeV1'
description: The type of the usage limit
examples:
- REQUEST
- TOKEN
unit:
$ref: '#/components/schemas/UsageLimitUnitV1'
description: The unit of the usage limit
examples:
- DAY
threshold:
description: The threshold for the usage limit
examples:
- 10000000
minimum: 0
title: Threshold
type: integer
source_group:
description: ID of the group in the hierarchy this limit is anchored to.
examples:
- abc123
title: Source Group
type: string
required:
- type
- unit
- threshold
- source_group
title: EffectiveUsageLimitV1
type: object
LimitTypeV1:
enum:
- REQUEST
- TOKEN
title: LimitTypeV1
type: string
RateLimitUnitV1:
enum:
- SECOND
- MINUTE
title: RateLimitUnitV1
type: string
UsageLimitUnitV1:
enum:
- DAY
title: UsageLimitUnitV1
type: string
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Send `Authorization: Bearer `. The legacy `Authorization:
Api-Key ` scheme is also accepted.
````