# Postmates — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Browse and search Postmates restaurants to discover menus, items, and detailed restaurant information all in one place. Get category suggestions, view complete menus, and access specific item details to find exactly what you're looking for.

**Category:** Food & Dining | **Website:** [postmates.com/](https://postmates.com/) | **Docs:** [parse.bot/marketplace/4c9aa124-c853-4f64-a687-504e758cb176/postmates-com-api](https://parse.bot/marketplace/4c9aa124-c853-4f64-a687-504e758cb176/postmates-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/postmates/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get categories

Returns the top food categories available for browsing, organized by vertical (ALL, RESTAURANTS, SHOP, ALCOHOL). Does not require location context. Categories include their icon URLs and can be used as search terms.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/postmates/get-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get menu item details

Returns details for a specific menu item, including price, description, and customization options. Requires the store UUID, section UUID (top-level key from catalogSectionsMap in get_restaurant_menu), and the item UUID (from catalogItems). The subsection UUID is optional but provides better context.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_uuid` | string | Yes | UUID of the menu item (from catalogSectionsMap catalogItems in get_restaurant_menu) |
| `section_uuid` | string | Yes | UUID of the menu section (top-level key from catalogSectionsMap in get_restaurant_menu) |
| `store_uuid` | string | Yes | UUID of the restaurant/store |
| `subsection_uuid` | string | No | UUID of the menu subsection (catalogSectionUUID from get_restaurant_menu). Omitting returns the item without subsection context. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/postmates/get-menu-item-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"item_uuid":"<string>","section_uuid":"<string>","store_uuid":"<string>","subsection_uuid":"<string>"}'
```

### Get restaurant details

Returns full details for a specific restaurant/store by its UUID, including location, hours, rating, categories, menu sections, and catalog items. The store_uuid can be obtained from search_restaurants or get_restaurant_feed results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `store_uuid` | string | Yes | UUID of the restaurant/store (obtainable from search_restaurants feedItems[*].store.storeUuid or get_restaurant_feed feedItems[*].carousel.stores[*].storeUuid) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/postmates/get-restaurant-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"store_uuid":"<string>"}'
```

### Get restaurant feed

Returns a location-based feed of restaurants and stores available for delivery. Requires a delivery address to determine nearby options. Returns dining modes, sort/filter options, and a list of feed items including store carousels and regular store listings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | No | Delivery address to search near (e.g. '1600 Pennsylvania Ave NW, Washington, DC'). Defaults to Washington DC if not provided. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/postmates/get-restaurant-feed \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"address":"<string>"}'
```

### Get restaurant menu

Returns the complete menu for a restaurant including catalog sections and items. Uses the same underlying API as get_restaurant_details, returning full store data with menu structure in catalogSectionsMap. The store_uuid can be obtained from search_restaurants or get_restaurant_feed results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `store_uuid` | string | Yes | UUID of the restaurant/store (obtainable from search_restaurants feedItems[*].store.storeUuid) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/postmates/get-restaurant-menu \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"store_uuid":"<string>"}'
```

### Get search suggestions

Returns autocomplete suggestions as the user types a search query. Includes both store suggestions (with UUIDs) and text/keyword suggestions. Does not require location context.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query text for typeahead suggestions (e.g. 'piz', 'burger') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/postmates/get-search-suggestions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Search restaurants

Search for restaurants, grocery stores, and alcohol shops by keyword. Returns matching stores with ratings, delivery info, and images. Location context is established via the address parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | No | Delivery address for location context (e.g. '1600 Pennsylvania Ave NW, Washington, DC'). Defaults to Washington DC if not provided. |
| `query` | string | Yes | Search keyword (e.g. 'pizza', 'sushi', 'chipotle') |
| `vertical` | string | No | Filter by vertical: ALL, RESTAURANTS, SHOP, ALCOHOL. Filtering is advisory and may include cross-category results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/postmates/search-restaurants \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"address":"<string>","query":"<string>","vertical":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.