Getting started

Query 14,941 phones, tablets, and smartwatches from 126 brands over HTTPS. Every request takes your API key and returns JSON.

Base URL

Append an endpoint path to this versioned HTTPS URL.

https://api.specspool.com/v1

Make your first request

1
Create an API key
Create a free account, confirm your email, then create a key in Dashboard → API keys. The full secret is shown once, so store it in an environment variable on your server.
macOS / Linux
```
export SPECSPOOL_API_KEY="YOUR_API_KEY"
```
PowerShell: $env:SPECSPOOL_API_KEY = "YOUR_API_KEY"
2
List brands
Send the key in the x-api-key header. This request needs no device slug.
```
curl --request GET 'https://api.specspool.com/v1/brands' \
  --header "x-api-key: $SPECSPOOL_API_KEY"
```
cURL examples assume a POSIX shell. In PowerShell, use curl.exe and $env:SPECSPOOL_API_KEY in a single-line command.

Read the response

Brands returns a data array and a revision object. Envelopes differ by endpoint; the data below is illustrative.

200 OK

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000010",
      "slug": "example-brand",
      "name": "Example Brand",
      "deviceCount": 2
    }
  ],
  "revision": {
    "revision": "example-revision",
    "updatedAt": "2026-10-01T00:00:00.000Z"
  }
}

Authentication

Every customer /v1 request requires x-api-key, except OPTIONS preflight. Call the API from your server; never put a secret key in browser or mobile app code. The free plan allows 1 active API key and does not include images. To rotate a free key, revoke it before creating and deploying the replacement.

Keys can call only GET /v1/search, GET /v1/devices/{slug}, POST /v1/compare, GET /v1/brands and GET /v1/categories. Other methods and routes, including HEAD, are denied before admission.

Authentication, key management and errors

Rate limits

Limits apply per account across all keys, in fixed UTC windows.

Limit	Free	Standard	Enterprise
Billable units	25 per calendar month (UTC)	No monthly quota; prepaid requests need enough credit	No monthly quota; contract terms apply
Calls	5 per minute	60 per minute	No RPM ceiling by default; custom rate available
Concurrent requests	1	4	4
Distinct devices	25 per hour, 25 per day	100 per hour, 500 per day	No hourly or daily quota
Discovery calls	25 per hour, 25 per day	120 per hour, 500 per day	No hourly or daily quota

The device budget deduplicates repeated identifiers and slug/UUID aliases by canonical device across detail and compare calls; missing identifiers use stable hashed tokens. Billing is separate: compare consumes one unit per submitted array entry, repeats included. Invalid requests and admission denials are not charged. Admitted work has a 20-second execution budget. On 429, wait for Retry-After.

Admitted responses include quota and rate-limit headers when applicable, with reset values as ISO 8601 UTC timestamps. Denied requests omit usage headers. Current usage is on the dashboard.

Plans and pricing

Status codes

Errors use { "error": { "code": "…", "message": "…" } }. Branch on the code; messages may change. Customer responses do not use an ETag or 304 workflow.

Status	Meaning
`200`	OK. Request succeeded; the response contains data.
`400`	Bad Request. Invalid query parameters, path values, or JSON request body.
`401`	Unauthorized. Missing, invalid, or revoked API key: api_key_missing, api_key_invalid, api_key_revoked.
`402`	Payment Required. Insufficient prepaid credit for the full request: insufficient_credit. Add credit in the dashboard.
`403`	Forbidden. Customer device listings are restricted (endpoint_not_available), or prepaid access is on hold (billing_hold).
`404`	Not Found. The requested device or route does not exist.
`429`	Rate Limited. A quota, minute, concurrency, device, discovery, or ingress limit was reached. Wait for Retry-After before retrying.
`503`	Service Unavailable. Authentication, ingress protection, an endpoint dependency, or the 20-second execution budget failed. Retry with backoff.

A device read pinned to an outdated generation can return 409. Compare can return 413 for a body larger than 8,192 bytes, or 422 for an unsupported comparison. Unexpected failures return 500. Each endpoint page lists its own error codes.

HTTP clients

No Specspool package is required. The examples use cURL, server-side JavaScript fetch and the Python standard library. Check the status before reading data, and retry temporary failures with backoff.

Next steps

Endpoint reference
Request and response schemas for the five customer endpoints.
Compare plans
Free for prototyping, then $0.03 / unit on Standard.
Build a device comparison
Compare 2-20 devices in the same supported category: phones, tablets, or smartwatches. Each submitted device consumes one billable unit; 20 devices cost $0.60 on prepaid Standard.
Response schema
Explore device fields, bounded search results, variants, categories and catalog revisions.