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.
- Get a free API key — no credit card required.
- Replace YOUR_API_KEY in the curl below.
- 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"
{
"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
/v1/compatibilityCheck if a specific accessory is compatible with a specific device.
| Param | Type | Required | Description |
|---|---|---|---|
| device_id | string | Yes | Canonical device ID, e.g. apple_iphone_15_pro (GET /v1/resolve turns a product name into one) |
| accessory_id | string | Yes | Canonical accessory ID, e.g. anker_737_gan_prime_120w |
| data_category | string | No | Which 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
/v1/compatible-accessoriesList all verified compatible accessories for a device.
| Param | Type | Required | Description |
|---|---|---|---|
| device_id | string | Yes | Canonical device ID, e.g. apple_iphone_15_pro |
| category | string | Yes | Accessory category: cases_and_covers | charging_cables | consumer_electronics | laptop_chargers | printer_ink_toner | screen_protectors | smart_home | usb_c_cables | wall_chargers |
| min_confidence | float | No | Minimum confidence threshold (default: 0.80) |
| page | integer | No | Page number (default: 1) |
| limit | integer | No | Results per page (default: 50, max: 100) |
GET /v1/compatible-accessories?device_id=apple_iphone_15_pro&category=wall_chargers&min_confidence=0.8
/v1/queryProcesses natural language queries to return structured compatibility results.
| Param | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Natural language question |
| category | string | No | Category hint |
POST /v1/query
Content-Type: application/json
{"query": "Will the Anker 737 fast charge my iPhone 15 Pro Max?"}/v1/resolveResolve a raw device string to its canonical ID.
| Param | Type | Required | Description |
|---|---|---|---|
| q | string | Yes | Raw device string to resolve |
| category | string | No | Optional category hint (default: consumer_electronics) |
GET /v1/resolve?q=iPhone+15+Pro
/v1/categoriesList 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
/v1/devicesList all canonical devices in the catalog.
| Param | Type | Required | Description |
|---|---|---|---|
| brand | string | No | Filter by brand |
| limit | integer | No | Max 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 range | Meaning | Agent recommendation |
|---|---|---|
| 0.95 – 1.00 | Manufacturer statement or certification-body listing | Proceed with purchase |
| 0.80 – 0.94 | Multiple verified third-party sources in agreement | Proceed with purchase |
| 0.70 – 0.79 | Single verified source or strong community consensus | Proceed |
| 0.50 – 0.69 | Partial or conflicting data | Warn user. Do not auto-purchase. |
| 0.00 – 0.49 | Insufficient or conflicting data | Block purchase. Escalate to human. |
5. Error Codes
| HTTP Status | error field | Agent handling |
|---|---|---|
| 400 | validation_error | Fix request parameters before retrying |
| 401 | invalid_api_key | Re-authenticate. Do not retry with same key. |
| 402 | payment_required | x402: submit payment header and retry once |
| 404 | device_not_found | Try /v1/resolve to normalize device name first |
| 404 | accessory_not_found | Broaden accessory search or use natural language endpoint |
| 429 | rate_limit_exceeded | Wait for X-RateLimit-Reset header timestamp |
| 503 | service_unavailable | Check 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
| Plan | Per minute | Per month |
|---|---|---|
| Free | 100 | 5,000 |
| Growth | 500 | 50,000 |
| Pro | 1,000 | 250,000 |
| x402 | Unlimited | Pay 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).
{
"mcpServers": {
"compatify": {
"url": "https://mcp.compatify.io/mcp"
}
}
}{
"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.
| Endpoint | Price |
|---|---|
| /v1/compatibility, /v1/compatible-accessories, /v1/query, and other paid routes | Per 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:
- Discovers products via UCP-compatible services
- Checks accessory compatibility through Compatify ahead of the purchase action
- Uses the returned
compatibleflag 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.