Start

Atlas API

The sourced reference catalog of consumer electronics, as JSON. Every fact comes with its source, the source's own words, its kind and a confidence, so you can show it, check it and cite it.

Open preview: no key is needed yet. Each IP may make 60 requests a minute. Keys and plans arrive with accounts; the header below is all you will need to add.

curl "https://api.devicedatabase.org/v1/devices?q=galaxy+s25"

Base URL https://api.devicedatabase.org/v1. Ids are opaque and permanent (dev_…); slugs work too. The machine-readable description is at /v1/openapi.json (OpenAPI 3.1).

Keys and authentication

Keys look like atlas_live_… or atlas_test_… and end in a checksum, so a mistyped key is refused at once. Send one as Authorization: Bearer atlas_live_…, never in a URL. We store only a keyed hash of each key: it is shown to you once, and a lost key is replaced, not recovered.

Limits and quotas

Every response says where you stand: RateLimit-Policy names the limit and RateLimit the requests left (an estimate) and seconds until the window resets. Over the limit you get a 429 with Retry-After.

Plan	Requests a month	Rate	Price (USD)	Policy
Open preview	None	60/min per IP	$0	"open";q=60;w=60
Free	10,000	2/s	$0	"free";q=20;w=10
Starter	100,000	10/s	$29	"starter";q=100;w=10
Pro	1,000,000	25/s	$149	"pro";q=250;w=10
Business	5,000,000	50/s	$599	"business";q=500;w=10
Internal	By agreement	100/s	$0	"internal";q=1000;w=10

Responses carry an ETag: send it back as If-None-Match and an unchanged answer is a bodiless 304. Lists page with an opaque cursor: pass next_cursor back until it is null.

Errors

Every error is an RFC 9457 problem document (application/problem+json) with a stable type to switch on.

{
  "type": "https://api.devicedatabase.org/problems/device_not_found",
  "title": "Device not found",
  "status": 404,
  "detail": "No device has the id or slug \"galaxy-s99\".",
  "instance": "/v1/devices/galaxy-s99"
}

Status	Type	Meaning
400	invalid_parameter	A query parameter is missing, malformed or out of range. `detail` names it.
400	invalid_cursor	The cursor was not issued by this API, or was edited. Start again without one.
401	missing_key	Send your key as `Authorization: Bearer atlas_live_…`.
401	invalid_key	The key is malformed, unknown, revoked or expired.
403	origin_not_allowed	Browsers may call the MCP server only from devicedatabase.org or localhost. Server-to-server calls send no Origin.
404	device_not_found	No device has this id or slug.
404	model_number_not_found	No regional model has this model number yet.
404	route_not_found	No route matches this method and path.
405	method_not_allowed	The MCP endpoint takes POST only: it is stateless and opens no event stream.
429	rate_limited	Slow down: the `RateLimit` and `Retry-After` headers say when to try again.
500	internal_error	Something failed on our side. It is logged; try again shortly.
503	catalog_unavailable	The catalog database cannot be reached right now. Try again shortly.

Sources, kinds and confidence

A fact's kind says what sort of claim it is: claimed, rated, typical, measured, regulatory, derived or rumoured. Kinds never compete: a rated and a typical battery capacity are both returned.

For each kind and scope one value is shown (rank: preferred); others are kept and come back with expand=all_values. When sources disagree, the lower tier wins: 1 a regulator, 2 the maker, 3 a lab, 4 open data, 5 a partner or the press, 6 a retailer, 7 the community. A value an editor reviewed is never replaced by an automatic reading.

Core facts are open under CC BY 4.0: show "Data: Techfleet Atlas, devicedatabase.org" with a link. Every fact repeats its licence, so a copied fact keeps its terms. Images are not covered by CC BY: each image carries its own licence and credit, and one marked example is a render standing for the model, to be shown with that label. The change feed is proprietary, under the API terms.

Reference / Devices

GET/v1/devicesAll plans

List devices

Devices by name or model number, filtered by department or brand, sorted by name. Every word of q must appear in the brand and name ("samsung s25" finds the Galaxy S25 Ultra), or q may be an exact model number. Merged devices are left out. Page with cursor.

Parameters

Name	In	Description
q	query	Words of the name, or an exact model number.
department	query	One department.
brand	query	A brand slug (`apple`) or id (`brd_…`).
limit	query	Items per page, 1 to 100. Default `20`.
cursor	query	`next_cursor` from the previous page. Opaque: pass it back as it came.

Response

Field	Type	Meaning
data	DeviceSummaryStrict[]
next_cursor	string · null
links	NextLinks

Errors

