# REST API

Call LookAlike analyses over HTTP with an API token, read the OpenAPI document, and handle errors and limits.

The REST API runs the same tools as the [MCP server](https://docs.lookalikeiq.com/agents/mcp/). The OpenAPI 3.1 document is at `https://app.lookalikeiq.com/api/v1/openapi.json`. It needs no token. Each response in it carries a schema with a description of every field.

Send the token in the `Authorization` header:

```
curl -H "Authorization: Bearer lk_your_token" \  "https://app.lookalikeiq.com/api/v1/brands/trader_joes/candidates?state=CO&limit=5"
```

## Endpoints

Method and path

Tool

`GET /api/v1/me`

Account, active release, usage, and endpoint addresses.

`GET /api/v1/glossary`

The meaning of every result field.

`GET /api/v1/brands`

`list_brands`

`GET /api/v1/brands/{brand}`

`get_brand`

`GET /api/v1/brands/{brand}/candidates`

`find_candidates` with query parameters

`GET /api/v1/brands/{brand}/markets`

`rank_markets` with query parameters

`GET /api/v1/brands/{brand}/preview.png`

`map_preview` as a PNG image

`POST /api/v1/candidates`

`find_candidates`

`POST /api/v1/markets`

`rank_markets`

`POST /api/v1/sites/evaluate`

`evaluate_site`

`POST /api/v1/tracts`

`describe_tracts` with `geoids`

`GET` or `POST /api/v1/tracts/{geoid}`

`describe_tracts` for one tract

`POST /api/v1/compare`

`compare_brands`

`POST /api/v1/preview`

`map_preview` as JSON with a base64 image

`POST /api/v1/preview.png`

`map_preview` as a PNG image

`GET /api/v1/metros?query=`

`search_metros`

`GET /api/v1/method`

`get_method`

`POST /api/v1/links`

`make_map_link`

`POST /api/v1/links/saved`

`save_view`

`GET /api/v1/views`

`list_views`

`GET /api/v1/views/{id}`

Read a saved view.

`PATCH /api/v1/views/{id}`

`rename_view` with `{ "title": "..." }`

`DELETE /api/v1/views/{id}`

`delete_view`

In query strings, write lists with commas, for example `exclude_states=TX,OK`. Write weight maps as `key:value` pairs, for example `theme_weights=education:2,retail_dining_context:0`. Send `near` and `site` in a POST body.

A PNG response carries the matching map link in the `x-map-link` header.

## Score your own stores

Send a `stores` list instead of `brand`. Each store needs `lat` and `lon`. Send 3 to 5,000 stores.

```
curl -X POST https://app.lookalikeiq.com/api/v1/candidates \  -H "Authorization: Bearer lk_your_token" -H "content-type: application/json" \  -d '{"stores":[{"lat":39.74,"lon":-104.99},{"lat":39.68,"lon":-104.94},{"lat":40.01,"lon":-105.27}],"stores_name":"Pilot","limit":5}'
```

LookAlike saves the store points once in a private view and reuses it for the same list. The `map_link` values open that view. Colleagues in your organization can open the links.

## Errors and limits

Errors use one shape:

```
{ "error": { "code": "INVALID_INPUT", "message": "input.limit must be at most 100", "issues": ["input.limit must be at most 100"], "requestId": "..." } }
```

Status

Meaning

400

The input is invalid. `issues` lists each problem and the valid choices.

401

The token is missing, wrong, expired, or revoked.

403

The account lost access, or the token called a route outside the agent API.

404

The saved view does not exist, or you did not create it.

429

The account made more than 1,200 agent requests in one hour. `Retry-After` gives the seconds to wait.

502

The address geocoder is unavailable.

503

The national data release is unavailable.

Every response to a token request carries `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (seconds until the hourly window resets).

Canonical URL: https://docs.lookalikeiq.com/agents/rest-api/
