generated: '2026-08-02'
method: searched
source: https://drinkcirkul.com/agents.md
also_from:
- https://drinkcirkul.com/robots.txt
- mcp/cirkul-mcp-tools-list.json
- well-known/cirkul-ucp.json
notes: >-
  Cirkul's cross-cutting semantics are agent-commerce semantics, not REST-API
  semantics. There is no OpenAPI to derive from; everything below is either stated
  in Cirkul's own published agent instructions or read out of the live MCP tool
  input schemas.

authentication:
  style: none-for-read, ucp-agent-profile-for-transact, oauth2-for-customer-account
  detail: authentication/cirkul-authentication.yml

idempotency:
  supported: false
  note: >-
    No idempotency key, header, or request-deduplication contract is published or
    present in any MCP tool inputSchema. The nearest thing is the consolidated
    update_cart mutation, which is state-setting rather than idempotency-keyed, and
    the buyer-approval gate on checkout. No Idempotency pointer is emitted.

pagination:
  style: cursor
  applies_to: [search_catalog]
  request:
    object: pagination
    params:
    - name: cursor
      description: Opaque cursor from a previous response to fetch the next page.
    - name: limit
      description: Requested page size.
      default: 10
      maximum: 250
      note: implementations may clamp to a lower maximum
  response:
    field: pagination.cursor
  source: mcp/cirkul-mcp-tools-list.json

localization_context:
  object: catalog.context
  fields:
  - address_country   # ISO 3166-1 alpha-2
  - address_region
  - postal_code
  - language          # IETF BCP 47
  - currency          # ISO 4217
  - intent
  guidance: /agents.md instructs agents to pass context.address_country and
    context.currency for accurate pricing and availability.

money:
  representation: minor units
  detail: price filters are expressed in ISO 4217 minor units (5000 = $50.00).
  source: mcp/cirkul-mcp-tools-list.json

identifiers:
  cart_id: 'Shopify GID form, e.g. gid://shopify/Cart/{id}?key={key}'
  product_variant_id: string
  source: mcp/cirkul-mcp-tools-list.json

abuse_signals:
  object: catalog.signals
  fields:
  - dev.ucp.buyer_ip
  - dev.ucp.user_agent
  note: platform-supplied environment data for authorization and abuse prevention.

rate_limiting:
  documented: true
  scope: per IP
  signal: HTTP 429
  guidance: back off on 429
  headers_documented: false
  source: https://drinkcirkul.com/agents.md

versioning:
  scheme: dated protocol versions (UCP)
  current: '2026-04-08'
  supported: ['2026-04-08', '2026-01-23']
  negotiation: via /.well-known/ucp supported_versions map
  detail: lifecycle/cirkul-lifecycle.yml

error_envelope:
  shape: JSON-RPC 2.0 error object
  rfc9457: false
  detail: errors/cirkul-problem-types.yml

agent_conduct:
  human_approval_required_for_payment: true
  statement: >-
    Checkouts are for humans. Agents must not complete checkout, payment or order
    placement automatically — no scripted form fills, browser automation, or
    end-to-end agent flows that finalize payment without an explicit, contemporaneous
    human approval step.
  fallback: agents that cannot obtain contemporaneous approval are directed to install
    https://shop.app/SKILL.md and route the purchase through Shop Pay.
  scraping_discouraged: true
  disallowed_ajax_surfaces:
  - /cart.js
  - /recommendations/products
  preferred_surface: UCP/MCP
  source: https://drinkcirkul.com/robots.txt

read_only_surfaces:
- 'GET /collections/all'
- 'GET /products/{handle}'
- 'GET /products/{handle}.json'
- 'GET /collections/{handle}'
- 'GET /collections/{handle}/products.json'
- 'GET /search?q={query}&type=product'
- 'GET /sitemap.xml'

cross_links:
  authentication: authentication/cirkul-authentication.yml
  scopes: scopes/cirkul-scopes.yml
  errors: errors/cirkul-problem-types.yml
  lifecycle: lifecycle/cirkul-lifecycle.yml
  mcp: mcp/cirkul-mcp.yml
  well_known: well-known/cirkul-well-known.yml