Skip to main content

​
Purpose (normative)

RetrieveRequest is a platform-declared, permissioned request sent by an AI platform to a publisher’s AIP retrieve endpoint to access content in response to a live user query. It is intentionally separate from PlatformRequest and ContextRequest. No ads. No bidding. No operator semantics. Only permissioned retrieval. It is evaluated against:
  • aip.json
  • editorial_domains
  • publisher policy

​
Canonical schema location

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

​
Schema summary

FieldTypeRequiredDescription
aip_versionstringYesMust be "0.1".
request_idstringYesUnique identifier for this retrieval request. May be derived from a PlatformRequest.
timestampstring (date-time)YesISO 8601 timestamp when the request was generated.
platformobjectYesIdentity of the AI platform. id required; software, software_version optional.
intentobjectYesPlatform-declared intent for editorial scope matching. domain required; subdomain, confidence optional.
contextobjectYesMinimal context. language required; geography, placement optional.
runtimeobjectYesLive interaction. session_id, turn_index required; query_text, latency_budget_ms optional.
extensionsobjectNoNamespaced extensions for future use.

​
intent

  • domain — Primary intent domain (must align with publisher editorial_domains). Pattern: ^[a-z0-9]+(\.[a-z0-9-]+)*$
  • subdomain — Optional. Same pattern.
  • confidence — Optional. 0.0–1.0.

​
context

  • language — BCP 47 (e.g. en-US). Required.
  • geography.country — ISO 3166-1 alpha-2. Optional.
  • placement — Surface (e.g. conversation, chat, voice). Optional.

​
runtime

  • session_id, turn_index — Required.
  • query_text, latency_budget_ms — Optional.

​
Example

Well-formed RetrieveRequest body (e.g. POST to publisher’s retrieve endpoint): 
{
  "aip_version": "0.1",
  "request_id": "req_92fA1",
  "timestamp": "2025-01-15T14:30:00Z",
  "platform": {
    "id": "platform-acme-001",
    "software": "Acme Assistant",
    "software_version": "2.1.0"
  },
  "intent": {
    "domain": "business",
    "subdomain": "finance.markets",
    "confidence": 0.92
  },
  "context": {
    "language": "en-US",
    "geography": {
      "country": "US"
    },
    "placement": "conversation"
  },
  "runtime": {
    "session_id": "sess_abc123",
    "turn_index": 2,
    "query_text": "What are the best CRM tools for small teams?",
    "latency_budget_ms": 500
  }
}

​
What this schema deliberately excludes

This is intentional and important.
  • No auction data
  • No CPX / CPM / pricing
  • No brand or creative metadata
  • No embeddings
  • No operator scoring
  • No user identity beyond session context
If any of those appear in a RetrieveRequest, the request is non-compliant.

​
How publishers evaluate a RetrieveRequest

A publisher MUST evaluate, in this order:
  1. Verify authentication / signature (out of scope of this schema)
  2. Check intent_access.enabled and state (from aip.json)
  3. Match intent.domain (and optionally intent.subdomain) against editorial_domains
  4. Enforce retrieval limits (from aip.json)
  5. Respond or deny
This schema gives publishers everything they need — and nothing they don’t.

​
Why this schema will survive scrutiny

  • Clean separation from advertising
  • Explicit platform-declared intent
  • Deterministic consent matching
  • Minimal personal data surface
  • Future-safe via extensions

​
Schema file

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

​
See also