# NDX developer docs

NDX (getndx.com) is a trading card collection product. This page is the public developer entry point: how to find the OpenAPI specification, which endpoints are reachable without a user session, and how authenticated collector APIs work.

## When to call NDX

Call these APIs when you need to:

- Add an email to the NDX launch waitlist
- Check that the NDX consumer API is up
- Read a collector's **public** shared library views
- Sign a collector in with Apple or Google and then read their collection, prices, or release calendar (authenticated)

Do not call NDX to scrape the full trading-card catalog, to place marketplace orders, or to impersonate a collector. Catalog identification and most collection writes require a signed-in NDX user.

## Discoverability

| Resource | URL |
|---|---|
| OpenAPI 3.1 (JSON) | https://getndx.com/openapi.json |
| OpenAPI 3.1 (YAML) | https://getndx.com/openapi.yaml |
| Agent summary | https://getndx.com/llms.txt |
| This page | https://getndx.com/developers |
| Consumer API host | https://api.getndx.com |
| Marketing site | https://getndx.com/ |

## Public endpoints

These do not require a collector session.

### Waitlist — `POST https://getndx.com/api/waitlist`

Adds an email to the NDX launch waitlist. Idempotent: repeating the same email still returns success.

```http
POST /api/waitlist HTTP/1.1
Host: getndx.com
Content-Type: application/json

{"email":"collector@example.com"}
```

```json
{"ok":true}
```

A hidden `website` field is a honeypot. Bots that fill it still receive `{"ok":true}` and are not stored.

### Health — `GET https://api.getndx.com/healthz`

Liveness. Returns `{"status":"ok"}` without touching the database.

### Readiness — `GET https://api.getndx.com/health`

Readiness. Pings Postgres. Use this to decide whether the consumer API can serve traffic.

### Public library views — `GET https://api.getndx.com/v1/public/u/{userId}/views`

Lists a collector's published library views. `{userId}` is the collector's NDX user UUID. Unauthenticated.

### Public view query — `GET https://api.getndx.com/v1/public/u/{userId}/views/{slug}/query`

Returns the cards in one published view. Optional `limit` (1–100) and `cursor` query parameters.

## Authentication

Collector APIs under `https://api.getndx.com/v1/` expect:

```
Authorization: Bearer <ndx-session-token>
```

Mint a session by posting a provider identity token to:

- `POST /v1/auth/apple`
- `POST /v1/auth/google`

The request body is JSON with the provider credential the iOS or web client already obtained. The response includes a short-lived NDX access token and a refresh token (`POST /v1/auth/refresh`). There is no public API key for catalog-wide access.

Example authenticated call:

```http
GET /v1/me HTTP/1.1
Host: api.getndx.com
Authorization: Bearer <ndx-session-token>
```

`GET /v1/me/portfolio` returns collection value. `GET /v1/release-calendar/` returns upcoming releases. Both require the bearer token.

## Spec quality

Every operation in [openapi.json](/openapi.json) has a unique `operationId`, a description, typed parameters, and response schemas so agents can register the endpoints as tools.

## Policies

Using the API is subject to the [Terms of Use](/terms) and [Acceptable Use Policy](/acceptable-use). Privacy details: [Privacy Policy](/privacy). Questions: [contact](/contact).