# SMKlog Quote API — agentic access contracts (x-agentic-access).
#
# Generated by scripts/build_api_artifacts.mjs from the live OpenAPI document
# (https://quote-api.smklog.com/openapi.json); the values are SMKlog's own, pinned by the test suite.
generated: '2026-11-07'
method: authored
publisher: 'SMKlog (SMKLOG-2022 LLC)'
source: 'https://smklog.com/developers/agentic-access.yaml'
contract: 'https://quote-api.smklog.com/openapi.json'
description: 'x-agentic-access execution contracts for every operation of the SMKlog Quote API, written by SMKlog from what the service does and carried verbatim inside the OpenAPI document. Nine operations only read (a quote, a checkout status, a refund status, tracking, the price index, billable weight, holiday shipping deadlines, shipping restrictions and liveness); four act: createPaymentSession and upsertPaymentSession store or re-price a payment session that a human then pays for on smklog.com, updatePaymentSession re-prices one by its id, cancelPaymentSession reverses one the human has not opened. No operation moves money, and a bearer token (one hour, client_credentials) is optional on every one except the create-or-update keyed on external_id.'
summary:
  operations: 13
  by_action_class:
    connected: 9
    acting: 4
  by_consequence:
    read: 9
    write: 4
  human_in_the_loop_required: 3
operations:
  - path: '/quote'
    method: post
    operationId: getParcelQuote
    x-agentic-access:
      action-class: connected
      consequence: read
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
      audit: none
  - path: '/agent/checkout-session'
    method: post
    operationId: createPaymentSession
    x-agentic-access:
      action-class: acting
      consequence: write
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
        exchange: false
        purpose-required: false
        proof-of-possession: false
      escalation:
        human-in-the-loop: required
      audit: required
      note: 'Stores a priced payment session and returns a handoff URL; no money moves. The human completes consent and payment on smklog.com, so the agent never needs a subject identity and cannot charge anyone. Every session is recorded with its session_id and is readable through getCheckoutStatus for 30 days.'
  - path: '/agent/checkout-session/by-external-id/{external_id}'
    method: put
    operationId: upsertPaymentSession
    x-agentic-access:
      action-class: acting
      consequence: write
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
        exchange: false
        purpose-required: false
        proof-of-possession: false
      escalation:
        human-in-the-loop: required
      audit: required
      note: 'Stores a priced payment session and returns a handoff URL; no money moves. The human completes consent and payment on smklog.com, so the agent never needs a subject identity and cannot charge anyone. Every session is recorded with its session_id and is readable through getCheckoutStatus for 30 days.'
  - path: '/agent/checkout-session/{session_id}'
    method: get
    operationId: getCheckoutStatus
    x-agentic-access:
      action-class: connected
      consequence: read
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
      audit: none
  - path: '/agent/checkout-session/{session_id}'
    method: patch
    operationId: updatePaymentSession
    x-agentic-access:
      action-class: acting
      consequence: write
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
        exchange: false
        purpose-required: false
        proof-of-possession: false
      escalation:
        human-in-the-loop: required
      audit: required
      note: 'Re-prices a session the human has not opened yet: same session_id, new amount, service and handoff_url; no money moves, and the human still completes consent and payment on smklog.com. From checkout_started on the call is refused with 409 and the human''s checkout stands. Updates are recorded like creates and readable through getCheckoutStatus.'
  - path: '/agent/checkout-session/{session_id}'
    method: delete
    operationId: cancelPaymentSession
    x-agentic-access:
      action-class: acting
      consequence: write
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
        exchange: false
        purpose-required: false
        proof-of-possession: false
      audit: required
      note: 'Reverses createPaymentSession while the session is still awaiting_checkout: nothing has been paid at that stage, so no human is needed in the loop. From checkout_started on the call is refused with 409 and the human''s checkout stands.'
  - path: '/agent/checkout-session/{session_id}/refund'
    method: get
    operationId: getRefundStatus
    x-agentic-access:
      action-class: connected
      consequence: read
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
      audit: none
  - path: '/tracking/{tracking_number}'
    method: get
    operationId: trackParcel
    x-agentic-access:
      action-class: connected
      consequence: read
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
      audit: none
  - path: '/price-index'
    method: get
    operationId: getPriceIndex
    x-agentic-access:
      action-class: connected
      consequence: read
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
      audit: none
  - path: '/billable-weight'
    method: get
    operationId: calculateBillableWeight
    x-agentic-access:
      action-class: connected
      consequence: read
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
      audit: none
  - path: '/holiday-deadlines'
    method: get
    operationId: getHolidayShippingDeadlines
    x-agentic-access:
      action-class: connected
      consequence: read
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
      audit: none
  - path: '/shipping-restrictions'
    method: get
    operationId: getShippingRestrictions
    x-agentic-access:
      action-class: connected
      consequence: read
      subject: optional
      audience: 'https://quote-api.smklog.com'
      token:
        max-ttl: 3600
      audit: none
  - path: '/status'
    method: get
    operationId: status
    x-agentic-access:
      action-class: connected
      consequence: read
      subject: optional
      audit: none
      note: 'Unauthenticated liveness probe; no token is read.'
