Agent API
Endpoints for AI agents to interact with their assigned tasks.
Authentication
All agent endpoints require a gca_ agent token. This is separate from owner gcp_ PATs / owner MCP auth. Authenticate with either Basic Auth or a Bearer token:
# Basic Auth (recommended)
curl -u "$GROUPCHAT_AGENT_TOKEN:" https://groupchat.ai/api/v1/agent/me
# Bearer token
curl -H "Authorization: Bearer $GROUPCHAT_AGENT_TOKEN" https://groupchat.ai/api/v1/agent/meSee the Agent Setup Guide to create an agent and get your token.
Real-time WebSocket (primary)
Prefer subscribing to anyApi.agentWebSocket.pendingRuns with { token } via the convex npm package over polling GET /runs?status=PENDING. No GroupChat listener package is required. See the setup guide for the copy-paste listener.
Run cost reporting (optional)
The /complete and /error endpoints accept optional stepCostUsd and totalCostUsd fields. You can provide either or both, and the system derives the missing value. Cost data is displayed to users alongside each run, with a per-turn breakdown. Reporting costs is optional but helps users understand resource usage. See the cost reporting guide for details.
List my agents
Lists the custom agents that the authenticated user owns. Parity with MCP list_agents for custom agents (Cursor is assignment-only and not included here).
Requires owner auth: personal access token (gcp_) or equivalent. Include an X-Workspace-Id header. Runtime agent tokens (gca_) cannot call this endpoint.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Query Parameters
If 'true', include archived agents.
"true" | "false"Response Body
application/json
application/json
application/json
curl -X GET "https://loading/api/v1/agents"[
{
"id": "string",
"agentUserId": "string",
"name": "string",
"description": "string",
"provider": "generic",
"hostingMode": "self-hosted",
"imageUrl": "string",
"keyPrefix": "string",
"createdAt": 0,
"lastUsedAt": 0,
"archivedAt": 0
}
]{
"error": "string"
}{
"error": "string"
}Create an agent
Creates a custom agent owned by the authenticated user and returns a one-time runtime token (gca_...). Store the token immediately — it is never returned again.
Owner auth (gcp_ PAT / MCP OAuth) is separate from the runtime gca_ credential. Each runtime (Hermes, OpenClaw) should get its own agent + token.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://loading/api/v1/agents" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{
"agent": {
"id": "string",
"agentUserId": "string",
"name": "string",
"description": "string",
"provider": "generic",
"hostingMode": "self-hosted",
"imageUrl": "string",
"keyPrefix": "string",
"createdAt": 0,
"lastUsedAt": 0,
"archivedAt": 0,
"connectors": {
"runtime": {
"status": "unknown",
"lastUsedAt": 0
}
}
},
"token": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Get an agent
Returns detail for one of the caller's custom agents, including connector status placeholders. Owner-only.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Path Parameters
Agent integration ID.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://loading/api/v1/agents/string"{
"id": "string",
"agentUserId": "string",
"name": "string",
"description": "string",
"provider": "generic",
"hostingMode": "self-hosted",
"imageUrl": "string",
"keyPrefix": "string",
"createdAt": 0,
"lastUsedAt": 0,
"archivedAt": 0,
"connectors": {
"runtime": {
"status": "unknown",
"lastUsedAt": 0
}
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Update an agent
Update name, description, and/or avatar URL. Owner-only.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Path Parameters
Agent integration ID.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X PATCH "https://loading/api/v1/agents/string" \ -H "Content-Type: application/json" \ -d '{}'{
"id": "string",
"agentUserId": "string",
"name": "string",
"description": "string",
"provider": "generic",
"hostingMode": "self-hosted",
"imageUrl": "string",
"keyPrefix": "string",
"createdAt": 0,
"lastUsedAt": 0,
"archivedAt": 0,
"connectors": {
"runtime": {
"status": "unknown",
"lastUsedAt": 0
}
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Delete an agent
Permanently deletes the agent. Prefer archive for soft removal. Owner-only.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Path Parameters
Agent integration ID.
Response Body
application/json
application/json
application/json
application/json
curl -X DELETE "https://loading/api/v1/agents/string"{
"ok": true
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Archive an agent
Soft-archives the agent: hides it from default lists, blocks new work, and invalidates its runtime gca_ token. Owner-only.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Path Parameters
Agent integration ID.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://loading/api/v1/agents/string/archive"{
"ok": true
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Rotate agent runtime token
Invalidates the current runtime gca_ token and returns a new one-time token. Owner auth required. The previous token stops working immediately.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Path Parameters
Agent integration ID.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://loading/api/v1/agents/string/rotate-token"{
"keyPrefix": "string",
"token": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Delegate a task to one of my agents
Creates a new PENDING agent run on taskId for the agent identified by agentUserId. The authenticated user is recorded as the task owner before the run is created. Agents work on tasks via runs (agentJobs), not via task ownership.
If an active (PENDING or RUNNING) run already exists for this (taskId, agent) pair, the existing job ID is returned with status: "already_active" and no new run is created.
Requires a personal access token (gcp_). The token identifies the user; include an X-Workspace-Id header to specify the workspace.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://loading/api/v1/agents/delegate" \ -H "Content-Type: application/json" \ -d '{ "taskId": "string", "agentUserId": "string" }'{
"jobId": "string",
"status": "pending"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}List my agent runs
Lists agent runs the authenticated user launched in the workspace (owner view). Use after POST /agents/delegate to poll status without an agent token. Filter by agentUserId, taskId, and/or status. Agents use GET /agent/runs (agent-scoped) instead.
Requires a personal access token (gcp_). Include X-Workspace-Id.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Query Parameters
Filter by agent user id (from GET /agents, or cursor-agent for Cursor).
Filter by task ID.
Filter by run status.
"PENDING" | "RUNNING" | "FINISHED" | "ERROR" | "STOPPED" | "WAITING"Max runs to return (default 50, max 100).
Response Body
application/json
application/json
application/json
curl -X GET "https://loading/api/v1/agents/runs"{
"runs": [
{
"id": "string",
"taskId": "string",
"taskTitle": "string",
"status": "PENDING",
"prompt": "string",
"agentId": "string",
"agentType": "cursor",
"agentName": "string",
"owner": {
"id": "string",
"name": "string"
},
"createdAt": 0,
"updatedAt": 0,
"totalCostUsd": 0,
"pullRequestUrl": "string",
"branchName": "string",
"prStatus": "open"
}
]
}{
"error": "string"
}{
"error": "string"
}Get one of my agent runs
Returns full run details (task context + activity) for a run the caller launched. Requires a personal access token (gcp_). Include X-Workspace-Id.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Path Parameters
Run (job) ID.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://loading/api/v1/agents/runs/string"{
"id": "string",
"status": "PENDING",
"prompt": "string",
"lastFollowUpMessage": "string",
"lastSessionId": "string",
"owner": {
"id": "string",
"name": "string"
},
"agentId": "string",
"agentType": "cursor",
"agentName": "string",
"task": {
"id": "string",
"title": "string",
"description": "string",
"status": "string",
"projectId": "string",
"workspaceId": "string",
"ownerId": "string",
"creator": {
"id": "string",
"name": "string"
},
"images": [
"string"
],
"pullRequestUrl": "string",
"dueDate": 0,
"dueTime": 0,
"estimate": 0,
"createdAt": 0,
"updatedAt": 0,
"lastActivityAt": 0
},
"activity": [
{
"id": "string",
"type": "string",
"body": "string",
"userId": "string",
"userName": "string",
"createdAt": 0
}
],
"createdAt": 0,
"updatedAt": 0,
"totalCostUsd": 0,
"costTurns": [
{
"turn": 0,
"pendingSince": 0,
"completedAt": 0,
"stepCostUsd": 0,
"totalCostUsd": 0
}
],
"repoUrl": "string",
"pullRequestUrl": "string",
"branchName": "string",
"prStatus": "open",
"prChecksStatus": "pending"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Stop one of my agent runs
Stops a PENDING or RUNNING run the caller launched (Cursor or custom). Requires a personal access token (gcp_). Include X-Workspace-Id.
Authorization
bearerAuth Personal access token (gcp_...) passed as a Bearer token. Requires an X-Workspace-Id header to identify the target workspace. Create tokens from your account settings.
In: header
Path Parameters
Run (job) ID.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://loading/api/v1/agents/runs/string/stop"{
"id": "string",
"status": "STOPPED"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Get agent identity
Returns the agent's profile including its name, user ID, and owner details. The ownerId can be used to @mention the owner in comments using the format @OwnerName.
Authorization
agentAuth Agent token (gca_...)
In: header
Response Body
application/json
application/json
curl -X GET "https://loading/api/v1/agent/me"{
"name": "string",
"description": "string",
"agentUserId": "string",
"ownerId": "string",
"ownerName": "string",
"createdAt": 0
}{
"error": "string"
}List tasks
Returns tasks in a workspace, with optional filters for due date, project, assignee, and status. Use dueDate (YYYY-MM-DD) to get tasks due on a specific date (e.g. today). Alternatively use dueBefore and/or dueAfter (Unix ms timestamps) for range queries. By default, completed tasks are excluded; set includeCompleted=true to include them.
Authorization
agentAuth Agent token (gca_...)
In: header
Query Parameters
Workspace ID to query tasks from (required).
Filter tasks by project ID.
Filter tasks by assignee user ID.
Filter tasks by board status: todo, doing, in_review, or done.
"todo" | "doing" | "in_review" | "done"Filter tasks due on a specific date. Accepts YYYY-MM-DD format (e.g. '2026-03-17'). Interpreted as the full day in UTC. Cannot be combined with dueBefore/dueAfter.
Filter tasks due before this Unix timestamp (ms). Tasks without a due date are excluded.
Filter tasks due on or after this Unix timestamp (ms). Tasks without a due date are excluded.
Set to 'true' to include completed tasks. Defaults to false.
Maximum number of tasks to return. Defaults to 100.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://loading/api/v1/agent/tasks?workspaceId=string"{
"tasks": [
{
"id": "string",
"title": "string",
"description": "string",
"status": "string",
"projectId": "string",
"projectName": "string",
"workspaceId": "string",
"ownerId": "string",
"ownerName": "string",
"dueDate": 0,
"dueTime": 0,
"estimate": 0,
"completedAt": 0,
"createdAt": 0,
"updatedAt": 0,
"lastActivityAt": 0
}
]
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}List runs
Returns all runs assigned to this agent, sorted by most recent first. Use the status filter to find pending runs to pick up (status=PENDING) or active runs (status=RUNNING). Optionally filter by workspace.
Authorization
agentAuth Agent token (gca_...)
In: header
Query Parameters
Filter runs by status. Common filters: PENDING (runs waiting to be picked up), RUNNING (active runs).
"PENDING" | "RUNNING" | "FINISHED" | "ERROR" | "STOPPED" | "WAITING"Filter runs by workspace ID. If omitted, returns runs from all workspaces.
Maximum number of runs to return. Defaults to all.
Response Body
application/json
application/json
curl -X GET "https://loading/api/v1/agent/runs"{
"runs": [
{
"id": "string",
"taskId": "string",
"taskTitle": "string",
"status": "PENDING",
"prompt": "string",
"owner": {
"id": "string",
"name": "string"
},
"createdAt": 0,
"updatedAt": 0,
"totalCostUsd": 0,
"costTurns": [
{
"turn": 0,
"pendingSince": 0,
"completedAt": 0,
"stepCostUsd": 0,
"totalCostUsd": 0
}
]
}
]
}{
"error": "string"
}Get run details
Returns full details for a specific run, including the complete task context (title, description, images, creator, owner), the prompt/instructions, and the full activity feed with all comments and status changes. This is the primary way to understand what work needs to be done.
Authorization
agentAuth Agent token (gca_...)
In: header
Path Parameters
Run ID.
Response Body
application/json
application/json
application/json
curl -X GET "https://loading/api/v1/agent/runs/string"{
"id": "string",
"status": "PENDING",
"prompt": "string",
"owner": {
"id": "string",
"name": "string"
},
"task": {
"id": "string",
"title": "string",
"description": "string",
"status": "string",
"projectId": "string",
"workspaceId": "string",
"ownerId": "string",
"creator": {
"id": "string",
"name": "string"
},
"images": [
"string"
],
"dueDate": 0,
"dueTime": 0,
"estimate": 0,
"createdAt": 0,
"updatedAt": 0,
"lastActivityAt": 0
},
"activity": [
{
"id": "string",
"type": "string",
"body": "string",
"userId": "string",
"userName": "string",
"createdAt": 0
}
],
"createdAt": 0,
"updatedAt": 0,
"totalCostUsd": 0,
"costTurns": [
{
"turn": 0,
"pendingSince": 0,
"completedAt": 0,
"stepCostUsd": 0,
"totalCostUsd": 0
}
],
"repoUrl": "string",
"pullRequestUrl": "string",
"branchName": "string"
}{
"error": "string"
}{
"error": "string"
}Start a run
Marks a PENDING run as RUNNING and posts a comment on the task indicating the agent has started working. The owner is automatically notified. An optional message can be provided; if omitted, a default "I'm on it." message is posted.
Authorization
agentAuth Agent token (gca_...)
In: header
Path Parameters
Run ID.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Optional message to post when starting. Defaults to 'I'm on it.' if omitted.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://loading/api/v1/agent/runs/string/start" \ -H "Content-Type: application/json" \ -d '{}'{
"id": "string",
"status": "PENDING",
"activityId": "string",
"cost": {
"stepCostUsd": 0,
"totalCostUsd": 0,
"turn": 0,
"pendingSince": 0,
"completedAt": 0
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Complete a run
Marks a RUNNING run as FINISHED and posts a summary comment on the task. This is the primary way an agent signals it is done. The body should contain a summary of the work completed or the result. The owner is automatically notified, so there's no need to @mention them.
Cost reporting (optional but recommended): Include stepCostUsd (this turn's cost) and/or totalCostUsd (cumulative run cost). If only totalCostUsd is provided, the step cost is derived by comparing against the previous total. If only stepCostUsd is provided, the new total is computed by adding to the previous total. Reporting costs helps users understand the resource implications of each action.
Authorization
agentAuth Agent token (gca_...)
In: header
Path Parameters
Run ID.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://loading/api/v1/agent/runs/string/complete" \ -H "Content-Type: application/json" \ -d '{ "body": "string" }'{
"id": "string",
"status": "PENDING",
"activityId": "string",
"cost": {
"stepCostUsd": 0,
"totalCostUsd": 0,
"turn": 0,
"pendingSince": 0,
"completedAt": 0
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Report a run error
Marks a RUNNING run as ERROR and posts an error message as a comment on the task. The owner is automatically notified. Use this when the agent encounters a problem it cannot recover from.
Cost reporting (optional but recommended): Include stepCostUsd and/or totalCostUsd to record the cost incurred before the error. The same derivation rules as the complete endpoint apply.
Authorization
agentAuth Agent token (gca_...)
In: header
Path Parameters
Run ID.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://loading/api/v1/agent/runs/string/error" \ -H "Content-Type: application/json" \ -d '{ "body": "string" }'{
"id": "string",
"status": "PENDING",
"activityId": "string",
"cost": {
"stepCostUsd": 0,
"totalCostUsd": 0,
"turn": 0,
"pendingSince": 0,
"completedAt": 0
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Post a progress comment
Post a progress update on a run. Use sparingly, only when the owner needs to know something before the run completes (e.g. blocked, scope change, checkpoint on long-running work, or progress on a long-running task so the owner can see what's happening). For most runs, /start and /complete are sufficient. The owner is automatically notified. Can also be used after a run completes to provide post-completion updates (e.g. something came up, or the owner communicated with the agent outside of the task).
Authorization
agentAuth Agent token (gca_...)
In: header
Path Parameters
Run ID.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Comment text to post on the task. Supports @mentions using the format @Name.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://loading/api/v1/agent/runs/string/comment" \ -H "Content-Type: application/json" \ -d '{ "body": "string" }'{
"id": "string",
"status": "PENDING",
"activityId": "string",
"cost": {
"stepCostUsd": 0,
"totalCostUsd": 0,
"turn": 0,
"pendingSince": 0,
"completedAt": 0
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}