Authentication

Authenticate customer API requests with an API key sent in the x-api-key header.

Get an API key

Create a free account or sign in. Confirm your email before creating keys.
Open Dashboard → API keys and select Create key. Enter a name with 1-80 characters and confirm creation.
Copy the full secret before closing the dialog. It starts with ss_live_ followed by 64 lowercase hexadecimal characters. The full secret is shown only when created; the key list displays a masked prefix.

Send the key

Store the key in a server environment variable named SPECSPOOL_API_KEY. Send the full secret in x-api-key with every /v1 request. OPTIONS preflight and /health do not require a key. Use HTTPS.

macOS / Linux: export SPECSPOOL_API_KEY="YOUR_API_KEY"
PowerShell: $env:SPECSPOOL_API_KEY = "YOUR_API_KEY"

curl --request GET 'https://api.specspool.com/v1/brands' \
  --header "x-api-key: $SPECSPOOL_API_KEY"

Run cURL examples in a POSIX shell; in PowerShell, use curl.exe and $env:SPECSPOOL_API_KEY in a single-line command. JavaScript uses server-side fetch; Python uses its standard library. Check HTTP status before reading response data.

Account limits

Limits apply to your whole account, across all active keys. An admitted full-spec request consumes one billable unit; comparisons consume one unit per submitted array entry. Twenty entries use 20 units ($0.60 on prepaid Standard). Other admitted calls use one unit. Later route errors still count. Invalid requests and authorization, quota, limit or credit denials are rejected before admission and are not charged. Minute and discovery limits count HTTP calls. The device security budget counts distinct canonical devices across detail and compare, independently of raw-entry billing. Your current usage is on the dashboard.

Monthly billable units	25 billable units per calendar month (UTC)
Rate limit	5 admitted HTTP calls per fixed UTC minute
Concurrent requests	1 active request per account
Distinct devices	25 per fixed UTC hour and 25 per fixed UTC day
Discovery	25 calls per fixed UTC hour and 25 per fixed UTC day
Active keys	1 per account
Device images	Image URLs omitted from API responses

Admitted requests include X-Api-Quota-Remaining and X-Api-Quota-Reset for bounded monthly quotas, plus X-RateLimit-Remaining and X-RateLimit-Reset for bounded minute limits. Monthly remaining counts billable units; minute remaining counts HTTP calls. Reset values are ISO 8601 UTC timestamps. Denied requests omit these usage headers.

Standard allows 60 calls per fixed UTC minute, 4 concurrent requests, 100 distinct devices per hour and 500 per day, plus 120 discovery calls per hour and 500 per day. These account-wide windows include every active key. Paid plans have no monthly unit quota; prepaid Standard still requires enough credit for the entire request. Enterprise has no default RPM ceiling or hourly/daily discovery or distinct-device quotas; an admin can configure a custom RPM limit. Enterprise retains four concurrent requests per account and separate abuse protections.

The device budget uses canonical device UUIDs shared by detail and compare requests. Repeating an identifier, or using a slug and UUID alias for the same device, occupies one slot in the fixed UTC window across all account keys. Missing identifiers use a hashed token, so the same missing value occupies one slot. If that identifier later resolves after publication, its canonical UUID can occupy a new slot. Compare billing remains separate and counts every submitted array entry.

Admitted work has a 20-second execution budget. A concurrency lease can remain reserved for up to 45 seconds so a crashed worker cannot occupy a slot forever. Timeouts can be retried with backoff; each retry is a new request.

Abuse protection

Customer API ingress is configured for 600 requests per 60 seconds per IP and Cloudflare location, across all plans. These counters are approximate; customers sharing an IP share this ceiling. Abuse denials occur before key authentication and do not consume plan quota or prepaid credit. Account-level concurrency, device, discovery and minute-limit denials are also rejected without charge. Follow Retry-After and retry with backoff.

Each account can successfully create at most five keys in a rolling hour and twenty in a rolling 24 hours, subject to its active-key limit. Revoked keys still count toward these creation windows. Revocation remains available when creation is blocked. A key-creation 429 supplies Retry-After: 3600; the daily limit may still prevent creation after that wait.

Customer API errors

