API Documentation

Everything you need to integrate Compatify into your product or agent workflow.

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_id=apple_iphone_17_pro&accessory_id=apple_silicone_case_iphone_17_pro"
Response
{
  "compatible": true,
  "confidence": 0.75,
  "notes": "Device model is on the accessory's manufacturer fitment list.",
  "source": "Apple",
  "source_type": "rule_engine",
  "source_tier": "manufacturer_spec",
  "source_method": "rule_engine",
  "source_url": "https://www.apple.com/shop/buy-iphone/iphone-17-pro/silicone-case-with-magsafe",
  "device_id": "apple_iphone_17_pro",
  "accessory_id": "apple_silicone_case_iphone_17_pro",
  "device_name": "Iphone 17 Pro",
  "accessory_name": "Silicone Case Iphone 17 Pro",
  "data_category": "phone_cases",
  "available_categories": null,
  "last_verified_at": null,
  "freshness_status": "never_verified",
  "freshness_reason": null,
  "under_review": false,
  "under_review_reason": null
}

2. Authentication

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

Authorization: Bearer sk_live_your_api_key

The sandbox, under /sandbox/v1/, needs no key and always returns predictable test data. A sk_test_ key is refused on the data routes with a 403.

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

3. Endpoint Reference

GET/v1/compatibility

Check if a specific accessory is compatible with a specific device.

ParamTypeRequiredDescription
device_idstringYesCanonical device ID, e.g. apple_iphone_15_pro (GET /v1/resolve turns a product name into one)
accessory_idstringYesCanonical accessory ID, e.g. anker_737_gan_prime_120w
data_categorystringNoWhich fact base answers when a pair is covered by more than one, e.g. magsafe_qi2 or phone_chargers_cables
GET /v1/compatibility?device_id=apple_iphone_15_pro&accessory_id=anker_737_gan_prime_120w
GET/v1/compatible-accessories

List all verified compatible accessories for a device.

ParamTypeRequiredDescription
device_idstringYesCanonical device ID, e.g. apple_iphone_15_pro
categorystringYesAccessory category: cases_and_covers | charging_cables | consumer_electronics | laptop_chargers | printer_ink_toner | screen_protectors | smart_home | usb_c_cables | wall_chargers
min_confidencefloatNoMinimum confidence threshold (default: 0.80)
pageintegerNoPage number (default: 1)
limitintegerNoResults per page (default: 50, max: 100)
GET /v1/compatible-accessories?device_id=apple_iphone_15_pro&category=wall_chargers&min_confidence=0.8
POST/v1/query

Processes natural language queries to return structured compatibility results.

ParamTypeRequiredDescription
querystringYesNatural language question
categorystringNoCategory hint
POST /v1/query
Content-Type: application/json

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

Resolve a raw device string to its canonical ID.

ParamTypeRequiredDescription
qstringYesRaw device string to resolve
categorystringNoOptional category hint (default: consumer_electronics)
GET /v1/resolve?q=iPhone+15+Pro
GET/v1/categories

List every category in the dataset with its own device and record counts, grouped into the five display families. Public, no auth. The `category` value each entry carries is what `data_category` on /v1/compatibility expects.

No parameters.

GET /v1/categories
GET/v1/devices

List all canonical devices in the catalog.

ParamTypeRequiredDescription
brandstringNoFilter by brand
limitintegerNoMax results (default: 50, max: 200)
GET /v1/devices?brand=Apple

4. Confidence Score Reference

The confidence score reflects how the fact was established: it is the lowest of the rules engine's confidence in the verdict and the confidence recorded on the device and accessory facts it rests on, and sits lower when the verdict rests on an inference rather than a stated specification.

Beside it, source_tier says what class of source the fact was read off — standards_body, manufacturer_spec, verified_retailer_listing or unverified, or null for a source outside those classes, such as independent testing, whose class source_method then names — and source_method says how it was established. source_url is the address of that same source and is returned only on an authenticated or x402-settled call — with one exception: each item in a list response carries source_tier and source_method and never a source URL, on an authenticated call as much as an anonymous one, and carries no last-verified or freshness field either, because a freshness label belongs to one fact base and a list can span several. Read a single verdict for those. last_verified_at is the last clean check for a pack verdict on GET/POST /v1/compatibility or pack-backed POST /v1/query, or null until both records were checked; legacy verdict routes GET /v1/printer-compatibility, GET /v1/pc-compatibility, POST /v1/smart-home/compatibility/check and POST /v1/laptop/compatibility/check always return null, while legacy list routes such as GET /v1/compatible-cartridges omit this field. freshness_status says whether the device and accessory records were checked within the category cadence: fresh, stale or never_verified. Frozen and catalog-gap states belong on the operator dashboard and in email, not in this field. On pack verdicts, under_review is true with under_review_reason frozen, source_unavailable, or record_flagged when the category is frozen, the last run checked no records, or either verdict record has an open flag; freshness_status stays verification age only. A stale fact base is still served.

Score rangeMeaningAgent recommendation
0.95 – 1.00Manufacturer statement or certification-body listingProceed with purchase
0.80 – 0.94Multiple verified third-party sources in agreementProceed with purchase
0.70 – 0.79Single verified source or strong community consensusProceed
0.50 – 0.69Partial or conflicting dataWarn user. Do not auto-purchase.
0.00 – 0.49Insufficient or conflicting dataBlock purchase. Escalate to human.

5. Error Codes

HTTP Statuserror fieldAgent handling
400validation_errorFix request parameters before retrying
401invalid_api_keyRe-authenticate. Do not retry with same key.
402payment_requiredx402: submit payment header and retry once
404device_not_foundTry /v1/resolve to normalize device name first
404accessory_not_foundBroaden accessory search or use natural language endpoint
429rate_limit_exceededWait for X-RateLimit-Reset header timestamp
503service_unavailableCheck status.compatify.io. Retry with exponential backoff.

6. Rate Limits

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1746748800
PlanPer minutePer month
Free1005,000
Growth50050,000
Pro1,000250,000
x402UnlimitedPay per query

7. MCP Server

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

Add as a custom connector in Claude (Settings → Connectors → Add custom connector → paste the URL; sign in when prompted).

Claude Desktop — claude_desktop_config.json
{
  "mcpServers": {
    "compatify": {
      "url": "https://mcp.compatify.io/mcp"
    }
  }
}
Cursor — .cursor/mcp.json
{
  "mcpServers": {
    "compatify": {
      "url": "https://mcp.compatify.io/mcp"
    }
  }
}

Available tools: check_compatibility, get_compatible_accessories, ask_compatibility_question

Connector traffic runs on the free tier.

Privacy policy: https://compatify.io/privacy.

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.

EndpointPrice
/v1/compatibility, /v1/compatible-accessories, /v1/query, and other paid routesPer endpoint (live at GET /v1/pricing)

Accepted token: USDC on Base. Query GET /v1/payment/accepted-tokens for live wallet addresses and exchange rates.

9. UCP Compatibility

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

Compatify provides pre-purchase compatibility verification for agent payment workflows, including x402.

In a UCP workflow, the agent:

  1. Discovers products via UCP-compatible services
  2. Checks accessory compatibility through Compatify ahead of the purchase action
  3. Uses the returned compatible flag and confidence score to decide whether to proceed to payment

Compatify's UCP discovery profile is served at /.well-known/ucp, and /.well-known/agent-card.json lists UCP under protocols: ["UCP", "MCP", "x402"].

10. 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.