# ReplenishRadar Agent API Contract Notes

Last verified: 2026-06-08

These notes define the public contract ReplenishRadar agents should rely on when using the MCP and REST tool surface. They are intentionally narrower than the product docs: this file is for response interpretation, versioning, and error handling.

## Scope

- Canonical MCP package: `npx -y @replenishradar/mcp-server`.
- Canonical REST tool-call endpoint: `POST https://api.replenishradar.com/api/mcp/call`.
- Canonical MCP server card: `https://replenishradar.com/.well-known/mcp/server-card.json`.
- Canonical auth policy: `https://replenishradar.com/auth.md`.
- Organization scope is derived from the Bearer API key. Do not send a separate organization header.
- Sandbox responses are pinned to synthetic demo data and include `sandbox: true` when the MCP dispatch tags the response.

## Response Metadata

Agents should treat tool output as operational data, not as model reasoning. ReplenishRadar does not expose hidden chain-of-thought through API responses.

### Provenance

Provenance means the business source for a value. It may appear as fields such as `source`, `source_type`, `connector_type`, `store_id`, `item_id`, `action_id`, `po_id`, `sync_run_id`, `updated_at`, or immutable snapshots on replenishment and purchase-order records.

When a tool returns replenishment actions, purchase orders, alerts, sync status, or stock-by-location data, prefer the returned IDs and snapshots over re-deriving facts from display labels. If provenance fields are absent on a legacy read, treat the tool name plus returned entity IDs as the provenance boundary.

### Confidence

Confidence is deterministic unless a response says otherwise:

- Direct records such as items, purchase orders, suppliers, sync runs, and notes are exact database reads scoped to the API key's organization.
- Forecast, stockout-risk, lost-sales, slow-mover, and suggestion outputs are computed planning signals. They should be presented as recommendations or estimates, not as guaranteed outcomes.
- Agent write tools that change money, supplier communication, or stock state remain gated by capability, tool group, and human approval where applicable.

Agents should ask for human review before taking irreversible business action when confidence is low, stale data is involved, or the requested action changes supplier, stock, or purchasing state.

### Freshness

Freshness means the age and health of the upstream data behind a response. It may appear as `as_of`, `updated_at`, `last_synced_at`, `last_success_at`, `data_freshness`, `stale_dimensions`, or sync-status fields.

Before quoting live quantities, days-to-stockout, purchase recommendations, or store health in a high-stakes decision, call `rr_get_data_freshness` or `rr_get_sync_status` and include stale-data caveats when the relevant dimension is stale, disconnected, pending setup, paused, or errored.

## Tool Versioning

- Tool names are stable public identifiers. Existing names should not change silently.
- Input schemas may gain optional fields without a breaking change.
- Output schemas may gain fields without a breaking change.
- Removing a field, changing a required input, changing a tool's side effect, or tightening access beyond the published tier/capability contract is a breaking change.
- Breaking changes require a replacement path and a deprecation notice in the MCP docs or server-card-adjacent discovery surface before removal.
- Package-backed MCP releases use npm package semver. The official MCP Registry entry, once published, must use a unique version string for every publication.

The generated server card and `packages/mcp-server/tools.manifest.json` are the source of truth for current tool names, descriptions, capabilities, tool groups, and input schemas.

## Error Taxonomy

Agents should normalize MCP and REST failures into this shape when possible:

```json
{
  "error": {
    "code": "capability_not_in_tier",
    "message": "This tool requires a capability or tool group your key does not grant.",
    "retryable": false,
    "next_action": "Ask a human admin to grant the required capability or choose a lower-risk tool."
  }
}
```

Current endpoints may return a FastAPI string detail or an object containing `error`. If `detail.error` exists, use it as the normalized `code`.

| Code | HTTP | Retryable | Agent action |
|---|---:|---:|---|
| `auth_required` | 401 | false | Ask the human operator for a ReplenishRadar API key. |
| `invalid_api_key` | 401 | false | Ask the human operator to create or paste a valid `rr_sk_` key. |
| `api_key_expired` | 401 | false | Ask the human operator to rotate the key. |
| `api_key_suspended` | 403 | false | Stop using the key and ask the human operator to review the suspension reason. |
| `capability_not_in_tier` | 403 | false | Use a lower-capability tool or ask a human admin for the required capability, tool group, or tier. |
| `write_scope_required` | 403 | false | Request a write-scope key only after the human operator confirms the intended write behavior. |
| `tier_upgrade_required` | 403 | false | Explain the required tier and link to pricing. |
| `sandbox_read_only` | 403 | false | Do not retry as a write. Use the sandbox for read evaluation only. |
| `sandbox_capacity` | 429 | true | Back off for the current hourly window or start a trial for a dedicated key. |
| `rate_limited` | 429 | true | Back off and retry after the window resets. |
| `validation_error` | 400 | false | Fix the input payload before retrying. |
| `unknown_tool` | 400 | false | Refresh the server card or package and use a listed tool name. |
| `not_found` | 404 | false | Re-check the entity ID, SKU, organization context, or current store connection. |
| `stale_state` | 409 | false | Re-read the entity, then retry with the latest `expected_updated_at` and a new or matching idempotency key. |
| `approval_required` | 400 | false | Request human approval before attempting the supplier-facing action again. |
| `server_error` | 500 | true | Retry with backoff; contact support if the error persists. |

Do not work around authorization errors by requesting broader access automatically. Capability escalation is a human-admin action.

## Security Boundaries

- API keys are created by a human admin and are bound to one organization.
- Raw API keys are never returned after creation except in the original creation or sandbox handoff response.
- Agent context tools must not store secrets or raw PII.
- Sandbox keys cannot reach real customer data and cannot call write tools.
- Agents must preserve human approval gates for purchase orders and supplier-facing actions.