Public API Agents Skill
AI agents are only as useful as the data they can access. The ShipHero Public API Agents Skill gives your AI agent (whether Claude Code, Codex, a custom LLM pipeline, or any MCP-compatible agent framework) secure, read-only access to your ShipHero data without requiring you to write auth flows or manage tokens manually.
Why this exists
Warehouse operations generate constant questions: What’s the current inventory level on SKU X? Which orders have an address hold? What did we ship yesterday? Traditionally, answering those questions meant logging into ShipHero, running reports, or building custom integrations. The Agents Skill changes that. You can now ask your AI agent directly, and it will query your live ShipHero data to answer.
The skill is intentionally read-only. This is deliberate to ensure the safety of your data. Agents are powerful, but warehouse data mutations (updating inventory, canceling orders, creating products) carry real operational risk. By scoping tokens to read access only, you get the full analytical value of your ShipHero data without any risk of an agent making an unintended change.
How it works
The skill provides your agent with two core capabilities:
1. Token acquisition - The skill handles the OAuth flow against the ShipHero API on your behalf, returning a scoped, read-only access token. You don’t need to manage credentials in your agent’s context or hard-code API keys.
2. Token revocation - When your agent session ends, the skill includes an explicit revoke command to invalidate the token. This is important: don’t skip this step. Short-lived tokens reduce the blast radius if a session log or context window is ever exposed.
Once your agent has a token, it can query the ShipHero GraphQL Public API directly, pulling orders, inventory positions, shipment statuses, returns, purchase orders, and more.
3. Common query library - The skill includes a curated set of pre-built queries covering the most frequent warehouse questions: order status lookups, inventory checks, work order status, and more. These serve two purposes. First, they give your agent a head start without requiring it to construct GraphQL from scratch. Second, they act as a translation layer, helping the agent map natural language questions (“what orders shipped late last week?”) to the correct API query patterns.
Installation
- Download the skill: sh-public-api-agent-skill-20260325.zip
- Install it in your agent by either:
- Importing the skill file directly into your agent’s skill/tool configuration, or
- Passing the skill URL directly to your agent if it supports URL-based skill loading
- Authenticate via the skill’s token acquisition flow using your ShipHero credentials
- Start querying. The skill exposes the full ShipHero GraphQL schema.
Compatibility
The skill is designed to work with any agent framework that supports tool/skill definitions, including:
- Claude Code - pass the URL or install the zip directly
- Custom LLM pipelines - use the skill definition to register ShipHero as a tool in your agent loop
- MCP-compatible agents - the skill follows conventions compatible with Model Context Protocol patterns
A note on API credit usage
Every GraphQL query against the ShipHero API consumes API credits. This matters in an agentic context because agents can be chatty. We recommend instructing agents to be credit-aware: request only the fields they need, consider both quota and timing constraints, and break work into efficient iterative steps when needed. This helps agents fulfill requests reliably without over-consuming credits in a single call. Be sure to monitor credit usage during development and testing.