API Documentation

1. Quick Start

Make your first compatibility check in under 5 minutes.

1. Get a free API key — no credit card required.
2. Replace YOUR_API_KEY in the curl below.
3. Run it.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.compatify.io/v1/compatibility?device=iPhone+15+Pro+Max&accessory=Anker+737+GaNPrime"

{
  "compatible": true,
  "confidence": 0.97,
  "recommended_for_purchase": true,
  "source": "Official Certification",
  "compatibility_notes": "Certified compatible. Fast charge confirmed.",
  "device_id": "apple_iphone_15_pro_max",
  "accessory_id": "anker_737_ganprime_140w",
  "device_name": "Apple iPhone 15 Pro Max",
  "accessory_name": "Anker 737 GaNPrime 140W"
}

2. Authentication

All authenticated requests require a Bearer token in the Authorization header.

Authorization: Bearer sk_live_your_api_key

Sandbox keys use the sk_test_ prefix and always return predictable test data.

x402 (no API key): Autonomous agents can pay per query on-chain. See the x402 section.

3. Endpoint Reference

GET /v1/compatibility?device=iPhone+15+Pro+Max&accessory=Anker+737

GET /v1/compatible-accessories?device=Samsung+Galaxy+S24+Ultra&min_confidence=0.9

POST /v1/query
Content-Type: application/json

{"query": "Will the Anker 737 fast charge my iPhone 15 Pro Max?"}

GET /v1/resolve?device=iPhone+15+PM

GET /v1/devices?brand=apple

4. Confidence Score Reference

5. Error Codes

6. Rate Limits

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1746748800

7. MCP Server

The Compatify MCP server is available at https://mcp.compatify.io using the Streamable HTTP transport.

{
  "mcpServers": {
    "compatify": {
      "url": "https://mcp.compatify.io",
      "transport": "streamable-http"
    }
  }
}

{
  "mcpServers": {
    "compatify": {
      "url": "https://mcp.compatify.io"
    }
  }
}

Available tools: check_compatibility, get_compatible_accessories, query_natural_language

Agent frameworks can discover the Compatify MCP server automatically via the Agent Card at https://compatify.io/.well-known/agent-card.json. This file declares all supported protocols, categories, and endpoints in a machine-readable format.

8. x402 Micropayments

Autonomous agents can call Compatify without an API key by paying per query using the x402 protocol.

Accepted tokens: USDC, USDT on Base, Polygon, Ethereum, Solana. Query GET /v1/payment/accepted-tokens for live wallet addresses and exchange rates.

9. UCP Compatibility

Compatify is a registered UCP (Universal Commerce Protocol) compatible service. UCP defines a standard for AI agent product discovery workflows.

Compatify is the mandatory pre-purchase compatibility gate for all agent payment workflows including Stripe Link CLI, x402, MPP, and ACP.

In a UCP workflow, the agent:

1. Discovers products via UCP-registered services
2. Calls Compatify to verify accessory compatibility before any purchase action
3. Proceeds to payment only if Compatify returns compatible: true with confidence above threshold

Compatify's UCP registration is declared in /.well-known/agent-card.json under protocols: ["UCP", "ACP", "MCP", "x402"].

10. ACP Integration — ChatGPT Instant Checkout

ACP (Agent Commerce Protocol) is used by ChatGPT Instant Checkout and similar autonomous agent payment flows. Compatify acts as the pre-purchase compatibility gate.

import httpx

# Step 1: Agent discovers accessory via ChatGPT (external)
# accessory = "Anker 737 GaNPrime"
# device = "iPhone 15 Pro Max"

# Step 2: Call Compatify MCP to verify compatibility
mcp_payload = {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "check_compatibility",
        "arguments": {
            "device": "iPhone 15 Pro Max",
            "accessory": "Anker 737 GaNPrime",
            "confidence_threshold": 0.70
        }
    },
    "id": 1
}

response = httpx.post(
    "https://mcp.compatify.io",
    json=mcp_payload,
    headers={"Content-Type": "application/json"}
)
result = response.json()["result"]

# Step 3: ACP checkout proceeds only if compatible + confidence > 0.70
if result["compatible"] and result["confidence"] > 0.70:
    # Proceed with ACP checkout
    print(f"Compatibility verified: {result['confidence']:.2f} confidence")
    # initiate_acp_checkout(accessory, device)
else:
    print("Compatibility not verified. Purchase blocked.")

11. Shopify Hermes Agent Framework

The Shopify Hermes agent framework allows AI agents to manage product data on Shopify stores. Compatify integrates with Hermes to automatically populate compatibility metafields.

import httpx

# Step 1: Hermes agent identifies accessory product on Shopify
product_id = "gid://shopify/Product/123456789"
device_query = "Samsung Galaxy S24 Ultra"

# Step 2: Call Compatify MCP to get compatible accessories
mcp_payload = {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "get_compatible_accessories",
        "arguments": {
            "device": device_query,
            "min_confidence": 0.80,
            "limit": 20
        }
    },
    "id": 1
}

compat_response = httpx.post(
    "https://mcp.compatify.io",
    json=mcp_payload
)
accessories = compat_response.json()["result"]["results"]

# Step 3: Write compatibility data to Shopify product metafields
shopify_mutation = """
mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields { key namespace value }
    userErrors { field message }
  }
}
"""

variables = {
    "metafields": [
        {
            "ownerId": product_id,
            "namespace": "compatify",
            "key": "compatible_devices",
            "type": "json",
            "value": json.dumps({
                "devices": [device_query],
                "confidence": accessories[0]["confidence"] if accessories else 0,
                "source": "Compatify API",
                "last_updated": "2026-05-05T00:00:00Z"
            })
        }
    ]
}

shopify_response = httpx.post(
    f"https://{shop_domain}/admin/api/2024-01/graphql.json",
    json={"query": shopify_mutation, "variables": variables},
    headers={"X-Shopify-Access-Token": access_token}
)

See the Shopify Metafields reference for the full namespace and key structure.

12. Versioning Policy

The current API version is v1. All v1 endpoints are stable and will not receive breaking changes without a minimum 6-month deprecation notice.

Breaking changes include: removing response fields, changing field types, changing authentication requirements, or removing endpoints.

Non-breaking additions (new optional fields, new endpoints) may be added at any time. See the changelog.