400 A parameter is missing or malformed (invalid_parameter), or the cursor is not one we issued (invalid_cursor).
401 No key (missing_key) or a bad one (invalid_key), when keys are required.
429 Over the rate limit (rate_limited). Retry-After says when to try again.
503 The catalog database cannot be reached (catalog_unavailable). Try again shortly.

curl https://api.devicedatabase.org/v1/devices -G \
  -d q=galaxy s25

const res = await fetch("https://api.devicedatabase.org/v1/devices?q=galaxy+s25");
const data = await res.json();

import requests

data = requests.get(
    "https://api.devicedatabase.org/v1/devices",
    params={"q": "galaxy s25"},
).json()

200 Response

{
  "data": [
    {
      "id": "dev_3f9a1c0b7e2d4a6f8c10",
      "slug": "galaxy-s25-ultra",
      "name": "Galaxy S25 Ultra",
      "department": "phones",
      "status": "released",
      "announced_on": "2025-01-22",
      "released_on": "2025-02-07",
      "brand": {
        "id": "brd_5b2e8f1a9c3d7e4f6a20",
        "name": "Samsung",
        "slug": "samsung"
      },
      "family": {
        "id": "fam_8d4c2b6a1e9f3c7d5b30",
        "name": "Galaxy S25",
        "slug": "galaxy-s25"
      },
      "updated_at": "2026-10-20T14:03:11.204Z",
      "image": null,
      "links": {
        "self": "https://api.devicedatabase.org/v1/devices/dev_3f9a1c0b7e2d4a6f8c10",
        "web": "https://devicedatabase.org/devices/galaxy-s25-ultra"
      }
    }
  ],
  "next_cursor": "WyJHYWxheHkgUzI1IFVsdHJhIiwiZGV2XzNmOWExYzBiN2UyZDRhNmY4YzEwIl0",
  "links": {
    "next": "https://api.devicedatabase.org/v1/devices?q=galaxy&cursor=WyJHYWxheHkgUzI1IFVsdHJhIiwiZGV2XzNmOWExYzBiN2UyZDRhNmY4YzEwIl0"
  }
}

Reference / Devices

GET/v1/devices/{id}All plans

Get a device

One device with its variants, regional models, identifiers and facts. facts has a key for every property of the device's department, in display order. Each is a list, because kinds never compete (a rated and a typical battery capacity are both shown) and scoped values sit side by side; or null when nothing is sourced yet, in which case the key is also in pending.

Every fact carries its value, unit, kind, confidence, source id, quote and licence. Add expand=sources for the full source records. A device that was merged into another answers with that device, and says so in merged_from.

Facts we know about but haven't sourced come back as null and are listed in pending. We never fill them with a guess.

Parameters

Name	In	Description
id required	path	An Atlas device id (`dev_…`) or its slug. Ids of merged devices answer with the device they merged into.
fields	query	Property keys to return, comma-separated, such as `display_in,battery_mah`. See /v1/properties.
expand	query	`sources` adds the full source records; `all_values` adds values that are not shown (rank `normal` or `deprecated`), with the reason.

Response

Field	Type	Meaning
id	string
slug	string
name	string
department	Department	One of `phones`, `tablets`, `watches`, `laptops`, `consoles`, `audio`, `cameras`, `monitors`.
status	enum	One of `rumoured`, `announced`, `released`, `discontinued`.
announced_on	Date
released_on	Date
brand	Ref
family	Ref · null
updated_at	string
image	Image · null	The first image, or null when the device has none yet.
links	object
merged_from	string	The id or slug you asked for, when it was merged into this device.
variants	object[]
regional_models	RegionalModel[]
identifiers	object[]
images	Image[]	Every image, in display order.
facts	object	Property key to its values, or null when nothing is sourced yet.
pending	string[]	Properties with no sourced value yet.
sources	Source[]	With `expand=sources`.
licence	Licence

The fact object

Field	Type	Meaning
value	number · string · boolean · array	A number, text, true/false, a list of numbers, or a date as YYYY-MM-DD; see the property's type.
unit	string · null	SI unit from the vocabulary, or null.
kind	enum	One of `claimed`, `rated`, `typical`, `measured`, `regulatory`, `derived`, `rumoured`.
confidence	enum	One of `high`, `medium`, `low`.
rank	enum	`preferred` is the value shown; the others appear only with `expand=all_values`. One of `preferred`, `normal`, `deprecated`.
rank_reason	string · null
scope	Scope	What the value is limited to. Empty means the whole subject.
subject	string	The device, variant (`var_…`) or regional model (`rgm_…`) the value is about.
source	string	The source's id; `expand=sources` for the record.
quote	string · null	The source's own words. Null only for open data and partner records.
retrieved_at	string · null	When we read the source.
archived_url	string · null	The Wayback Machine copy of the source as read.
valid_from	Date
valid_to	Date
recorded_at	string	When Atlas recorded the value.
reviewed	boolean	An editor checked it.
licence	"CC-BY-4.0"

