AI Agent Integration

Use the Blaze ECOM Storefront API with AI coding assistants, LLMs, and agentic development tools.

What you'll learn

• How to feed the API to AI coding agents (Cursor, Cline, Warp, Aider)
• How to use the API as context for ChatGPT, Claude, and other LLMs
• What files are available and when to use each one
• How to set up an MCP server for your AI tools
• Token budget guidance for different context window sizes

Prerequisites

• Access to an AI coding assistant or LLM
• Familiarity with the Quick Start guide

Available Formats

The API documentation is published in multiple formats optimized for different consumers:

Using with IDE Agents

Cursor

Add the full API documentation as a Cursor Doc:

1. Open Cursor Settings → Docs
2. Click Add new doc
3. Point it at the llms-full.txt URL (once hosted) or paste the file path
4. Cursor will index the content and use it when you ask about the API

Alternatively, add a .cursor/rules file to your frontend project:

## Blaze ECOM API

This project uses the Blaze ECOM Storefront API. The full API documentation
is available at `../ecom-backend/docs/api/llms-full.txt`.

Key conventions:

- JSON:API format for all requests/responses
- X-Store header required on all store-scoped endpoints
- JWT auth via POST /api/v1/auth/login
- Staging: https://ecom-api.staging.blaze.me
- Store UUID: e87437f2-3e35-4738-af5e-6307e368255c

Warp (Oz)

Point Oz at the API documentation:

1. Reference docs/api/llms-full.txt in your prompt or attach it as context
2. Or ask Oz to read the OpenAPI spec directly: "Read docs/api/openapi.yaml and help me build a product listing page"

Oz can also run the automation skills in .agents/skills/ to validate docs against the live API.

Cline / Aider

Both tools support adding documentation as context files:

# Cline — add to .cline/context
cp docs/api/llms-full.txt .cline/context/blaze-ecom-api.txt

# Aider — pass as read-only context
aider --read docs/api/llms-full.txt src/api/products.ts

Using with ChatGPT / Claude

For conversational LLMs, paste the appropriate documentation as context:

Small context window (~32K tokens)

Use llms.txt — the curated index. It gives the LLM an overview of what's available and links to specific guides. Follow up by pasting the specific guide you need.

Example prompt:

Here is the API documentation index for the Blaze ECOM Storefront API:

[paste llms.txt content]

I need to build a product listing page with filtering. Which guide should I read?

Large context window (~128K+ tokens)

Use llms-full.txt — all guides + endpoint reference inlined. This gives the LLM everything it needs in a single context load.

Example prompt:

Here is the complete API documentation for the Blaze ECOM Storefront API:

[paste llms-full.txt content]

Build me a React component that:
1. Fetches product categories from the API
2. Displays a filter sidebar with category, type, and price range filters
3. Lists products with pagination (20 per page)
4. Shows product name, image, price, THC/CBD percentages
Use fetch() and the staging server URL.

Token Budget Reference

Using with MCP (Model Context Protocol)

Scalar supports creating MCP servers from OpenAPI documents. This lets AI tools like Claude, Cursor, and Warp interact with the API directly.

Setting up via Scalar Dashboard

1. Sign in to the Scalar Dashboard
2. Go to MCP → Create an MCP Server
3. Select your API and choose which endpoints to expose
4. Create an installation and authenticate with the staging API
5. Copy the installation URL

Connecting to Claude Code

claude mcp add \
  blaze-ecom-api \
  https://api.scalar.com/vector/mcp/YOUR_MCP_SERVER_ID \
  --header "Authorization: YOUR_PERSONAL_ACCESS_TOKEN" \
  --transport http

Tool Modes

For development, use Execute mode against the staging server. For production documentation queries, Search mode is safer.

OpenAPI Spec for Code Generation

The OpenAPI 3.1 spec (docs/api/openapi.yaml) can generate typed API clients:

TypeScript (recommended)

# Generate types from the spec
npx openapi-typescript docs/api/openapi.yaml -o src/api/schema.d.ts

# Use with openapi-fetch for type-safe requests
npm install openapi-fetch

import createClient from "openapi-fetch";
import type { paths } from "./schema";

const client = createClient<paths>({
  baseUrl: "https://ecom-api.staging.blaze.me",
  headers: {
    "X-Store": "e87437f2-3e35-4738-af5e-6307e368255c",
  },
});

// Fully typed — autocomplete on params, response shape, errors
const { data } = await client.GET("/api/v1/products", {
  params: { query: { limit: 20, category: "flower" } },
});

Python

npx @openapitools/openapi-generator-cli generate \
  -i docs/api/openapi.yaml \
  -g python \
  -o ./generated/python-client

Automation Skills for AI Agents

Three AI agent skills in .agents/skills/ automate documentation maintenance:

Example — ask your AI agent:

Run the api-docs-drift-check skill to see if there are any
undocumented endpoints in the router.

Recommended Workflow

For AI agents building a new frontend

1. Start with context: Load llms-full.txt as your primary API reference
2. Follow the storefront guide: See Building a Headless Storefront for a step-by-step walkthrough with ready-to-use agent prompts
3. Generate types: Run openapi-typescript against the spec for type-safe API calls
4. Validate: Use the staging server (https://ecom-api.staging.blaze.me) with store UUID e87437f2-3e35-4738-af5e-6307e368255c
5. Iterate: Ask the agent to read specific guides for deep dives (e.g., Payments for payment integration)

For AI agents maintaining existing code

1. Load the relevant guide as context (e.g., guides/cart-and-checkout.md for cart changes)
2. Cross-reference the Error Catalog for error handling
3. Run drift check before PRs to catch doc/code mismatches
4. Validate responses after deploys to catch schema drift

What's Next?

• Building a Headless Storefront — Complete step-by-step guide with AI agent prompts
• Quick Start — First API call in under 5 minutes
• General Concepts — JSON format, headers, pagination
• Error Catalog — All error codes with resolution guidance