API Evangelist enhancements — Jitsu REST API

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
overlay: 1.0.0
info:
  title: API Evangelist enhancements — Jitsu REST API
  version: 1.0.0
  x-generated: '2026-08-06'
  x-method: generated
  x-source: >-
    Generated by the API Evangelist enrichment pipeline against
    openapi/axlehire-jitsu-rest-api.yml (fetched verbatim from
    https://docs.gojitsu.com/Jitsu_Export/openapi.yaml). Every value added below
    is sourced from Jitsu's own published documentation — nothing is invented.
    The original spec is never mutated; apply this overlay to get the enriched
    view.
extends: ../openapi/axlehire-jitsu-rest-api.yml
actions:

- target: $.info
  description: Record where the contract was found and what it does not cover.
  update:
    x-evidence:
      fetched: '2026-08-06'
      url: https://docs.gojitsu.com/Jitsu_Export/openapi.yaml
      http_status: 200
      content_type: text/yaml
      bytes: 134234
      note: >-
        The docs host is a Firebase SPA — https://docs.gojitsu.com/openapi.yaml
        returns the 11773-byte HTML shell. The real contract is under
        /Jitsu_Export/.
    x-former-name: AxleHire
    x-rebrand-date: '2024-04'
    x-not-covered:
      - >-
        The staging lifecycle simulation endpoints
        (/v3/simulation/happy_path/shipments/{shipment_id},
        /v3/simulation/sad_path/shipments/{shipment_id},
        /v3/simulation/shipments/{shipment_id}/{SHIPMENT_SIGNAL}) are documented
        in Testing.md but absent from this contract.
      - No error responses are declared; see x-error-catalog.
    x-error-catalog: ../errors/axlehire-problem-types.yml
    x-conventions: ../conventions/axlehire-conventions.yml
    x-webhooks-catalog: ../asyncapi/axlehire-webhooks.yml
    x-lifecycle: ../lifecycle/axlehire-lifecycle.yml

- target: $.info
  description: Attach the documentation entry points Jitsu publishes.
  update:
    x-documentation:
      integration_guide: https://docs.gojitsu.com/#/docs/QuickStart.md
      authentication: https://docs.gojitsu.com/#/docs/Authentication.md
      testing: https://docs.gojitsu.com/#/docs/Testing.md
      lifecycle: https://docs.gojitsu.com/#/docs/Lifecycle.md
      webhooks: https://docs.gojitsu.com/#/docs/Webhooks.md
      errors: https://docs.gojitsu.com/#/docs/Errors.md
      retry_and_errors: https://docs.gojitsu.com/#/docs/RetryAndErrors.md
      labels: https://docs.gojitsu.com/#/docs/Labels.md
      brands: https://docs.gojitsu.com/#/docs/Brands.md
      glossary: https://docs.gojitsu.com/#/docs/Glossary.md
      sdks: https://docs.gojitsu.com/#/docs/SDKs.md
      status: https://status.gojitsu.com/

- target: $
  description: >-
    Record the account-wide rate limit Jitsu documents but does not express in
    the contract, and the fact that it signals no rate-limit headers.
  update:
    x-rate-limits:
      limit: 10
      metric: requests_per_second
      scope: account
      environments: [production, staging]
      throttle_status: 429
      response_headers: none
      backoff: exponential 1s/2s/4s/8s capped at 60s with 10-20% jitter
      source: https://docs.gojitsu.com/#/docs/RetryAndErrors.md
      detail: ../rate-limits/axlehire-rate-limits.yml

- target: $
  description: Record the idempotency posture explicitly — the contract is silent, the docs are not.
  update:
    x-idempotency:
      supported: false
      mechanism: none
      guidance: >-
        Jitsu publishes no Idempotency-Key header. A retried POST /v3/shipments
        after a timeout can create a duplicate shipment. The documented
        mitigation is to send a stable internal_id or tracking_code and to look
        the shipment up before retrying.
      source: https://docs.gojitsu.com/#/docs/RetryAndErrors.md

- target: $.components.securitySchemes.Authorization
  description: Clarify the token format, its scope model and where it is issued.
  update:
    x-token-format: 'Authorization: Token <YOUR_API_TOKEN>'
    x-issued-at: https://client.gojitsu.com/ (Settings → API Token)
    x-staging-issued-at: https://client.staging.gojitsu.com/
    x-scopes: none — a token carries full account permissions
    x-self-service: false
    x-detail: ../authentication/axlehire-authentication.yml

- target: $.paths['/v3/shipments'].post
  description: >-
    Flag the duplicate-creation risk on the one required operation in the whole
    integration.
  update:
    x-idempotent: false
    x-retry-safe: false
    x-natural-keys: [internal_id, tracking_code]
    x-agentic-access:
      action_class: write
      consequence: irreversible-side-effect
      note: >-
        Creates a real physical delivery and incurs cost. Not safe to retry
        blind; confirm via GET /v3/shipments/{shipment_id} before re-issuing.

- target: $.paths['/v3/shipments/{shipment_id}/cancel'].post
  description: Mark the consequence class of cancellation.
  update:
    x-agentic-access:
      action_class: write
      consequence: irreversible-side-effect
      note: >-
        Produces CANCELLED_BEFORE_PICKUP or CANCELLED_AFTER_PICKUP depending on
        timing; cannot be undone by the API.

- target: $.paths['/v3/shipments/{shipment_id}/label'].get
  description: Record the label formats and the response encoding, which the contract does not state.
  update:
    x-formats: [PDF, PNG, ZPL]
    x-default-format: PDF
    x-response-encoding: base64 string in the `label` field
    x-source: https://docs.gojitsu.com/#/docs/Labels.md

- target: $.tags
  description: >-
    Note the tag/route inconsistency — a "Partner Information" tag is used on
    /v3/partner/tracking/{tracking_code}/events but is not declared in tags[],
    and two operations share the operationId `retrieveEvents`.
  update:
    x-tag-issues:
      undeclared_tags: [Partner Information]
      duplicate_operation_ids:
      - operationId: retrieveEvents
        paths:
        - '/v3/tracking/{tracking_code}/events'
        - '/v3/partner/tracking/{tracking_code}/events'
      note: >-
        Duplicate operationIds break code generation — most generators either
        collide or silently drop one of the two methods.