# Agent: Sessions

**Page:** api/agent/sessions

[Download Raw Markdown](./api/agent/sessions.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Agent Sessions API exposes the full lifecycle of an agent session: browsing live sessions, creating and configuring sessions, sending prompts and commands, inspecting messages and parts, managing diffs/todos/tags, and performing session-level actions like abort, revert, fork, summarize, and delete.

All session-scoped operations are keyed by a workspace identifier (`workspaceID` — 24-character lowercase hex) and, where applicable, a session identifier (`sessionID`).

## Sessions wall (HTML)

These endpoints return an HTML view of live agent sessions, intended for iframe embedding in dashboards.

### `GET /api/v1/agent/all`

Alias for `/api/v1/agent/sessions/live`. Renders the HTML sessions wall.



```bash
curl "https://api.hoody.com/api/v1/agent/all?workspace=5f9f5c5e7b1e0c0001a2b3c4&limit=50"
```


```ts
await client.agent.sessions.listAll({
  workspace: "5f9f5c5e7b1e0c0001a2b3c4",
  limit: "50",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspace` | query | string | No | |
| `directory` | query | string | No | |
| `readonly` | query | string | No | |
| `read_only` | query | string | No | |
| `cardWidth` | query | string | No | |
| `limit` | query | string | No | |
| `sub` | query | string | No | |
| `archived` | query | string | No | |
| `containerId` | query | string | No | |
| `projectId` | query | string | No | |
| `serverNode` | query | string | No | |
| `containerAlias` | query | string | No | |

### Response



Returns an HTML page representing the sessions wall.



---

### `GET /api/v1/agent/sessions/live`

Renders an HTML page showing live agent sessions, designed for iframe embedding.



```bash
curl "https://api.hoody.com/api/v1/agent/sessions/live?workspace=5f9f5c5e7b1e0c0001a2b3c4"
```


```ts
await client.agent.sessions.listLive({
  workspace: "5f9f5c5e7b1e0c0001a2b3c4",
});
```



### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspace` | query | string | No | — |
| `directory` | query | string | No | — |
| `readonly` | query | string | No | — |
| `read_only` | query | string | No | — |
| `cardWidth` | query | string | No | — |
| `limit` | query | string | No | — |
| `sub` | query | string | No | — |
| `archived` | query | string | No | — |
| `containerId` | query | string | No | — |
| `projectId` | query | string | No | — |
| `serverNode` | query | string | No | — |
| `containerAlias` | query | string | No | — |


### Response



Returns an HTML page representing the sessions wall.



---

## List and inspect sessions

### `GET /api/v1/workspaces/{workspaceID}/sessions`

Returns a paginated list of all sessions in a workspace, newest-first by session ID.



```bash
curl "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions?page=1&limit=50&roots=true"
```


```ts
await client.agent.sessions.list({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  page: 1,
  limit: 50,
  roots: true,
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `page` | query | integer | No | Page number (1-indexed). Default: `1` |
| `limit` | query | integer | No | Items per page (max 200). Default: `50` |
| `roots` | query | boolean | No | Only return root sessions (no parentID) |
| `search` | query | string | No | Filter by title (case-insensitive) |

### Response



```json
{
  "items": [
    {
      "id": "5fa1bd2e9c1d2c0001b2a3f4",
      "slug": "refactor-auth-flow",
      "projectID": "5f9f5c5e7b1e0c0001a2b3c4",
      "directory": "/home/user/projects/app",
      "parentID": null,
      "summary": {
        "additions": 142,
        "deletions": 38,
        "files": 7,
        "diffs": []
      },
      "title": "Refactor auth flow",
      "version": "v1.2.3",
      "time": {
        "created": 1731000000000,
        "updated": 1731000450000,
        "compacting": 0,
        "archived": 0
      },
      "permission": [
        { "permission": "edit", "pattern": "*", "action": "allow" }
      ],
      "metadata": {},
      "revert": {
        "messageID": "msg_01HXY...",
        "partID": "prt_01HXY...",
        "snapshot": "snap_abc",
        "diff": "diff --git ..."
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 124,
    "pages": 3
  }
}
```



---

### `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}`

Retrieve a single session by ID within the workspace.



```bash
curl "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123"
```


```ts
await client.agent.sessions.get({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Response



```json
{
  "id": "5fa1bd2e9c1d2c0001b2a3f4",
  "slug": "refactor-auth-flow",
  "projectID": "5f9f5c5e7b1e0c0001a2b3c4",
  "directory": "/home/user/projects/app",
  "parentID": null,
  "summary": {
    "additions": 142,
    "deletions": 38,
    "files": 7,
    "diffs": []
  },
  "title": "Refactor auth flow",
  "version": "v1.2.3",
  "time": {
    "created": 1731000000000,
    "updated": 1731000450000,
    "compacting": 0,
    "archived": 0
  },
  "permission": [
    { "permission": "edit", "pattern": "*", "action": "allow" }
  ],
  "metadata": {
    "featureFlag": "auth-v2"
  },
  "revert": {
    "messageID": "msg_01HXY...",
    "partID": "prt_01HXY...",
    "snapshot": "snap_abc",
    "diff": "diff --git a/..."
  }
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/children`

Retrieve all sessions forked from the specified parent.



```bash
curl "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/children"
```


```ts
await client.agent.sessions.getChildren({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Response



```json
{
  "items": [
    {
      "id": "5fa1bd2e9c1d2c0001b2a3f5",
      "slug": "refactor-auth-flow-experiment-1",
      "projectID": "5f9f5c5e7b1e0c0001a2b3c4",
      "directory": "/home/user/projects/app",
      "parentID": "5fa1bd2e9c1d2c0001b2a3f4",
      "summary": {
        "additions": 24,
        "deletions": 10,
        "files": 2,
        "diffs": []
      },
      "title": "Refactor auth flow — experiment 1",
      "version": "v1.2.3",
      "time": {
        "created": 1731000500000,
        "updated": 1731000700000,
        "compacting": 0,
        "archived": 0
      },
      "permission": [
        { "permission": "edit", "pattern": "*", "action": "ask" }
      ],
      "metadata": {},
      "revert": {
        "messageID": "msg_01HXY..."
      }
    }
  ]
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `GET /api/v1/workspaces/{workspaceID}/sessions/status`

Retrieve the current status of every session in the workspace (active, idle, retry, busy).



```bash
curl "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/status"
```


```ts
await client.agent.sessions.getStatuses({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |

### Response



```json
{
  "ses_01HXY123": { "type": "busy" },
  "ses_01HXY124": { "type": "idle" },
  "ses_01HXY125": {
    "type": "retry",
    "attempt": 2,
    "message": "Provider returned 503",
    "next": 1731000800000
  }
}
```



---

## Session insights: summary, diff, todos, tags

### `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/summary`

Retrieve a lightweight summary: title, token/cost totals, file change stats, and the last message snippet. `O(messages)` reads with no AI call triggered.



```bash
curl "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/summary"
```


```ts
await client.agent.sessions.getSummary({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Response



```json
{
  "sessionID": "ses_01HXY123",
  "title": "Refactor auth flow",
  "messageCount": 42,
  "tokens": {
    "total": 87420,
    "input": 41200,
    "output": 30120,
    "reasoning": 9100,
    "cache": {
      "read": 3800,
      "write": 5200
    }
  },
  "cost": 0.1842,
  "files": 7,
  "additions": 142,
  "deletions": 38,
  "lastMessage": {
    "role": "assistant",
    "snippet": "I've finished wiring the OAuth callback handler.",
    "time": 1731000450000
  },
  "time": {
    "created": 1731000000000,
    "updated": 1731000450000
  }
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/diff`

Get file changes (diffs) resulting from the session. Optionally scope the diff to a specific message.



```bash
curl "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/diff?messageID=msg_01HXY..."
```


```ts
await client.agent.sessions.getDiff({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  messageID: "msg_01HXY...",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |
| `messageID` | query | string | No | Optional message cursor for message-scoped diff |

### Response



```json
[
  {
    "file": "src/auth/callback.ts",
    "before": "export const handler = (req, res) => { /* old */ }",
    "after": "export const handler = async (req, res) => { /* new */ }",
    "additions": 24,
    "deletions": 10,
    "status": "modified"
  },
  {
    "file": "src/auth/oauth.ts",
    "before": "",
    "after": "export const config = { provider: 'github' }",
    "additions": 12,
    "deletions": 0,
    "status": "added"
  }
]
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/todo`

Retrieve the todo list associated with a session.



```bash
curl "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/todo"
```


```ts
await client.agent.sessions.getTodo({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Response



```json
[
  {
    "id": "todo_01HXY...",
    "content": "Migrate callback handler to async/await",
    "status": "completed",
    "priority": "high"
  },
  {
    "id": "todo_01HXY...",
    "content": "Add integration test for OAuth refresh",
    "status": "in_progress",
    "priority": "medium"
  },
  {
    "id": "todo_01HXY...",
    "content": "Document the new env vars",
    "status": "pending",
    "priority": "low"
  }
]
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `PATCH /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/tags`

Replace the MITM tags on a session. This surface and `/mitm/sessions/{sessionID}/tags` share the same canonical-equality fast path.



```bash
curl -X PATCH "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/tags" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["needs-review", "security", "v2"]
  }'
```


```ts
await client.agent.sessions.updateTags({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: {
    tags: ["needs-review", "security", "v2"],
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tags` | array | Yes | |

```json
{
  "tags": ["needs-review", "security", "v2"]
}
```

### Response



```json
{
  "id": "5fa1bd2e9c1d2c0001b2a3f4",
  "slug": "refactor-auth-flow",
  "projectID": "5f9f5c5e7b1e0c0001a2b3c4",
  "directory": "/home/user/projects/app",
  "parentID": null,
  "summary": {
    "additions": 142,
    "deletions": 38,
    "files": 7,
    "diffs": []
  },
  "title": "Refactor auth flow",
  "version": "v1.2.3",
  "time": {
    "created": 1731000000000,
    "updated": 1731000800000,
    "compacting": 0,
    "archived": 0
  },
  "permission": [
    { "permission": "edit", "pattern": "*", "action": "allow" }
  ],
  "metadata": {},
  "revert": {
    "messageID": "msg_01HXY..."
  }
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "tags", "message": "tags must be an array of strings" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

## Session messages

### `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/messages`

Retrieve messages from a session, oldest first. Use the `after` cursor parameter for incremental polling.



```bash
curl "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/messages?limit=20&role=assistant&after=msg_01HXY..."
```


```ts
await client.agent.sessions.listMessages({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  limit: 20,
  role: "assistant",
  after: "msg_01HXY...",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |
| `limit` | query | integer | No | Maximum messages to return |
| `role` | query | string | No | Filter by role. Allowed values: `user`, `assistant` |
| `after` | query | string | No | Cursor: only return messages with ID strictly greater than this (newer) |

### Response



```json
[
  {
    "info": {
      "id": "msg_01HXY...",
      "sessionID": "ses_01HXY123",
      "role": "user",
      "time": { "created": 1731000000000 },
      "summary": { "diffs": [] },
      "agent": "build",
      "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet" },
      "system": "You are a helpful coding assistant.",
      "tools": { "bash": true, "edit": true },
      "variant": "max"
    },
    "parts": [
      {
        "id": "prt_01HXY...",
        "sessionID": "ses_01HXY123",
        "messageID": "msg_01HXY...",
        "type": "text",
        "text": "Refactor the auth callback to be async.",
        "time": { "start": 1731000000000 }
      }
    ]
  },
  {
    "info": {
      "id": "msg_01HXY...",
      "sessionID": "ses_01HXY123",
      "role": "assistant",
      "time": { "created": 1731000005000, "completed": 1731000030000 },
      "parentID": "msg_01HXY...",
      "modelID": "claude-3-5-sonnet",
      "providerID": "anthropic",
      "mode": "build",
      "agent": "build",
      "path": { "cwd": "/home/user/projects/app", "root": "/home/user/projects/app" },
      "cost": 0.0124,
      "tokens": {
        "input": 412,
        "output": 220,
        "reasoning": 80,
        "cache": { "read": 120, "write": 40 }
      }
    },
    "parts": [
      {
        "id": "prt_01HXY...",
        "sessionID": "ses_01HXY123",
        "messageID": "msg_01HXY...",
        "type": "text",
        "text": "I'll refactor the auth callback handler."
      }
    ]
  }
]
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/messages/{messageID}`

Retrieve a specific message from a session, including all of its parts.



```bash
curl "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/messages/msg_01HXY..."
```


```ts
await client.agent.sessions.getMessage({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  messageID: "msg_01HXY...",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |
| `messageID` | path | string | Yes | |

### Response



```json
{
  "info": {
    "id": "msg_01HXY...",
    "sessionID": "ses_01HXY123",
    "role": "assistant",
    "time": { "created": 1731000005000, "completed": 1731000030000 },
    "parentID": "msg_01HXY...",
    "modelID": "claude-3-5-sonnet",
    "providerID": "anthropic",
    "mode": "build",
    "agent": "build",
    "path": { "cwd": "/home/user/projects/app", "root": "/home/user/projects/app" },
    "cost": 0.0124,
    "tokens": {
      "input": 412,
      "output": 220,
      "reasoning": 80,
      "cache": { "read": 120, "write": 40 }
    }
  },
  "parts": [
    {
      "id": "prt_01HXY...",
      "sessionID": "ses_01HXY123",
      "messageID": "msg_01HXY...",
      "type": "text",
      "text": "I'll refactor the auth callback handler."
    },
    {
      "id": "prt_01HXY...",
      "sessionID": "ses_01HXY123",
      "messageID": "msg_01HXY...",
      "type": "step-finish",
      "reason": "stop",
      "cost": 0.0124,
      "tokens": {
        "input": 412,
        "output": 220,
        "reasoning": 80,
        "cache": { "read": 120, "write": 40 }
      }
    }
  ]
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Message not found"
  }
}
```



---

### `PATCH /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/message/{messageID}`

Update mutable fields on a user message — for example, switching the model while retrying.



```bash
curl -X PATCH "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/message/msg_01HXY..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet" }
  }'
```


```ts
await client.agent.sessions.updateMessage({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  messageID: "msg_01HXY...",
  data: {
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet" },
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |
| `messageID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `model` | object | Yes | `providerID` and `modelID` (both required) |

```json
{
  "model": {
    "providerID": "anthropic",
    "modelID": "claude-3-5-sonnet"
  }
}
```

### Response



```json
{
  "info": {
    "id": "msg_01HXY...",
    "sessionID": "ses_01HXY123",
    "role": "user",
    "time": { "created": 1731000000000 },
    "agent": "build",
    "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet" }
  },
  "parts": [
    {
      "id": "prt_01HXY...",
      "sessionID": "ses_01HXY123",
      "messageID": "msg_01HXY...",
      "type": "text",
      "text": "Refactor the auth callback to be async."
    }
  ]
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "model.modelID", "message": "modelID is required" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Message not found"
  }
}
```



---

## Session parts

### `PATCH /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/message/{messageID}/part/{partID}`

Update a part attached to a message.



```bash
curl -X PATCH "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/message/msg_01HXY.../part/prt_01HXY..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "prt_01HXY...",
    "sessionID": "ses_01HXY123",
    "messageID": "msg_01HXY...",
    "type": "text",
    "text": "Updated text content"
  }'
```


```ts
await client.agent.sessions.updatePart({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  messageID: "msg_01HXY...",
  partID: "prt_01HXY...",
  data: {
    id: "prt_01HXY...",
    sessionID: "ses_01HXY123",
    messageID: "msg_01HXY...",
    type: "text",
    text: "Updated text content",
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |
| `messageID` | path | string | Yes | |
| `partID` | path | string | Yes | Part ID |

### Request Body

The request body matches the `Part` schema (a tagged union of `TextPart`, `SubtaskPart`, `ReasoningPart`, `FilePart`, `ToolPart`, `JobResultPart`, `StepStartPart`, `StepFinishPart`, `SnapshotPart`, `PatchPart`, `AgentPart`, `RetryPart`, `CompactionPart`).

```json
{
  "id": "prt_01HXY...",
  "sessionID": "ses_01HXY123",
  "messageID": "msg_01HXY...",
  "type": "text",
  "text": "Updated text content"
}
```

### Response



```json
{
  "id": "prt_01HXY...",
  "sessionID": "ses_01HXY123",
  "messageID": "msg_01HXY...",
  "type": "text",
  "text": "Updated text content",
  "time": { "start": 1731000000000 }
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "type", "message": "unsupported part type" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Part not found"
  }
}
```



---

### `DELETE /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/message/{messageID}/part/{partID}`

Delete a part from a message.



```bash
curl -X DELETE "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/message/msg_01HXY.../part/prt_01HXY..."
```


```ts
await client.agent.sessions.deletePart({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  messageID: "msg_01HXY...",
  partID: "prt_01HXY...",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |
| `messageID` | path | string | Yes | |
| `partID` | path | string | Yes | Part ID |

### Response



```json
true
```


```json
{
  "data": null,
  "errors": [
    { "path": "partID", "message": "partID is malformed" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Part not found"
  }
}
```



---

## Create, update, delete sessions

### `POST /api/v1/workspaces/{workspaceID}/sessions`

Create a new session in the workspace. Pass a `parentID` to fork from an existing session.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Investigate flaky CI test",
    "permission": [
      { "permission": "edit", "pattern": "*", "action": "ask" }
    ],
    "metadata": { "priority": "high" }
  }'
```


```ts
await client.agent.sessions.create({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  data: {
    title: "Investigate flaky CI test",
    permission: [
      { permission: "edit", pattern: "*", action: "ask" },
    ],
    metadata: { priority: "high" },
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `parentID` | string | No | Must match `^[0-9a-f]{24}$` |
| `title` | string | No | |
| `permission` | array | No | `PermissionRuleset` — array of `{ permission, pattern, action }` |
| `metadata` | object | No | Free-form key/value map |

```json
{
  "title": "Investigate flaky CI test",
  "permission": [
    { "permission": "edit", "pattern": "*", "action": "ask" }
  ],
  "metadata": { "priority": "high" }
}
```

### Response



```json
{
  "id": "5fa1bd2e9c1d2c0001b2a3f6",
  "slug": "investigate-flaky-ci-test",
  "projectID": "5f9f5c5e7b1e0c0001a2b3c4",
  "directory": "/home/user/projects/app",
  "parentID": null,
  "summary": {
    "additions": 0,
    "deletions": 0,
    "files": 0,
    "diffs": []
  },
  "title": "Investigate flaky CI test",
  "version": "v1.2.3",
  "time": {
    "created": 1731000900000,
    "updated": 1731000900000,
    "compacting": 0,
    "archived": 0
  },
  "permission": [
    { "permission": "edit", "pattern": "*", "action": "ask" }
  ],
  "metadata": { "priority": "high" },
  "revert": {
    "messageID": "msg_01HXY..."
  }
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "parentID", "message": "parentID must match ^[0-9a-f]{24}$" }
  ],
  "success": false
}
```



---

### `PATCH /api/v1/workspaces/{workspaceID}/sessions/{sessionID}`

Update session-level properties: `title`, `time.archived`, and/or `permission`.

The `permission` field is a session-scoped ruleset merged on top of `config.permission` at evaluation time (last-match-wins).

- Pass `permission: []` to clear session overrides (keeps the field).
- Pass `permission: null` to remove the field entirely (revert to config defaults).
- Omit `permission` to leave the existing rules untouched.



```bash
curl -X PATCH "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refactor auth flow (renamed)",
    "time": { "archived": 0 },
    "permission": [
      { "permission": "edit", "pattern": "src/auth/**", "action": "ask" }
    ]
  }'
```


```ts
await client.agent.sessions.update({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: {
    title: "Refactor auth flow (renamed)",
    time: { archived: 0 },
    permission: [
      { permission: "edit", pattern: "src/auth/**", action: "ask" },
    ],
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `title` | string | No | New session title (min length 1) |
| `time` | object | No | Timestamp fields to update. Contains `archived` (ms since epoch, or `0` to unarchive) |
| `permission` | array \| null | No | Session-scoped ruleset. `[]` clears overrides; `null` removes the field |

```json
{
  "title": "Refactor auth flow (renamed)",
  "time": { "archived": 0 },
  "permission": [
    { "permission": "edit", "pattern": "src/auth/**", "action": "ask" }
  ]
}
```

### Response



```json
{
  "id": "5fa1bd2e9c1d2c0001b2a3f4",
  "slug": "refactor-auth-flow-renamed",
  "projectID": "5f9f5c5e7b1e0c0001a2b3c4",
  "directory": "/home/user/projects/app",
  "parentID": null,
  "summary": {
    "additions": 142,
    "deletions": 38,
    "files": 7,
    "diffs": []
  },
  "title": "Refactor auth flow (renamed)",
  "version": "v1.2.3",
  "time": {
    "created": 1731000000000,
    "updated": 1731001000000,
    "compacting": 0,
    "archived": 0
  },
  "permission": [
    { "permission": "edit", "pattern": "src/auth/**", "action": "ask" }
  ],
  "metadata": {},
  "revert": {
    "messageID": "msg_01HXY..."
  }
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "permission", "message": "permission must be an array, null, or omitted" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `DELETE /api/v1/workspaces/{workspaceID}/sessions/{sessionID}`

Delete a session and all associated data. This action is irreversible.



```bash
curl -X DELETE "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123"
```


```ts
await client.agent.sessions.delete({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Response



```json
true
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

## Session actions

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/message`

Send a message to a session, streaming the AI response.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/message" \
  -H "Content-Type: application/json" \
  -d '{
    "messageID": "msg_01HXY...",
    "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet" },
    "agent": "build",
    "system": "Be concise.",
    "parts": [
      { "type": "text", "text": "Add a retry policy to the HTTP client." }
    ]
  }'
```


```ts
await client.agent.sessions.prompt({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: {
    messageID: "msg_01HXY...",
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet" },
    agent: "build",
    system: "Be concise.",
    parts: [
      { type: "text", text: "Add a retry policy to the HTTP client." },
    ],
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `messageID` | string | No | Matches `^msg.*` |
| `model` | object | No | `providerID` and `modelID` (both required when present) |
| `agent` | string | No | |
| `noReply` | boolean | No | |
| `tools` | object | No | Deprecated — set `permission` on the session instead. Map of tool name to boolean |
| `system` | string | No | |
| `variant` | string | No | |
| `parts` | array | Yes | Array of `TextPartInput`, `FilePartInput`, `AgentPartInput`, or `SubtaskPartInput` |

```json
{
  "messageID": "msg_01HXY...",
  "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet" },
  "agent": "build",
  "system": "Be concise.",
  "parts": [
    { "type": "text", "text": "Add a retry policy to the HTTP client." }
  ]
}
```

### Response



```json
{
  "info": {
    "id": "msg_01HXY...",
    "sessionID": "ses_01HXY123",
    "role": "assistant",
    "time": { "created": 1731001000000, "completed": 1731001030000 },
    "parentID": "msg_01HXY...",
    "modelID": "claude-3-5-sonnet",
    "providerID": "anthropic",
    "mode": "build",
    "agent": "build",
    "path": { "cwd": "/home/user/projects/app", "root": "/home/user/projects/app" },
    "cost": 0.0242,
    "tokens": {
      "input": 612,
      "output": 320,
      "reasoning": 110,
      "cache": { "read": 80, "write": 40 }
    }
  },
  "parts": [
    {
      "id": "prt_01HXY...",
      "sessionID": "ses_01HXY123",
      "messageID": "msg_01HXY...",
      "type": "text",
      "text": "I'll add a retry policy to the HTTP client."
    }
  ]
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "parts", "message": "parts must be a non-empty array" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/prompt_async`

Send a message to a session asynchronously. The endpoint returns immediately after the prompt is accepted; stream the response separately.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/prompt_async" \
  -H "Content-Type: application/json" \
  -d '{
    "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet" },
    "agent": "build",
    "parts": [
      { "type": "text", "text": "Add a retry policy to the HTTP client." }
    ]
  }'
```


```ts
await client.agent.sessions.promptAsync({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: {
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet" },
    agent: "build",
    parts: [
      { type: "text", text: "Add a retry policy to the HTTP client." },
    ],
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `messageID` | string | No | Matches `^msg.*` |
| `model` | object | No | `providerID` and `modelID` (both required when present) |
| `agent` | string | No | |
| `noReply` | boolean | No | |
| `tools` | object | No | Deprecated — set `permission` on the session instead. Map of tool name to boolean |
| `system` | string | No | |
| `variant` | string | No | |
| `parts` | array | Yes | Array of `TextPartInput`, `FilePartInput`, `AgentPartInput`, or `SubtaskPartInput` |

```json
{
  "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet" },
  "agent": "build",
  "parts": [
    { "type": "text", "text": "Add a retry policy to the HTTP client." }
  ]
}
```

### Response



The prompt was accepted. The session processes the message in the background.


```json
{
  "data": null,
  "errors": [
    { "path": "parts", "message": "parts must be a non-empty array" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/command`

Send a slash command to a session for execution by the AI assistant.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/command" \
  -H "Content-Type: application/json" \
  -d '{
    "messageID": "msg_01HXY...",
    "agent": "build",
    "model": "claude-3-5-sonnet",
    "command": "init",
    "arguments": "scan the repo"
  }'
```


```ts
await client.agent.sessions.command({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: {
    messageID: "msg_01HXY...",
    agent: "build",
    model: "claude-3-5-sonnet",
    command: "init",
    arguments: "scan the repo",
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `messageID` | string | No | Matches `^msg.*` |
| `agent` | string | No | |
| `model` | string | No | |
| `arguments` | string | Yes | |
| `command` | string | Yes | |
| `variant` | string | No | |
| `parts` | array | No | Array of file parts (`type: "file"`, `mime`, `url` required) |

```json
{
  "messageID": "msg_01HXY...",
  "agent": "build",
  "model": "claude-3-5-sonnet",
  "command": "init",
  "arguments": "scan the repo"
}
```

### Response



```json
{
  "info": {
    "id": "msg_01HXY...",
    "sessionID": "ses_01HXY123",
    "role": "assistant",
    "time": { "created": 1731001100000, "completed": 1731001130000 },
    "parentID": "msg_01HXY...",
    "modelID": "claude-3-5-sonnet",
    "providerID": "anthropic",
    "mode": "build",
    "agent": "build",
    "path": { "cwd": "/home/user/projects/app", "root": "/home/user/projects/app" },
    "cost": 0.0184,
    "tokens": {
      "input": 480,
      "output": 240,
      "reasoning": 60,
      "cache": { "read": 60, "write": 30 }
    }
  },
  "parts": [
    {
      "id": "prt_01HXY...",
      "sessionID": "ses_01HXY123",
      "messageID": "msg_01HXY...",
      "type": "text",
      "text": "Running /init..."
    }
  ]
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "command", "message": "command is required" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/shell`

Execute a shell command within the session context. Returns the assistant's response.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/shell" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "build",
    "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet" },
    "command": "ls -la src/auth"
  }'
```


```ts
await client.agent.sessions.shell({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: {
    agent: "build",
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet" },
    command: "ls -la src/auth",
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `agent` | string | Yes | |
| `model` | object | No | `providerID` and `modelID` (both required when present) |
| `command` | string | Yes | |

```json
{
  "agent": "build",
  "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet" },
  "command": "ls -la src/auth"
}
```

### Response



```json
{
  "id": "msg_01HXY...",
  "sessionID": "ses_01HXY123",
  "role": "assistant",
  "time": { "created": 1731001200000, "completed": 1731001210000 },
  "parentID": "msg_01HXY...",
  "modelID": "claude-3-5-sonnet",
  "providerID": "anthropic",
  "mode": "build",
  "agent": "build",
  "path": { "cwd": "/home/user/projects/app", "root": "/home/user/projects/app" },
  "cost": 0.0042,
  "tokens": {
    "input": 220,
    "output": 60,
    "reasoning": 0,
    "cache": { "read": 20, "write": 10 }
  }
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "command", "message": "command is required" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/fork`

Create a new session forked at a specific message point. The new session starts empty but inherits state up to `messageID`.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/fork" \
  -H "Content-Type: application/json" \
  -d '{ "messageID": "msg_01HXY..." }'
```


```ts
await client.agent.sessions.fork({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: { messageID: "msg_01HXY..." },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `messageID` | string | No | Matches `^msg.*`. If omitted, the new session forks at the latest message |

```json
{
  "messageID": "msg_01HXY..."
}
```

### Response



```json
{
  "id": "5fa1bd2e9c1d2c0001b2a3f7",
  "slug": "refactor-auth-flow-fork-1",
  "projectID": "5f9f5c5e7b1e0c0001a2b3c4",
  "directory": "/home/user/projects/app",
  "parentID": "5fa1bd2e9c1d2c0001b2a3f4",
  "summary": {
    "additions": 0,
    "deletions": 0,
    "files": 0,
    "diffs": []
  },
  "title": "Refactor auth flow (fork)",
  "version": "v1.2.3",
  "time": {
    "created": 1731001300000,
    "updated": 1731001300000,
    "compacting": 0,
    "archived": 0
  },
  "permission": [
    { "permission": "edit", "pattern": "*", "action": "ask" }
  ],
  "metadata": {},
  "revert": {
    "messageID": "msg_01HXY..."
  }
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "messageID", "message": "messageID must match ^msg.*" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Source session not found"
  }
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/revert`

Revert a session to a specific message, undoing all subsequent changes.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/revert" \
  -H "Content-Type: application/json" \
  -d '{
    "messageID": "msg_01HXY...",
    "partID": "prt_01HXY..."
  }'
```


```ts
await client.agent.sessions.revert({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: {
    messageID: "msg_01HXY...",
    partID: "prt_01HXY...",
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `messageID` | string | Yes | Matches `^msg.*` |
| `partID` | string | No | Matches `^prt.*` |

```json
{
  "messageID": "msg_01HXY...",
  "partID": "prt_01HXY..."
}
```

### Response



```json
{
  "id": "5fa1bd2e9c1d2c0001b2a3f4",
  "slug": "refactor-auth-flow",
  "projectID": "5f9f5c5e7b1e0c0001a2b3c4",
  "directory": "/home/user/projects/app",
  "parentID": null,
  "summary": {
    "additions": 0,
    "deletions": 0,
    "files": 0,
    "diffs": []
  },
  "title": "Refactor auth flow",
  "version": "v1.2.3",
  "time": {
    "created": 1731000000000,
    "updated": 1731001400000,
    "compacting": 0,
    "archived": 0
  },
  "permission": [
    { "permission": "edit", "pattern": "*", "action": "ask" }
  ],
  "metadata": {},
  "revert": {
    "messageID": "msg_01HXY...",
    "partID": "prt_01HXY...",
    "snapshot": "snap_abc",
    "diff": "diff --git a/..."
  }
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "messageID", "message": "messageID is required" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/unrevert`

Restore all messages that were previously reverted.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/unrevert"
```


```ts
await client.agent.sessions.unrevert({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Response



```json
{
  "id": "5fa1bd2e9c1d2c0001b2a3f4",
  "slug": "refactor-auth-flow",
  "projectID": "5f9f5c5e7b1e0c0001a2b3c4",
  "directory": "/home/user/projects/app",
  "parentID": null,
  "summary": {
    "additions": 142,
    "deletions": 38,
    "files": 7,
    "diffs": []
  },
  "title": "Refactor auth flow",
  "version": "v1.2.3",
  "time": {
    "created": 1731000000000,
    "updated": 1731001500000,
    "compacting": 0,
    "archived": 0
  },
  "permission": [
    { "permission": "edit", "pattern": "*", "action": "ask" }
  ],
  "metadata": {},
  "revert": {
    "messageID": "msg_01HXY..."
  }
}
```


```json
{
  "data": null,
  "errors": [
    { "path": "session", "message": "no prior revert to restore" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/abort`

Abort any in-progress AI processing for the session.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/abort"
```


```ts
await client.agent.sessions.abort({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Response



```json
true
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/summarize`

Generate a concise summary of the session using AI compaction. Use `auto: true` to run compaction automatically.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/summarize" \
  -H "Content-Type: application/json" \
  -d '{
    "providerID": "anthropic",
    "modelID": "claude-3-5-sonnet",
    "auto": false,
    "systemPrompt": "Summarize concisely."
  }'
```


```ts
await client.agent.sessions.summarize({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: {
    providerID: "anthropic",
    modelID: "claude-3-5-sonnet",
    auto: false,
    systemPrompt: "Summarize concisely.",
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `providerID` | string | Yes | |
| `modelID` | string | Yes | |
| `auto` | boolean | No | Default: `false` |
| `systemPrompt` | string | No | |

```json
{
  "providerID": "anthropic",
  "modelID": "claude-3-5-sonnet",
  "auto": false,
  "systemPrompt": "Summarize concisely."
}
```

### Response



```json
true
```


```json
{
  "data": null,
  "errors": [
    { "path": "modelID", "message": "modelID is required" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```


```json
{
  "error": "Session is busy",
  "code": "session_busy"
}
```




The 409 response includes an optional `code` field that discriminates sub-cases such as `loop_already_active`, `session_busy`, and `loop_install_aborted`, so SDK consumers don't have to regex-match human messages.


---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/init`

Trigger AI-based workspace analysis to generate or update an `AGENTS.md` configuration file.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/init" \
  -H "Content-Type: application/json" \
  -d '{
    "providerID": "anthropic",
    "modelID": "claude-3-5-sonnet",
    "messageID": "msg_01HXY..."
  }'
```


```ts
await client.agent.sessions.init({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
  data: {
    providerID: "anthropic",
    modelID: "claude-3-5-sonnet",
    messageID: "msg_01HXY...",
  },
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `modelID` | string | Yes | |
| `providerID` | string | Yes | |
| `messageID` | string | Yes | Matches `^msg.*` |

```json
{
  "providerID": "anthropic",
  "modelID": "claude-3-5-sonnet",
  "messageID": "msg_01HXY..."
}
```

### Response



```json
true
```


```json
{
  "data": null,
  "errors": [
    { "path": "messageID", "message": "messageID is required" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/export`

Export a session in Markdown, JSON, or Plain Text format.



```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/5f9f5c5e7b1e0c0001a2b3c4/sessions/ses_01HXY123/export" \
  -H "Accept: text/markdown"
```


```ts
await client.agent.sessions.export({
  workspaceID: "5f9f5c5e7b1e0c0001a2b3c4",
  sessionID: "ses_01HXY123",
});
```



### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier (project ID or workspace entry ID; 24-char lowercase hex) |
| `sessionID` | path | string | Yes | |

### Response



Returns the exported session content. The response content type depends on the request's `Accept` header (`text/markdown`, `application/json`, or `text/plain`).


```json
{
  "data": null,
  "errors": [
    { "path": "Accept", "message": "unsupported content type" }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Session not found"
  }
}
```




The export format is selected via the request's `Accept` header: `text/markdown` (default), `application/json`, or `text/plain`. Compression options and per-format content selection are configured on the request via the same Accept negotiation surface.