> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enlazosystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Does the Proximos API Work?

> AWS Lambda-powered, polling Apple's GDMF every five minutes for new macOS releases.

## Architecture

The Proximos API runs entirely on AWS infrastructure:

<CardGroup cols={2}>
  <Card title="AWS Lambda" icon="bolt">
    Handles all request routing, database lookups, and response formatting for every API call.
  </Card>

  <Card title="AWS API Gateway" icon="shield-check">
    Manages HTTPS endpoints and validates every license key before forwarding requests.
  </Card>

  <Card title="Amazon DynamoDB" icon="database">
    Stores the macOS version database (primary and legacy tables) plus the license key authorization table.
  </Card>

  <Card title="AWS CloudWatch" icon="chart-line">
    Logs API activity: request counts per license key and the query data requested.
  </Card>
</CardGroup>

## 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:

| Field                    | Example      | Description                                     |
| ------------------------ | ------------ | ----------------------------------------------- |
| `board_id_major_version` | `J293AP:14`  | Primary key: board ID + colon + major version   |
| `major_version`          | `14`         | The macOS major version number                  |
| `version`                | `14.8.7`     | Latest known point release for this board/major |
| `releasedDate`           | `2026-05-11` | Release date of the latest point release        |

Point releases (e.g., `J293AP:14.7.2`) are stored as individual rows as well, enabling the [GET by BoardID:Version](/proximos-api/endpoints/get-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](/proximos-api/endpoints/get-boardid-version) will provide the fastest API response times. If possible, extract a Mac Board ID with shell command`ioreg -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](https://mrmacintosh.com/list-of-mac-boardid-deviceid-model-identifiers-machine-models/), 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 `J293AP`will 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:

| Era                          | Example board IDs                                                               |
| ---------------------------- | ------------------------------------------------------------------------------- |
| Power Mac G3 / G4 (Mac OS X) | `M5183` (B\&W G3 + G4 PCI/AGP/Gigabit/DA), `M8493` (QuickSilver), `M8570` (MDD) |
| Power Mac G5 (Mac OS X)      | `A1047` (all standard G5 models), `A1117` / `A1177` (Dual Core / Quad)          |
| iMac G3 (Mac OS X)           | `M4984` (233–333 MHz), `M5521` (350–700 MHz slot-loading)                       |
| iMac G4 / G5 (Mac OS X)      | `M6498`, `A1065`, `A1058`, `A1076`                                              |
| Classic Mac 68k              | `M0001` (Mac 128K), `M5119` (Mac SE/30), `M4150` (Classic II)                   |
| Classic Mac PPC              | `M1688` (Power Mac 8100), `M3979` (7200–7600 tower + Beige G3 Desktop)          |

Where Apple assigned a single model number to multiple machines (common practice), the database entry covers the **union of their compatible OS versions**.