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.
A workspace may have at most 50 groups, and each group may contain at most 100 agents.The 50-group limit counts every group in the workspace, including the system groups the platform auto-provisions (copy-qa, seo, design-checks, performance, brand-checks). Those occupy up to 5 of your 50 slots, so a workspace can hit RESOURCE_EXHAUSTED at 45 self-created groups.
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

string
required
Your API key.
string
required

Body

Params

object
required
Unknown top-level fields are rejected (.strict()).

Example Requests

Response

Success Response

Failure Response

Errors:
  • RESOURCE_EXHAUSTED: the workspace already has 50 groups (system groups included).
  • NOT_FOUND: one of the initial agentIds does not exist.
  • INVALID_ARGUMENT: validation failure (missing/empty name, unknown fields, over-length values, or an agentIds array with more than 100 entries).
An oversized agentIds array is INVALID_ARGUMENT, not RESOURCE_EXHAUSTED. The 100-entry cap is enforced during schema validation on the array as sent, so it fails before the group is created. RESOURCE_EXHAUSTED on this endpoint means only that the workspace is at its 50-group limit.