Agent CRUD
Manage agents inside the workspace bound to your API key.
You do not pass workspaceId or userId in the request. The API key scope is applied automatically.
| Header | Required | Description |
|---|
Authorization | Yes | API key in Bearer snorbe_... format |
Content-Type | POST / PATCH only | application/json |
GET /api/v1/agent/
Fetch one agent with full detail.
Response
{
"id": "clxxx123456",
"name": "Research Agent",
"identityMarkdown": "# Identity\nStrong at B2B SaaS market research.",
"userMarkdown": "The user leads a new business team.",
"soulMarkdown": "States hypotheses explicitly and separates evidence from opinion.",
"memoryMarkdown": "- The user often asks for deeper competitor research",
"isDefault": true,
"createdAt": "2026-04-19T00:00:00.000Z",
"updatedAt": "2026-04-19T02:30:00.000Z"
}
POST /api/v1/agent
Create a new agent.
Request Body
{
"name": "Patent Analyst",
"identityMarkdown": "# Identity\nHandles patent research",
"userMarkdown": "",
"soulMarkdown": "",
"memoryMarkdown": "",
"isDefault": false
}
Fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Agent name. Max 100 chars |
identityMarkdown | string | No | Self-introduction. Max 300 chars |
userMarkdown | string | No | User understanding. Max 600 chars |
soulMarkdown | string | No | Persona / SOUL. Max 800 chars |
memoryMarkdown | string | No | Long-term memory. Max 2000 chars |
isDefault | boolean | No | If true, makes this agent the workspace default |
Default behavior
- The first agent in a workspace is automatically created as
isDefault: true
- Creating with
isDefault: true clears the previous default agent in that workspace
PATCH /api/v1/agent/
Partially update an agent. Only provided fields are changed.
Request Body
{
"identityMarkdown": "# Identity\nHandles patents and literature research",
"isDefault": true
}
Notes
- Sending
isDefault: true promotes that agent to the workspace default
- You cannot directly send
isDefault: false for the current default agent. Promote another agent instead
DELETE /api/v1/agent/
Delete an agent. Related AgentRun rows are deleted by cascade.
Default deletion behavior
- If other agents remain, the most recently updated one becomes the new default
- If no agents remain, the workspace ends up with no default agent
Response Fields
POST / GET / PATCH / DELETE all return the same agent object.
| Field | Type | Description |
|---|
id | string | Agent ID |
name | string | Agent name |
identityMarkdown | string | Self-introduction |
userMarkdown | string | User understanding |
soulMarkdown | string | Persona / SOUL |
memoryMarkdown | string | Long-term memory |
isDefault | boolean | Whether this agent is the workspace default |
createdAt | string | Creation timestamp (ISO 8601) |
updatedAt | string | Update timestamp (ISO 8601) |
Examples
curl "https://app.snorbe.deskrex.ai/api/v1/agent/clxxx123456" \
-H "Authorization: Bearer snorbe_your_api_key_here"
curl -X POST "https://app.snorbe.deskrex.ai/api/v1/agent" \
-H "Authorization: Bearer snorbe_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Patent Analyst",
"identityMarkdown": "# Identity\nHandles patent research"
}'
curl -X PATCH "https://app.snorbe.deskrex.ai/api/v1/agent/clxxx123456" \
-H "Authorization: Bearer snorbe_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"isDefault": true
}'
curl -X DELETE "https://app.snorbe.deskrex.ai/api/v1/agent/clxxx123456" \
-H "Authorization: Bearer snorbe_your_api_key_here"
Error Responses
| HTTP Status | Code | Description |
|---|
| 400 | BAD_REQUEST | Invalid input or invalid default-unset attempt |
| 401 | UNAUTHORIZED | Invalid, expired, or missing API key |
| 404 | NOT_FOUND | The agent does not exist inside the API key scope |
| 429 | TOO_MANY_REQUESTS | Rate limit exceeded |
