Skip to main content

​
Architecture

The Proximos API runs entirely on AWS infrastructure:

AWS Lambda

Handles all request routing, database lookups, and response formatting for every API call.

AWS API Gateway

Manages HTTPS endpoints and validates every license key before forwarding requests.

Amazon DynamoDB

Stores the macOS version database (primary and legacy tables) plus the license key authorization table.

AWS CloudWatch

Logs API activity: request counts per license key and the query data requested.

​
Staying current

The Proximos API polls Apple’s GDMF service every five minutes for new macOS releases. When Apple publishes a new version, it is added to the database automatically — no manual intervention required. The Proximos API is typically updated within minutes of Apple publishing a new macOS release.

​
Request flow

  1. Your client sends a GET request to proximosapi.enlazosystems.com/items/{query} with your license key in the Authorization header.
  2. AWS API Gateway validates the license key against the authorization database.
  3. If authorized, the Lambda function is invoked and queries DynamoDB for the matching record.
  4. The result is returned as a JSON response.

​
Database structure

The database uses a DynamoDB composite key called board_id_major_version (e.g., J293AP:14). Each summary record stores: Point releases (e.g., J293AP:14.7.2) are stored as individual rows as well, enabling the GET by BoardID:Version endpoint to find the next available update from any specific version.

​
Best Response Performance

Using a primary key lookup GET by BoardID:Version will provide the fastest API response times. If possible, extract a Mac Board ID with shell commandioreg -l | grep board-id and use it in your API call.

​
What is a BoardID?

A BoardID is Apple’s internal identifier for a specific logic board configuration within a Mac model line. Because modern Macs have components like RAM, storage, and processors soldered directly to the logic board, a single model — such as a MacBook Air 13” — can ship with several distinct hardware configurations. A BoardID allows Apple, developers, and system administrators to identify exactly which variant they are working with. BoardIDs are a developer-facing concept and are not surfaced to end users in typical macOS workflows.

​
BoardIDs and the Proximos API

Apple uses BoardIDs — not consumer-facing model numbers — as the key for delivering targeted macOS update packages through its GDMF service. This per-board targeting enables more precise update delivery and reduces the risk of applying incompatible software to the wrong hardware configuration. Because BoardIDs are what Apple’s GDMF service supplies, the Proximos API uses them as the primary lookup key for all queries.

​
BoardID References

The most comprehensive publicly available BoardID reference is maintained by Mr. Macintosh, though it was last updated in January 2023.

​
Board ID coverage

The J293AP (M1 MacBook Pro) is used as the canonical representative board for version-only lookups covering macOS 11 through the latest release. If a BoardID is not supplied, then J293APwill be used as the primary key lookup. For PowerPC Macs (Mac OS X 10.0–10.5) and Classic Mac OS (System 0.97–Mac OS 9.2.2), the Apple model number is used as the board ID in place of a hardware board identifier string. These are the same model numbers physically printed on the machines and documented by EveryMac.com — for example: Where Apple assigned a single model number to multiple machines (common practice), the database entry covers the union of their compatible OS versions.