The source object

Field	Type	Meaning
id	string
kind	enum	One of `regulator`, `maker_page`, `maker_press`, `maker_store`, `open_data`, `partner`, `lab`, `press`, `retailer`, `community`.
publisher	string
url	string
tier	integer	Precedence when sources disagree: 1 (a regulator) wins.

Errors

400 A parameter is missing or malformed (invalid_parameter), or the cursor is not one we issued (invalid_cursor).
401 No key (missing_key) or a bad one (invalid_key), when keys are required.
404 No such device (device_not_found) or model number (model_number_not_found).
429 Over the rate limit (rate_limited). Retry-After says when to try again.
503 The catalog database cannot be reached (catalog_unavailable). Try again shortly.

curl https://api.devicedatabase.org/v1/devices/galaxy-s25-ultra -G \
  -d fields=display_in,battery_mah \
  -d expand=sources

const res = await fetch("https://api.devicedatabase.org/v1/devices/galaxy-s25-ultra?fields=display_in%2Cbattery_mah&expand=sources");
const data = await res.json();

import requests

data = requests.get(
    "https://api.devicedatabase.org/v1/devices/galaxy-s25-ultra",
    params={"fields": "display_in,battery_mah", "expand": "sources"},
).json()

200 Response

{
  "id": "dev_3f9a1c0b7e2d4a6f8c10",
  "slug": "galaxy-s25-ultra",
  "name": "Galaxy S25 Ultra",
  "department": "phones",
  "status": "released",
  "announced_on": "2025-01-22",
  "released_on": "2025-02-07",
  "brand": {
    "id": "brd_5b2e8f1a9c3d7e4f6a20",
    "name": "Samsung",
    "slug": "samsung"
  },
  "family": {
    "id": "fam_8d4c2b6a1e9f3c7d5b30",
    "name": "Galaxy S25",
    "slug": "galaxy-s25"
  },
  "updated_at": "2026-10-20T14:03:11.204Z",
  "image": {
    "width": 1200,
    "height": 1200,
    "alt": "Galaxy S25 Ultra in Titanium Silverblue",
    "colour": "Titanium Silverblue",
    "example": false,
    "credit": "Samsung",
    "licence": "Samsung press image",
    "variants": [
      {
        "width": 300,
        "url": "https://devicedatabase.org/media/devices/galaxy-s25-ultra/silverblue-300.webp"
      },
      {
        "width": 600,
        "url": "https://devicedatabase.org/media/devices/galaxy-s25-ultra/silverblue-600.webp"
      },
      {
        "width": 1200,
        "url": "https://devicedatabase.org/media/devices/galaxy-s25-ultra/silverblue-1200.webp"
      }
    ]
  },
  "links": {
    "self": "https://api.devicedatabase.org/v1/devices/dev_3f9a1c0b7e2d4a6f8c10",
    "web": "https://devicedatabase.org/devices/galaxy-s25-ultra"
  },
  "variants": [
    {
      "id": "var_1a2b3c4d5e6f7a8b9c00",
      "name": "12 GB / 256 GB",
      "axes": {
        "storage_gb": 256,
        "ram_gb": 12
      }
    }
  ],
  "regional_models": [
    {
      "id": "rgm_9f8e7d6c5b4a3f2e1d00",
      "model_number": "SM-S938W",
      "region": "CA",
      "carrier": null
    }
  ],
  "identifiers": [
    {
      "kind": "wikidata",
      "value": "Q131234567"
    }
  ],
  "images": [
    {
      "width": 1200,
      "height": 1200,
      "alt": "Galaxy S25 Ultra in Titanium Silverblue",
      "colour": "Titanium Silverblue",
      "example": false,
      "credit": "Samsung",
      "licence": "Samsung press image",
      "variants": [
        {
          "width": 300,
          "url": "https://devicedatabase.org/media/devices/galaxy-s25-ultra/silverblue-300.webp"
        },
        {
          "width": 600,
          "url": "https://devicedatabase.org/media/devices/galaxy-s25-ultra/silverblue-600.webp"
        },
        {
          "width": 1200,
          "url": "https://devicedatabase.org/media/devices/galaxy-s25-ultra/silverblue-1200.webp"
        }
      ]
    }
  ],
  "facts": {
    "battery_mah": [
      {
        "value": 5000,
        "unit": "mAh",
        "kind": "typical",
        "confidence": "high",
        "rank": "preferred",
        "rank_reason": null,
        "scope": {},
        "subject": "dev_3f9a1c0b7e2d4a6f8c10",
        "source": "src_4e5f6a7b8c9d0e1f2a30",
        "quote": "Battery Capacity (mAh, Typical) 5000",
        "retrieved_at": "2026-10-18T09:12:40.000Z",
        "archived_url": null,
        "valid_from": null,
        "valid_to": null,
        "recorded_at": "2026-10-18T09:13:02.551Z",
        "reviewed": true,
        "licence": "CC-BY-4.0"
      }
    ],
    "peak_nits": null
  },
  "pending": [
    "peak_nits"
  ],
  "sources": [
    {
      "id": "src_4e5f6a7b8c9d0e1f2a30",
      "kind": "maker_page",
      "publisher": "Samsung",
      "url": "https://www.samsung.com/ca/smartphones/galaxy-s25-ultra/specs/",
      "tier": 2
    }
  ],
  "licence": {
    "facts": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/",
    "attribution": "Data: Techfleet Atlas, devicedatabase.org"
  }
}

