> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snorbe.deskrex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent CRUD

> Create, fetch, update, and delete agents with an API key

# Agent CRUD

Manage agents inside the workspace bound to your API key.

<Note>
  You do not pass `workspaceId` or `userId` in the request. The API key scope is applied automatically.
</Note>

## Common Headers

| Header          | Required          | Description                           |
| --------------- | ----------------- | ------------------------------------- |
| `Authorization` | Yes               | API key in `Bearer snorbe_...` format |
| `Content-Type`  | POST / PATCH only | `application/json`                    |

## GET /api/v1/agent/{agentId}

Fetch one agent with full detail.

### Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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/{agentId}

Partially update an agent. Only provided fields are changed.

### Request Body

```json theme={null}
{
  "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/{agentId}

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```typescript TypeScript theme={null}
  const headers = {
    Authorization: "Bearer snorbe_your_api_key_here",
    "Content-Type": "application/json",
  };

  const created = await fetch("https://app.snorbe.deskrex.ai/api/v1/agent", {
    method: "POST",
    headers,
    body: JSON.stringify({
      name: "Patent Analyst",
      identityMarkdown: "# Identity\nHandles patent research",
    }),
  }).then((resp) => resp.json());

  await fetch(`https://app.snorbe.deskrex.ai/api/v1/agent/${created.id}`, {
    method: "PATCH",
    headers,
    body: JSON.stringify({ isDefault: true }),
  });
  ```
</CodeGroup>

## 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                               |