Marketplaces and networks

Content marketplaces, licensed content repositories, and affiliate networks sit between agents, content owners, and end users. This guide covers how those intermediaries report telemetry on behalf of content owners - retrieval events when an agent fetches licensed content, and engagement events when a user clicks through from an AI response.

If you only need read access to a content owner's telemetry, see the Measurement partners (delegated read) guide instead - that flow uses the same delegation primitive but doesn't require write access.

Who this is for

Reporting retrievals

When an agent fetches content through your marketplace or repository, report a content_retrieved event with source_role: "index". No session is required - the marketplace doesn't have a session view of the agent's conversation.

curl -X POST https://telemetry.openattribution.org/events \
  -H "X-API-Key: oat_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "content_retrieved",
        "timestamp": "2026-03-18T10:00:01Z",
        "source_role": "index",
        "content_url": "https://example.com/article/best-headphones",
        "content_id": "doi:10.1000/example.123",
        "content_telemetry_id": "550e8400-e29b-41d4-a716-446655440000",
        "data": {
          "media_type": "text",
          "license_ref": "https://example.com/licences/standard"
        }
      }
    ]
  }'

Why no session_id?

Marketplaces, edges, and origins emit at the retrieval conformance level. They see HTTP requests, not conversations. Attribution consumers correlate these standalone events with agent-reported sessions using content_telemetry_id - the UUID the agent puts on its Content-Telemetry-ID request header.

Why include content_id?

If your URLs differ from the canonical source - for example you serve content from marketplace.example.com but the underlying article lives at owner.example.com - include the canonical content_id (DOI, ISCC, content-owner-assigned identifier) so attribution rolls up to the right content owner. The spec covers this in section 4.4.

Reporting clickthroughs (engagement)

When an AI agent generates an outbound link, the agent creates a click token and appends it to the URL as a ctx query parameter. The user (or their agent) clicks the link and lands on your network or merchant page.

https://retailer.com/headphones/sony-wh1000xm5?ctx=ctx_abc123def456

Capture the ctx parameter and report a content_engaged event. You don't need the agent's session ID - the server resolves ctx_token to the session.

curl -X POST https://telemetry.openattribution.org/events \
  -H "X-API-Key: oat_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "content_engaged",
        "timestamp": "2026-03-18T10:01:00Z",
        "source_role": "index",
        "content_url": "https://retailer.com/headphones/sony-wh1000xm5",
        "ctx_token": "ctx_abc123def456",
        "data": {
          "engagement_type": "link_click"
        }
      }
    ]
  }'

You can also report richer engagement after the click - expand, copy, share - using the same ctx_token. Engagement events with a click token are scoped to the click and don't extend the agent's session.

Consent on click-token lookup

Click-token lookup is two-sided opt-in. The endpoint returns 404 unless both:

• The agent that issued the token has set share_sessions_via_click_tokens to true on its org.
• The content owner whose URLs were cited has set visible_in_click_token_lookups to true on its org.

Both default to false, so a fresh agent and a fresh content owner will see empty lookups until they each enable sharing. Toggle either flag in the dashboard settings page or via PATCH /api/v1/identity/settings.

If consent is missing, your reported content_engaged event still records correctly against the session - you just can't see who cited what. Reporting is unconditional; lookup is opt-in.

Closing the loop with conversion outcomes

If you can detect that the click led to a purchase or signup, report a checkout_completed event tied to the same ctx_token. (checkout_completed is defined in the ACP commerce extension, not the core schema.) This closes the attribution loop from agent citation to merchant conversion.

{
  "type": "checkout_completed",
  "timestamp": "2026-03-18T10:14:30Z",
  "source_role": "index",
  "content_url": "https://retailer.com/headphones/sony-wh1000xm5",
  "ctx_token": "ctx_abc123def456",
  "data": {
    "value_amount": 34900,
    "currency": "USD"
  }
}

value_amount is in minor currency units. Content owners with a delegation from you can read these outcomes alongside their citation data.

Cross-observer corroboration

When the agent emits an Content-Telemetry-ID header on its HTTP fetch, both you and the agent end up with the same UUID on your separate content_retrieved events. OA correlates them as one corroborated retrieval - the marketplace's record matches the agent's record.

The same applies to clickthroughs: the agent emits its own content_engaged event when the user clicks, and your network's event with the same ctx_token corroborates it.

Next steps

• API reference for full endpoint and field documentation.
• Telemetry specification - sections 4.3, 5.7, and 6 cover source roles, conformance levels, and per-stage data profiles.
• Measurement partners guide if you also need read access on behalf of content owners.