Reference / Devices

GET/v1/devices/{id}/historyAll plans

Device history

Every fact recorded or superseded on the device, its variants and its regional models, newest first, with the changeset that wrote it. Capped at the newest 1,000 entries.

Parameters

Name	In	Description
id required	path	An Atlas device id (`dev_…`) or its slug. Ids of merged devices answer with the device they merged into.

Response

Field	Type	Meaning
device	DeviceSummaryStrict
merged_from	string
data	HistoryEntry[]

Errors

401 No key (missing_key) or a bad one (invalid_key), when keys are required.
404 No such device (device_not_found) or model number (model_number_not_found).
429 Over the rate limit (rate_limited). Retry-After says when to try again.
503 The catalog database cannot be reached (catalog_unavailable). Try again shortly.

curl https://api.devicedatabase.org/v1/devices/galaxy-s25-ultra/history

const res = await fetch("https://api.devicedatabase.org/v1/devices/galaxy-s25-ultra/history");
const data = await res.json();

import requests

data = requests.get(
    "https://api.devicedatabase.org/v1/devices/galaxy-s25-ultra/history",
).json()

200 Response

{
  "device": {
    "id": "dev_3f9a1c0b7e2d4a6f8c10",
    "slug": "galaxy-s25-ultra",
    "name": "Galaxy S25 Ultra",
    "department": "phones",
    "status": "released",
    "announced_on": "2025-01-22",
    "released_on": "2025-02-07",
    "brand": {
      "id": "brd_5b2e8f1a9c3d7e4f6a20",
      "name": "Samsung",
      "slug": "samsung"
    },
    "family": null,
    "updated_at": "2026-10-20T14:03:11.204Z",
    "image": null,
    "links": {
      "self": "https://api.devicedatabase.org/v1/devices/dev_3f9a1c0b7e2d4a6f8c10",
      "web": "https://devicedatabase.org/devices/galaxy-s25-ultra"
    }
  },
  "data": [
    {
      "property": "weight_g",
      "value": 218,
      "kind": "claimed",
      "rank": "preferred",
      "recorded_at": "2026-10-18T09:13:02.551Z",
      "superseded_at": null,
      "changeset": "cs_0a1b2c3d4e5f6a7b8c90",
      "comment": "Samsung Canada spec page, October 2026"
    }
  ]
}

Reference / Identify

GET/v1/identifyAll plans

Identify a model number

A model number (A3256, SM-S938W) to its device and regional model. Any letter case.

Parameters

Name	In	Description
model_number required	query	The model number printed on the device, its box or in its settings.

Response

Field	Type	Meaning
device	DeviceSummaryStrict
merged_from	string	The device the model number is filed under, when it was merged into `device`.
regional_model	RegionalModel

Errors

400 A parameter is missing or malformed (invalid_parameter), or the cursor is not one we issued (invalid_cursor).
401 No key (missing_key) or a bad one (invalid_key), when keys are required.
404 No such device (device_not_found) or model number (model_number_not_found).
429 Over the rate limit (rate_limited). Retry-After says when to try again.
503 The catalog database cannot be reached (catalog_unavailable). Try again shortly.

curl https://api.devicedatabase.org/v1/identify -G \
  -d model_number=SM-S938W

const res = await fetch("https://api.devicedatabase.org/v1/identify?model_number=SM-S938W");
const data = await res.json();

import requests

