Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.interchange.io/llms.txt

Use this file to discover all available pages before exploring further.

The Interchange API publishes a per-role skill file — a single Markdown document that teaches an AI agent how to use the API, on demand, at runtime.

​
Overview

A skill file is a self-contained Markdown document that describes an entire API surface in a format LLMs can read and reason about. Agents discover capabilities, endpoints, auth, presentation rules, and gotchas without bespoke client code. v2 ships two: one for the buyer API and one for the storefront API.

​
Skill File URL

Buyer Skill File

Machine-readable API spec for buyer operations

Storefront Skill File

Machine-readable API spec for storefront operations

​
Format

Each skill file opens with YAML front matter, followed by Markdown sections. The buyer skill file currently looks like: 
---
name: scope3-agentic-buyer
version: "2.0.0"
description: Scope3 Agentic Buyer API - AI-powered programmatic advertising
api_base_url: https://api.interchange.io/api/v2/buyer
auth:
  type: bearer
  header: Authorization
  format: "Bearer {token}"
  obtain_url: https://interchange.io/user-api-keys
---

# Scope3 Agentic Buyer API

This API enables AI-powered programmatic advertising with inventory discovery,
campaign management, and creative orchestration.

## ⚠️ CRITICAL: Presentation Rules
…
After the front matter, the file walks through:
  • Presentation rules — what an agent must show the user from each response.
  • Workflow guides — the required call sequence for multi-step intents (e.g. campaign creation requires brief → audience → catalog → configure → execute).
  • Endpoint catalog — operations exposed via api_call, with required fields, examples, and gotchas.
  • Display requirements per endpoint — exactly which fields to surface and how to structure them.

​
How an agent uses it

Agents connected over MCP get three tools and use them in a loop:
ToolPurpose
healthProbe API connectivity
ask_about_capabilitySearch the skill file for the right operation, fields, and presentation rules for the user’s intent
api_callExecute the chosen REST operation
The canonical pattern is:
  1. User describes an intent in natural language.
  2. Agent calls ask_about_capability with that intent. The skill file returns the relevant operation, required fields, and any “must show this in your reply” rules.
  3. Agent gathers any missing inputs from the user (one question per turn) and calls api_call to execute.
  4. Agent presents the result to the user, following the display requirements that came back with the operation. End the turn.
The skill file emphasizes one mutating or discovery call per turn — agents should not chain multiple writes in a single response. Custom agent prompt example: 
Read https://api.interchange.io/api/v2/buyer/skill.md and use it to help me
create an advertiser called "Acme Corp" for the brand acme.com. Once it's
created, list my advertisers so I can confirm.

​
Versioning

The version field in the front matter is a semantic version that tracks the skill file, not the underlying API.
  • Patch (2.0.x) — clarifications, new examples, fixed gotchas. No agent change required.
  • Minor (2.x.0) — new operations, new optional fields, additive workflows. Existing agents keep working; new capabilities become available the next time ask_about_capability is called.
  • Major (x.0.0) — breaking changes (renamed operations, removed fields, changed required workflows). Pin to the previous version’s skill URL if your agent can’t be updated immediately; otherwise re-test critical flows.
The skill file URL always serves the latest stable version for that role. There is no separate “v1 skill file” URL — v1 didn’t ship one.

​
Capability summaries

The skill files cover the same capabilities documented in the Buyer API reference and Storefront API reference. For depth on any one area:

Buyer onboarding

End-to-end campaign-launch flow.

Storefront onboarding

Register a storefront and expose inventory.

Discovery guide

Product discovery, refinement, and proposals.

Built for Agents

MCP connector setup for Claude, ChatGPT, Cursor, and custom agents.