Skip to main content

​
Purpose (normative)

RetrieveResponse is returned by a publisher’s AIP retrieve endpoint in response to a valid RetrieveRequest. It may return:
  • permitted content fragments (chunks),
  • citation metadata,
  • or an explicit denial.
It MUST NOT return:
  • full articles when disallowed,
  • content outside declared limits,
  • any advertising or pricing metadata.
It is deliberately minimal, rights-preserving, and auditable.

​
Canonical schema location

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

​
Schema summary

FieldTypeRequiredDescription
aip_versionstringYesMust be "0.1".
request_idstringYesEchoes the request_id from the corresponding RetrieveRequest.
timestampstring (date-time)YesISO 8601 timestamp when the response was generated.
statusstringYesok, denied, or error.
contentobjectWhen status is okContains chunks (array of chunk objects).
citationsarrayNoCitation metadata for returned content.
limits_appliedobjectNoPublisher-enforced limits (max_chunks, max_tokens).
denialobjectWhen status is deniedReason and optional message.
errorobjectWhen status is errorCode and optional message (technical failure).
extensionsobjectNoNamespaced extensions.

​
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)

ReasonMeaning
out_of_scopeIntent not in editorial_domains.
access_disabledintent_access.enabled = false or state not active.
policy_violationRequest violated declared constraints.
rate_limitedPublisher throttling.
unsupportedPublisher does not support requested access.

​
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).
A response MUST NOT include both content and denial.

​
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": "0.1",
  "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": "0.1",
  "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": "0.1",
  "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

Full JSON Schema (Draft 2020-12): retrieve-response.json

​
See also