---

name: flexport-hello-world description: >- Prove a Flexport integration with one read-only shipment request and a defensively parsed receipt. Use when validating new credentials, network access, version selection, or response handling. Trigger with: "test Flexport API", "Flexport hello world", "verify shipment access". allowed-tools: Read, Grep, Write, Edit version: 2.0.0 argument-hint: '[credential-alias-and-test-scope]' model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• flexport
• validation
• shipments compatibility: 'Requires approved Flexport credentials and access to a tenant with a non-sensitive testable shipment or empty-list response.'

---

Read-Only Flexport v3 Proof

Overview

Establish connectivity without creating freight, documents, or bookings. Pin the intended API version, accept documented response wrappers, and preserve only a redacted proof.

Prerequisites

• Approved read-only credential and credential alias
• Known account API version or explicit Flexport-Version choice
• A test policy that permits either one shipment reference or an empty list

Instructions

Step 1: Define the proof

Set the expected account, endpoint, version, and allowed evidence before making a call.

Step 2: Acquire authentication

Reuse a cached OAuth client-credentials token, or use an explicitly approved API key. Keep the credential out of command text and logs.

Step 3: Request shipments

Send GET https://api.flexport.com/shipments with Bearer authorization, JSON acceptance, and Flexport-Version: 3 when an explicit v3 override is intended.

Step 4: Parse defensively

Read the documented response envelope and pagination links without assuming invented ID prefixes, undocumented nested records, or a fixed set of additive fields.

Step 5: Validate tenant safety

Confirm the response belongs to the intended account and emit only count, HTTP status, selected version, and a hashed operation identifier.

Step 6: Fail closed

Do not progress from a successful read to document creation, booking, or mutation. Make the next action a separate approved workflow.

Authentication

REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions.

Tool Discipline

Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change.

Output

• Scoped decision or implementation artifact
• Redacted operation and validation receipt
• Failure, rollback, and follow-up ownership record

Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it:

surface: rest-v3
operation: shipment-read
decision: approved
outcome: verified
evidence:
  release_sha: recorded-out-of-band
  provider_reference: redacted
rollback_owner: logistics-platform

Examples

A deployment probe requests the first shipment page with a cached OAuth token, confirms HTTP 200 and the intended version, records count=0 or a redacted count, then exits without following pagination.

Error Handling

Failure	Response
401 response	Refresh once through the shared cache, then inspect credential state instead of retrying.
403 response	Check endpoint resources and account access; do not switch to a broad key automatically.
Unexpected schema	Capture field names and version only, then compare with current v3 documentation.
Non-empty sensitive payload	Discard payload content and keep a metadata-only receipt.

Resources

• First-party source notes
• Shipment API tutorial
• Versioning
• Flexport API reference