Errors return { "error": { "code": "…", "message": "…" } }. Branch on code, not on the message. 429 responses include Retry-After in seconds.

Status	Code	Cause	Fix
401	`api_key_missing`	No x-api-key header was sent.	Add the x-api-key header to every request.
401	`api_key_invalid`	The key is malformed or does not belong to an existing Specspool account.	Copy the full secret again or create a new key in the dashboard.
401	`api_key_revoked`	The key was revoked.	Create a new key and update your environment variable.
429	`quota_exceeded`	Your account has insufficient monthly billable units for this request.	Wait until the quota resets (see Retry-After) or upgrade your plan.
429	`rate_limit_exceeded`	Too many requests in the current minute.	Wait for the number of seconds in Retry-After, then retry.
503	`api_auth_unavailable`	Key verification is temporarily unavailable.	Retry with exponential backoff.
429	`abuse_rate_limited`	Ingress abuse protection rejected this request before authentication.	Wait for Retry-After, then retry with backoff. This is separate from your plan quota.
503	`abuse_protection_unavailable`	Ingress abuse protection is unavailable.	Retry with exponential backoff. The request was not admitted or counted.
402	`insufficient_credit`	Prepaid Standard has insufficient credit for the entire request: $0.03 per unit, or $0.60 for a 20-device comparison.	Add credit in the dashboard. This denied request creates no usage charge.
403	`billing_hold`	A refund or dispute requires payment review.	Ask for billing review. Prepaid requests stay paused until reconciliation.
403	`endpoint_not_available`	The method or route is not part of the customer allowlist. This includes HEAD and internal autocomplete, stats, trending, version, landing, view-recording, and brand or category device-listing routes.	Use only GET /v1/search, GET /v1/devices/{slug}, POST /v1/compare, GET /v1/brands, or GET /v1/categories. Use search with a valid q to discover devices. This rejected request is not billed.
429	`concurrency_limit_exceeded`	Your account already has the maximum number of customer requests running.	Wait for Retry-After, then retry. Reduce parallel requests.
429	`device_limit_exceeded`	The fixed UTC hourly or daily distinct-device limit was reached.	Wait for Retry-After. Request fewer distinct devices during the window.
429	`discovery_limit_exceeded`	The fixed UTC hourly or daily discovery-call limit was reached.	Wait for Retry-After. Cache brand and category discovery results in your application.
503	`request_timeout`	Admitted work exceeded the 20-second execution budget.	Retry with backoff. Each retry is a new request and can be admitted separately.

Key management errors

Creating, listing, and revoking keys in the dashboard requires your signed-in session. A catalog API key does not replace that session. These errors also use the error.code and error.message envelope.

Status	Code	Cause	Fix
401	`unauthenticated`	Your signed-in session is missing or invalid.	Sign in again to manage keys.
403	`email_confirmation_required`	Your email has not been confirmed.	Confirm your email before creating a key. You can still revoke existing keys.
409	`api_key_limit_reached`	Your account already has the maximum number of active keys for its plan.	Revoke an existing key before creating another, or upgrade your plan.
429	`api_key_creation_rate_limited`	Your account reached the rolling key-creation limit.	Follow Retry-After. Creation remains blocked until both rolling limits allow another key; revocation is still available.
400	`invalid_request`	The key name or key-management request is invalid.	Use a key name with 1-80 characters after trimming and retry from the dashboard.
404	`api_key_not_found`	The key was not found among keys owned by your account.	Refresh the dashboard and select a key belonging to your account.
503	`api_access_unavailable`	The account or key-management service is temporarily unavailable.	Retry later with backoff.

Keep keys safe

Call the API from your server. Never put a key in browser or mobile app code.
On plans with multiple active keys, use one per environment so you can revoke them separately.
On Free, revoke your current key before creating and deploying a replacement. Plan for an interruption in API access while replacing your only active key. On plans with spare key slots, deploy the replacement before revoking the old key. If all slots are occupied, revoke an unused key to make room first. Once revocation succeeds, subsequent key checks return 401 api_key_revoked. Requests already admitted can finish and remain counted.
If a key leaks, revoke it immediately. If you lose the full secret, revoke the key and create a replacement; it cannot be retrieved from the key list.