Specspool API / Getting Started

Getting started with the Specspool API

The Specspool API gives you programmatic access to a structured catalog of phones, tablets, and smartwatches — 14,561 devices across 126 brands. Authenticate once, query anything, ship in minutes.

How a request flows

Your app

Web · Mobile · Server

HTTPS · TLS 1.3

Specspool API

Edge · 14 regions

JSON · <120 ms p95

Your response

Typed · Paginated

01 · The basics

Base URL

Every endpoint in this reference is appended to the canonical base URL. We require HTTPS — plain HTTP requests are redirected with 308.

BASE

https://api.specspool.com/v1

02 · 3-minute setup

Make your first request

From signup to a live JSON response in three steps. No SDK required — every endpoint works with plain HTTP.

Grab an API key

Sign up for a free Developer account — no credit card. Your credentials show up in Dashboard → API Keys with read scope and 100 requests/minute.

shell

# export credentials once per shell session
export SPECSPOOL_API_ID="sp_live_pub_•••••••••"
export SPECSPOOL_API_KEY="••••••••••••••••"

Call any endpoint

Pass your x-api-id and x-api-key headers. Below: fetch the iPhone 16 Pro Max full specification.

curl --request GET \
  --url 'https://api.specspool.com/v1/products/iphone-16-pro-max' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'x-api-id: sp_live_pub_•••••••••' \
  --header 'x-api-key: ••••••••••••••••'

Inspect the response

You get a typed JSON envelope with data and meta. Every spec category is normalised so the same field name behaves identically across vendors.

application/json

{
  "data": {
    "id": "iphone-16-pro-max",
    "brand": "Apple",
    "display": {
      "size_in": 6.9,
      "panel": "LTPO OLED",
      "refresh_hz": 120
    }
  },
  "meta": { "request_id": "req_8f3…b21" }
}

03 · Identity

Authentication

All requests must include your API ID and key in the x-api-id and x-api-key headers. Keys are scoped (read, write, admin), regionable, and revocable from the dashboard.

Header format

x-api-id: sp_live_pub_•••••••••
x-api-key: ••••••••••••••••
Accept: application/json
User-Agent: your-app/1.0

sp_live_pub_4f9b2c••••••••••a02e

Key scopes

read — query products, brands, schemas
write — submit corrections, hotfix data
admin — manage org, billing, members

Keys are prefixed by environment — sp_test_pub_ hits the sandbox, sp_live_pub_ hits production.

04 · Quotas

Rate limits

Limits are per-key, per-minute, smoothed over a 10-second window. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset headers so you can pace clients gracefully.

FreeNo card

100 /min

Developer$0.02 / req

5,000 /min

TeamVolume

25,000 /min

EnterpriseNegotiated

Custom SLA

05 · Failure modes

Status codes

We follow standard HTTP semantics. Error bodies always include a stable code string you can branch on — never parse the human-readable message.

200

Request succeeded, response contains data.

400

Bad Request

Malformed query, invalid filter, or unknown field name.

401

Unauthorized

Missing, malformed, or revoked API credentials.

404

Not Found

Product / brand / schema slug does not exist.

429

Rate Limited

You hit the per-minute quota. Back off using Retry-After.

06 · Libraries

Official SDKs

First-party libraries with typed models, retry/backoff, and streaming pagination. Community ports listed on GitHub.

Node / TypeScript

npm i specspool · v0.7.2

Python

pip install specspool · v0.6.1

Ruby

gem install specspool · v0.4.0

go get io/specspool · v0.3.5

PHP

composer require specspool · v0.2.8

Rust

cargo add specspool · v0.1.4

07 · Keep going

What to explore next

You've got the basics. Pick a path that matches what you're building.

Reference