# Agent: Questions

**Page:** api/agent/questions

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

---

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



## Agent: Questions

The Questions API manages inter-session question requests generated by the AI agent. Use these endpoints to list pending questions, reply with user selections, reject questions, or consult a separate AI model for an automated recommendation.

---

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

Get all pending question requests across all sessions.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
[
  {
    "id": "que_a1b2c3d4e5f6g7h8i9j0k1l2",
    "sessionID": "5f9e3c2a1b8d4f7e6a5b3c2d1e",
    "questions": [
      {
        "question": "Which authentication method should the new service use?",
        "header": "Auth method",
        "options": [
          {
            "label": "OAuth 2.0",
            "description": "Industry standard, supports delegated authorization"
          },
          {
            "label": "API Keys",
            "description": "Simple to implement, ideal for server-to-server"
          },
          {
            "label": "JWT tokens",
            "description": "Stateless, no session storage required"
          }
        ],
        "multiple": false,
        "custom": true
      }
    ],
    "tool": {
      "messageID": "msg_8x7y6z5w4v3u2t1s0r9q8p7o",
      "callID": "call_3a4b5c6d7e8f9g0h1i2j3k4l"
    }
  }
]
```



#### SDK usage

```ts
const questions = await client.agent.questions.list({
  workspaceID: "ws_5f9e3c2a1b8d4f7e6a5b3c2d",
});
```

```bash
curl -X GET "https://api.hoody.com/api/v1/workspaces/ws_5f9e3c2a1b8d4f7e6a5b3c2d/questions" \
  -H "Authorization: Bearer <token>"
```

---

### `POST /api/v1/workspaces/{workspaceID}/questions/{requestID}/consult`

Ask a separate AI model for advice on how to answer a pending question. This is a stateless one-shot call — no session is created and the parent agent is unaware of the consultation.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `requestID` | path | string | Yes | Question request identifier |
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `providerID` | string | Yes | Identifier of the AI provider to consult |
| `modelID` | string | Yes | Identifier of the model to consult |
| `note` | string | No | Additional context for the consultant model |
| `questionIndex` | integer | No | Index of a specific question within the request to consult on (0-based) |
| `system` | string | No | Custom system prompt to guide the consultation |

```json
{
  "providerID": "anthropic",
  "modelID": "claude-sonnet-4-20250514",
  "note": "The project uses a microservices architecture with strict compliance requirements",
  "questionIndex": 0,
  "system": "You are advising on a software architecture decision. Be concise."
}
```

#### Response



```json
{
  "recommendation": ["OAuth 2.0"],
  "reasoning": "OAuth 2.0 provides the strongest security guarantees for a multi-tenant API while supporting future integrations with third-party clients without requiring significant rework.",
  "confidence": "high",
  "usage": {
    "promptTokens": 312,
    "completionTokens": 88,
    "totalTokens": 400
  }
}
```


```json
{
  "data": null,
  "errors": [
    {
      "providerID": "Invalid provider identifier"
    }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Question request que_a1b2c3d4e5f6g7h8i9j0k1l2 not found"
  }
}
```


```json
{
  "error": "Model returned invalid structured output: missing 'confidence' field"
}
```


```json
{
  "error": "Rate limit exceeded for consult endpoint",
  "retryAfterMs": 1500
}
```



#### SDK usage

```ts
const result = await client.agent.questions.consult({
  workspaceID: "ws_5f9e3c2a1b8d4f7e6a5b3c2d",
  requestID: "que_a1b2c3d4e5f6g7h8i9j0k1l2",
  data: {
    providerID: "anthropic",
    modelID: "claude-sonnet-4-20250514",
    note: "The project uses a microservices architecture with strict compliance requirements",
    questionIndex: 0,
    system: "You are advising on a software architecture decision. Be concise.",
  },
});
```

```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/ws_5f9e3c2a1b8d4f7e6a5b3c2d/questions/que_a1b2c3d4e5f6g7h8i9j0k1l2/consult" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "providerID": "anthropic",
    "modelID": "claude-sonnet-4-20250514",
    "note": "The project uses a microservices architecture with strict compliance requirements"
  }'
```

---

### `POST /api/v1/workspaces/{workspaceID}/questions/{requestID}/reject`

Reject a question request from the AI assistant. The request is marked as declined and the originating session is notified.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `requestID` | path | string | Yes | Question request identifier |
| `workspaceID` | path | string | Yes | Workspace identifier |

This endpoint takes no parameters in the path beyond those listed above and accepts no request body.

#### Response



```json
true
```


```json
{
  "data": null,
  "errors": [
    {
      "requestID": "Question request is already resolved"
    }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Question request que_a1b2c3d4e5f6g7h8i9j0k1l2 not found"
  }
}
```



#### SDK usage

```ts
const rejected = await client.agent.questions.reject({
  workspaceID: "ws_5f9e3c2a1b8d4f7e6a5b3c2d",
  requestID: "que_a1b2c3d4e5f6g7h8i9j0k1l2",
});
```

```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/ws_5f9e3c2a1b8d4f7e6a5b3c2d/questions/que_a1b2c3d4e5f6g7h8i9j0k1l2/reject" \
  -H "Authorization: Bearer <token>"
```

---

### `POST /api/v1/workspaces/{workspaceID}/questions/{requestID}/reply`

Provide answers to a question request from the AI assistant. Answers are supplied as an array of selections, ordered to match the questions in the request.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `requestID` | path | string | Yes | Question request identifier |
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `answers` | array | Yes | User answers in order of questions. Each answer is an array of selected `label` strings. |

```json
{
  "answers": [
    ["OAuth 2.0"],
    ["PostgreSQL", "Redis"]
  ]
}
```


Each `answers` entry corresponds to a question in the same order returned by the list endpoint. The inner array contains the `label` values of the selected `options`. When `custom` is enabled on a question, free-text labels may also be provided.


#### Response



```json
true
```


```json
{
  "data": null,
  "errors": [
    {
      "answers": "Number of answers does not match number of questions"
    }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Question request que_a1b2c3d4e5f6g7h8i9j0k1l2 not found"
  }
}
```



#### SDK usage

```ts
const replied = await client.agent.questions.reply({
  workspaceID: "ws_5f9e3c2a1b8d4f7e6a5b3c2d",
  requestID: "que_a1b2c3d4e5f6g7h8i9j0k1l2",
  data: {
    answers: [
      ["OAuth 2.0"],
      ["PostgreSQL", "Redis"],
    ],
  },
});
```

```bash
curl -X POST "https://api.hoody.com/api/v1/workspaces/ws_5f9e3c2a1b8d4f7e6a5b3c2d/questions/que_a1b2c3d4e5f6g7h8i9j0k1l2/reply" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      ["OAuth 2.0"],
      ["PostgreSQL", "Redis"]
    ]
  }'
```