data = requests.get(
    "https://api.devicedatabase.org/v1/identify",
    params={"model_number": "SM-S938W"},
).json()

200 Response

{
  "device": {
    "id": "dev_3f9a1c0b7e2d4a6f8c10",
    "slug": "galaxy-s25-ultra",
    "name": "Galaxy S25 Ultra",
    "department": "phones",
    "status": "released",
    "announced_on": "2025-01-22",
    "released_on": "2025-02-07",
    "brand": {
      "id": "brd_5b2e8f1a9c3d7e4f6a20",
      "name": "Samsung",
      "slug": "samsung"
    },
    "family": {
      "id": "fam_8d4c2b6a1e9f3c7d5b30",
      "name": "Galaxy S25",
      "slug": "galaxy-s25"
    },
    "updated_at": "2026-10-20T14:03:11.204Z",
    "image": null,
    "links": {
      "self": "https://api.devicedatabase.org/v1/devices/dev_3f9a1c0b7e2d4a6f8c10",
      "web": "https://devicedatabase.org/devices/galaxy-s25-ultra"
    }
  },
  "regional_model": {
    "id": "rgm_9f8e7d6c5b4a3f2e1d00",
    "model_number": "SM-S938W",
    "region": "CA",
    "carrier": null
  }
}

Reference / Vocabulary

GET/v1/propertiesAll plans

List properties

The vocabulary a fact may name, in display order, with each property's type and SI unit.

Parameters

Name	In	Description
department	query	One department.

Response

Field	Type	Meaning
data	Property[]

Errors

400 A parameter is missing or malformed (invalid_parameter), or the cursor is not one we issued (invalid_cursor).
401 No key (missing_key) or a bad one (invalid_key), when keys are required.
429 Over the rate limit (rate_limited). Retry-After says when to try again.
503 The catalog database cannot be reached (catalog_unavailable). Try again shortly.

Reference / Changes

GET/v1/changesAll plans

Changes since

Devices that changed after since (an edit, or a fact recorded or superseded on them), oldest change first. Page with cursor, keeping the same since; store the last changed_at you saw and pass it next time. A device that changes again while you page turns up again later. Proprietary, under the API terms.

Parameters

Name	In	Description
since required	query	An ISO 8601 date, or a timestamp with an offset.
limit	query	Items per page, 1 to 100. Default `20`.
cursor	query	`next_cursor` from the previous page. Opaque: pass it back as it came.

Response

Field	Type	Meaning
data	object[]
next_cursor	string · null
links	NextLinks

Errors

400 A parameter is missing or malformed (invalid_parameter), or the cursor is not one we issued (invalid_cursor).
401 No key (missing_key) or a bad one (invalid_key), when keys are required.
429 Over the rate limit (rate_limited). Retry-After says when to try again.
503 The catalog database cannot be reached (catalog_unavailable). Try again shortly.

curl https://api.devicedatabase.org/v1/changes -G \
  -d since=2026-10-01T00:00:00Z

const res = await fetch("https://api.devicedatabase.org/v1/changes?since=2026-10-01T00%3A00%3A00Z");
const data = await res.json();

import requests

data = requests.get(
    "https://api.devicedatabase.org/v1/changes",
    params={"since": "2026-10-01T00:00:00Z"},
).json()

200 Response

{
  "data": [
    {
      "id": "dev_3f9a1c0b7e2d4a6f8c10",
      "slug": "galaxy-s25-ultra",
      "changed_at": "2026-10-20T14:03:11.204Z",
      "links": {
        "self": "https://api.devicedatabase.org/v1/devices/dev_3f9a1c0b7e2d4a6f8c10"
      }
    }
  ],
  "next_cursor": null,
  "links": {
    "next": null
  }
}

Reference / Service

GET/v1/healthAll plans

Health

Whether the API is up, and whether keys are required. Never needs a key; never touches the database.

Response

Field	Type	Meaning
ok	boolean
service	"atlas-api"
version	"v1"
access	enum	Whether a key is required. One of `open_preview`, `keys`.

Reference / Service

GET/v1/openapi.jsonAll plans

This document

The OpenAPI 3.1 description of this API, as JSON. Never needs a key.

MCP server

AI assistants and agents can use Atlas directly over the Model Context Protocol (Streamable HTTP, protocol revisions 2026-07-28 and 2025) at https://mcp.devicedatabase.org/mcp, with the same keys and limits as the API. Every tool answers with the same JSON as the API, sources and quotes included, so an assistant can cite each value. Read-only tools:

search_devices
get_device
identify
get_fact_sources
compare_devices

claude mcp add --transport http atlas https://mcp.devicedatabase.org/mcp