For developers and the people who build assistants

Build on Interchange

Interchange maps every brand’s part number for the same industrial hose fitting to one item with a permanent Interchange ID. The API and the MCP server return those mappings, each checked by a person, so your product can answer “what replaces this part?” without guessing.

Addresses

  • The REST API will be at https://api.interchangeparts.com.au. Reviewed data once it is published.
  • The sandbox API will be at https://sandbox.api.interchangeparts.com.au. Illustrative data only, safe to build against.
  • The MCP server will be at https://mcp.interchangeparts.com.au/mcp. Streamable HTTP, for assistants.

Read endpoints will work without a key. Keys will be issued when the sandbox opens, and none can be issued yet.

What the API is for

  • Look up a part number from any brand and find the item it belongs to.
  • Get every brand’s reviewed equivalent of an item, with its confidence, evidence and review date.
  • Identify a fitting from attributes someone has read, and be told which question to ask when the answer depends on something unseen.
  • Find who lists an item, in alphabetical order, with a link to ask for a quote.
  • Match a whole price list to IX IDs, and keep your item codes current with a change feed or webhooks.

It is a cross-reference. It is not a price comparison, a ranking of suppliers, or a recommendation of one part over another.

Principles

These shape the API, and your integration needs to respect them.

Answers are the same for everyone

A plan changes how much you may call and which extra endpoints you can use. It never changes which parts match, the order of suppliers, or how a correction is handled. No response carries a plan, tier, rank or promoted field, and equivalents and suppliers are always sorted A to Z.

We abstain rather than guess

When no reviewed mapping exists the API says no_verified_match and returns nothing nearer. Show that as “we do not know”, never as “there is no equivalent”. Only reviewed, published data is returned; nothing machine-suggested is.

Safety is data

Known confusions, such as BSPP against NPT threads, come back as safety_flags with a message you can show as written. Wherever a person sees an item, show its flags and the usage.disclaimer that every answer carries.

You build the integration

We publish the specification, this documentation, a sandbox and worked examples. We do not build or run connectors, and the recipes are examples, not products.

Where to start

  • Quickstart: a first call in five minutes, then a correct integration.
  • API reference: every operation, schema, error and webhook, generated from the specification.
  • Recipes: match a price list, keep item codes in sync, handle a retired ID, show equivalents, relay safety flags.
  • MCP server: connect an assistant, with the tools and the server instructions.

Support boundary

We support the service and the data. You support your integration.

What we support

  • The API and the MCP server being available and behaving as documented.
  • The documentation being correct. If it and the API disagree, that is our fault.
  • Keys and accounts: creating, rotating and revoking keys, plan and billing questions.
  • The data. A wrong mapping, a missing equivalent or a safety concern is handled for everyone, whatever their plan.

What we do not support

  • Writing, debugging or running your integration.
  • Configuring your ERP, e-commerce platform, spreadsheet or middleware.
  • Connectors, SDKs, custom fields, custom endpoints or custom feeds.
  • Training and consulting.

Getting help

Email hello@interchangeparts.com.au. Include the Interchange-Request-Id from the response, which every response carries, the endpoint or tool, the time, and what you expected. Without a request ID we can rarely find the call. Response targets depend on your plan and are proposals until published.

Your side of the line

  • Store IX IDs as opaque keys. Do not parse them.
  • Show or pass on safety_flags and usage.disclaimer wherever a person sees a result.
  • Respect Cache-Control and never serve a cached answer older than 12 hours.
  • Treat 410 Gone as “stop showing this item”, and no_verified_match as “we do not know”.
  • Wait for Retry-After after a 429.
  • Make webhook handlers idempotent, verify the signature, and reject a delivery whose timestamp is more than 5 minutes old.
  • Keep your key secret and rotate it if it may have leaked. Test in the sandbox.

How the API changes

The version is in the path (/v1). Within a version we only add.

We may do at any time

  • Add endpoints, optional parameters, response fields and enum values.
  • Add safety flag codes and error codes.
  • Change the order of fields, the wording of messages and the size of a response within documented limits.
  • Add or tighten rate limits to protect the service.

So ignore fields you do not know, and treat an enum value you do not know as “other”.

We will not do within a version

  • Remove or rename an endpoint, parameter or field.
  • Change the meaning, type or format of a field.
  • Make an optional parameter required.

A breaking change means a new version. We will announce it in the changelog and by email to every key holder at least 6 months before the old version stops working, run both side by side for that whole period, publish a migration guide, and open the new version’s sandbox from the announcement. The notice period is a proposal until the terms are published.

Safety is the exception. If a field or behaviour makes a wrong or unsafe answer likely, we may change or remove it immediately.

Data changes are not breaking changes. A mapping can be corrected, withdrawn or retired at any time, and that is the product working. A cached answer may be kept for 12 hours at most, and a correction or withdrawal must reach what you show within 24 hours. Use the change feed or webhooks, or keep your cache short, to keep up. A withdrawn item answers 410 Gone.