Skip to main content
POST
Create Agent Group
Use this API to create an agent group. Groups are lightweight named collections that reference existing agents via an agentIds array — agents themselves remain independent documents and can belong to multiple groups. metadata is an optional, free-form object — mirroring the agent create contract. The workspace apiKey is merged into metadata.apiKey server-side. metadata is immutable after creation — there is no way to modify it via Update Group. If you need document or organization context on a group, embed it inside metadata on create. The schema uses .strict() so unknown top-level fields are rejected with a clear validation error. Limits:
  • Workspace cap: MAX_GROUPS_PER_API_KEY = 50 (enforced via Firestore count() on create)
  • Per-group cap: MAX_AGENTS_PER_GROUP = 100 (enforced inside a Firestore transaction)

Endpoint

POST https://api.velt.dev/v2/agents/groups/create

Headers

x-velt-api-key
string
required
Your API key.
x-velt-auth-token
string
required

Body

Params

data
object
required

Example Requests

1. Minimal group

2. Full group with members and metadata

Response

Success Response

Failure Response

Errors:
  • INVALID_ARGUMENT — Zod validation failure (missing name, unknown top-level field, etc.)
  • RESOURCE_EXHAUSTED — workspace already has MAX_GROUPS_PER_API_KEY groups, OR initial agentIds exceeds MAX_AGENTS_PER_GROUP
  • NOT_FOUND — one of the initial agentIds does not exist