Skip to main content
POST
Add Agents to Group
Use this API to add one or more agents to an existing group.
This operation is idempotent: re-adding an agent that is already a member is a silent success (no duplicate is appended, no error is thrown). Membership is deduped and appended atomically inside a Firestore transaction using arrayUnion.
All provided ids must reference existing agents. Custom-agent ids are validated in a single batched read; built-in agent ids (e.g. spell-check) are accepted without a lookup. The final membership size is capped at 100, enforced atomically to avoid race conditions.

Endpoint

POST https://api.velt.dev/v2/agents/groups/add-agents

Headers

string
required
Your API key.
string
required

Body

Params

object
required

Example Requests

Response

Success Response

Returns the updated group document, the same shape as Get Group. System groups carry system: true; groups you created omit the field.

Failure Response

Errors:
  • NOT_FOUND: the group does not exist, or one of the provided agentIds does not exist.
  • RESOURCE_EXHAUSTED: the resulting group size would exceed the 100-agent limit.
  • INVALID_ARGUMENT: empty agentIds array or empty id values.