# Agents

> The Agents operations of the Hub REST API (5 operations).

URL: https://docs.synap.live/docs/reference/hub-api/agents · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /agent-users

List AI agent users

Returns users with userType='agent' that are members of the requested workspace (or any accessible workspace).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `workspaceId` | query | string |  |  |
| `parentUserId` | query | string |  | Filter agents by agentMetadata.parentAgentId — used by orchestrators to discover their personalities. |

Responses:

- `200`: Agent users
- `403`: Forbidden
- `500`: Internal error

## GET /agent-configs

List agent_configs rows

Returns per-user/per-workspace/per-agentType config overrides. Filter by userId (required), workspaceId (optional), agentType (optional). The caller can only read configs whose userId is themselves OR an agent user whose parentAgentId == caller.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `userId` | query | string | yes | Agent user ID (the personality). |
| `workspaceId` | query | string |  | Workspace ID. If omitted, returns all configs for this userId across workspaces. |
| `agentType` | query | string |  | Free-form agent type slug. If set, narrows to a single row. |

Responses:

- `200`: Array of agent_configs rows
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /channels/trigger-ai

Trigger an AI response in a channel

Posts a system-prompt-overridden message into the channel and dispatches the AI to respond. Used by skill triggers and proactive entry points.

Request body (`application/json`): TriggerAiRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `channelId` | string | yes |  |
| `userId` | string | yes |  |
| `workspaceId` | string | yes |  |
| `systemPromptOverride` | string | yes |  |
| `skillId` | string |  |  |
| `entityId` | string |  | Entity to inject as context for the AI response. |

Responses:

- `200`: Trigger result (varies by skill/agent)
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /discord/agent-turn

Run one orchestrator turn for an inbound Discord message

Resolves-or-creates the Discord-bound channel, records the inbound message, runs ONE Intelligence Service orchestrator turn via streaming accumulation (external actions stay proposal-gated), and returns the agent's reply text synchronously. On pod deadline, returns partial:true with steps collected so far.

Request body (`application/json`): DiscordAgentTurnRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string |  |  |
| `discordChannelId` | string | yes |  |
| `guildId` | string |  |  |
| `discordUserId` | string | yes |  |
| `discordUsername` | string | yes |  |
| `channelKind` | "dm" \| "guild" |  |  |
| `text` | string |  |  |
| `messageId` | string | yes |  |
| `attachments` | array<object> |  |  |
| `skillName` | string |  |  |
| `priority` | "interactive" \| "background" |  |  |

Responses:

- `200`: Agent reply (may be partial with steps when timed out mid-stream)
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /agents/sync

Sync agent registry from IS

Responses:

- `200`: Success
- `401`: Unauthorized
- `403`: Forbidden — missing scope
- `500`: Internal error