Skip to main content

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.

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. 
{
  "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. 
// 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: 
{ "applied_service_charges_ids": true }

​
Behaviour

ScenarioResult
response_mask omittedNo filtering; full response stored in history
Field present in mask, present in responseField included in history
Field present in mask, absent in responseField silently omitted (no error)
Field absent from mask, present in responseField dropped from history
Response is not a JSON objectMask is skipped; full response stored
Nested mask on a scalar valueScalar 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.