RetrieveResponse

​

Purpose (normative)

• permitted content fragments (chunks),
• citation metadata,
• or an explicit denial.

• full articles when disallowed,
• content outside declared limits,
• any advertising or pricing metadata.

​

Canonical schema location

https://schemas.agenticintentprotocol.com/aip/1.0/retrieve-response.schema.json

​

Schema summary

​

Chunk (content.chunks[])

• id - Publisher-defined chunk identifier. Required.
• text - Content text. Required.
• token_count - Optional token count.

​

Citation

• source_url - Canonical URL of the cited source. Required.
• title - Optional source title.
• publisher - Publisher name.
• chunk_ids - IDs of chunks this citation applies to.

​

Denial reasons (canonical)

​

Semantics (important, not optional)

​

Status handling

• ok → Content returned in content.chunks. Citations optional.
• denied → No content returned; denial.reason (and optional message) provided.
• error → Technical failure, not a consent decision; error.code (and optional message).

​

Content rules

• Only chunks may be returned.
• Full articles MUST NOT be returned when full_article: false (per aip.json).
• Returned chunks MUST respect max_chunks and max_tokens from publisher policy.

​

Citation rules

• Citations MUST reference returned chunks.
• Citations MUST be truthful and canonical.
• Citations MUST NOT imply licensing or ownership transfer.

​

Example: Successful response

{
  "aip_version": "1.0",
  "request_id": "req_92fA1",
  "timestamp": "2025-11-14T18:22:01Z",
  "status": "ok",
  "content": {
    "chunks": [
      {
        "id": "c1",
        "text": "CRM tools help small teams manage customer relationships effectively.",
        "token_count": 18
      }
    ]
  },
  "citations": [
    {
      "source_url": "https://forbes.com/crm-guide",
      "title": "Best CRM Tools for Small Teams",
      "publisher": "Forbes",
      "chunk_ids": ["c1"]
    }
  ],
  "limits_applied": {
    "max_chunks": 5,
    "max_tokens": 800
  }
}

​

Example: Denied response

{
  "aip_version": "1.0",
  "request_id": "req_92fA1",
  "timestamp": "2025-11-14T18:22:01Z",
  "status": "denied",
  "denial": {
    "reason": "out_of_scope",
    "message": "Requested intent is outside declared editorial domains."
  }
}

​

Example: Error response

{
  "aip_version": "1.0",
  "request_id": "req_92fA1",
  "timestamp": "2025-11-14T18:22:01Z",
  "status": "error",
  "error": {
    "code": "internal_error",
    "message": "Temporary failure; retry later."
  }
}

​

Why this schema fits

• Directly corresponds to RetrieveRequest.
• Fully enforceable against aip.json.
• No ad-tech contamination.
• Explicit denial semantics.
• Audit-friendly.
• Future-safe via extensions.

​

Schema file

​

See also

• RetrieveRequest - Platform → publisher request that triggers this response.
• aip.json - Publisher Declaration - Declared retrieval limits and editorial_domains.