Skip to main content
POST
Create Agent Group
Use this API to create an agent group. Groups let you bundle custom and/or built-in agents together and filter execution/list responses by group. Agents remain independent documents; a group only stores an agentIds array that references them, and an agent can belong to multiple groups.
Groups are stored at the Firestore path apiKey/{apiKey}/agentGroup/{groupId}. A workspace may have at most 50 groups (MAX_GROUPS_PER_API_KEY), and each group may contain at most 100 agents (MAX_AGENTS_PER_GROUP).
metadata is immutable after creation. There is no way to modify it later; the update endpoint only changes name/description. If you need document or organization context on a group, embed it inside the metadata object you send here. The workspace apiKey is always merged into metadata.apiKey server-side.

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
Unknown top-level fields are rejected (.strict()).

Example Requests

Response

Success Response

Failure Response

Errors:
  • RESOURCE_EXHAUSTED: workspace already has MAX_GROUPS_PER_API_KEY (50) groups.
  • RESOURCE_EXHAUSTED: initial agentIds exceeds MAX_AGENTS_PER_GROUP (100).
  • NOT_FOUND: one of the initial agentIds does not exist.
  • INVALID_ARGUMENT: validation failure (missing/empty name, unknown fields, over-length values).