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

# Filter API response fields with response masks

> Use response masks to control which fields from your API responses are forwarded to the AI model, reducing token usage and preventing data leakage.

`response_mask` is an optional field on API tool definitions that controls which fields from a tool's HTTP response are forwarded to the AI model in subsequent conversation turns.

Without a mask, the full response body is stored in conversation history and re-sent to the model on every turn. For APIs that return large objects — say, a 70+ key flow document — this accumulates quickly and increases both latency and cost. A `response_mask` lets you declare exactly which fields the model needs, discarding the rest before the response enters history.

## Format

The mask is a plain JSON object. Each key corresponds to a field in the response body. The value is either:

* `true` — keep the field's value as-is (any type: scalar, array, nested object)
* A nested mask object — recurse into the field, applying the inner mask

Keys absent from the mask are dropped.

```json theme={null}
{
  "response_mask": {
    "_id": true,
    "last_action_number": true,
    "members": {
      "_id": true,
      "email": true
    },
    "blocks": {
      "block_id": true,
      "type": true,
      "service_item": {
        "title": true,
        "price_per_unit": true
      }
    }
  }
}
```

## Array handling

Arrays are transparent to the mask. When a masked field contains an array, the mask is applied to each element individually. You don't need to declare that a field is an array — the same nested mask works regardless.

```json theme={null}
// Response
{ "blocks": [{ "block_id": "abc", "type": "service", "styles": {} }] }

// Mask
{ "blocks": { "block_id": true, "type": true } }

// Result stored in history
{ "blocks": [{ "block_id": "abc", "type": "service" }] }
```

For arrays of scalars (e.g. `["id1", "id2"]`), use `true` — there's nothing to recurse into:

```json theme={null}
{ "applied_service_charges_ids": true }
```

## Tip: preserve decision fields

Use masks to keep only the fields the model needs for the next decision, especially for large objects like flows or search results. Make sure the mask still includes the fields that distinguish meaningful states such as "found", "not found", and "failed".

For example, for a contact lookup, keep identifiers and user-facing fields like `_id`, `full_name`, and `email`. Avoid masking a response so aggressively that matched objects become `{}` or large responses get truncated before the model can tell what happened.

## Behaviour

| Scenario                                    | Result                                        |
| ------------------------------------------- | --------------------------------------------- |
| `response_mask` omitted                     | No filtering; full response stored in history |
| Field present in mask, present in response  | Field included in history                     |
| Field present in mask, absent in response   | Field silently omitted (no error)             |
| Field absent from mask, present in response | Field dropped from history                    |
| Response is not a JSON object               | Mask is skipped; full response stored         |
| Nested mask on a scalar value               | Scalar returned as-is                         |

Mixed-type arrays — for example, a `blocks` array containing both container blocks and service blocks — are handled naturally. Fields absent from a given element are simply omitted for that element.