# Posh — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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.

> Discover exclusive events and explore attendee lists, ticket information, and host profiles complete with social links through Posh.vip. Search for events and hosts by city to find the perfect social gathering and connect with event organizers.

**Category:** Entertainment | **Website:** [posh.vip/](https://posh.vip/) | **Docs:** [parse.bot/marketplace/4b56785b-2e57-4c0f-a5b6-1eee93767866/posh-vip-api](https://parse.bot/marketplace/4b56785b-2e57-4c0f-a5b6-1eee93767866/posh-vip-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-posh-vip-api-4b56785b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### explore_events

Browse and discover events by city, time period, and sort order. Returns paginated results including event name, venue, tickets, flyer, and organizer info. Use nextCursor from the response to paginate through results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | City name to browse events in. |
| `cursor` | string | No | Pagination cursor from a previous response's nextCursor field. Integer encoded as string. |
| `limit` | integer | No | Maximum number of events to return per page. |
| `sort` | string | No | Sort order for results. |
| `when` | string | No | Time filter for events. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-posh-vip-api-4b56785b/explore_events \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","cursor":"<string>","limit":"<integer>","sort":"<string>","when":"<string>"}'
```

### get_event_attendees

Get the guestlist of attendees for a specific event. Returns attendee names, avatars, account info, and a nextCursor for pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_id` | string | Yes | Internal event ID (MongoDB ObjectID). Obtainable from the _id field in explore_events/search_events results or eventId from get_event_details. |
| `limit` | integer | No | Maximum number of attendees to return. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-posh-vip-api-4b56785b/get_event_attendees \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"<string>","limit":"<integer>"}'
```

### get_event_details

Get details for a specific event by its URL slug. Extracts event data from the event page including ID, name, venue, dates, organizer, location coordinates, and flyer URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Event URL slug (e.g. 'space-yacht-pool-party-5'). Obtainable from the url field in explore_events or search_events results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-posh-vip-api-4b56785b/get_event_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### get_event_tickets

Get ticket availability and pricing for an event. Returns ticket groups with individual ticket types (name, price, quantity available, description) and total tickets sold.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_id` | string | Yes | Internal event ID (MongoDB ObjectID). Obtainable from the _id field in explore_events/search_events results or eventId from get_event_details. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-posh-vip-api-4b56785b/get_event_tickets \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"<string>"}'
```

### get_host_profile

Get full details of a host/group profile by their username slug. Returns host metadata (name, currency, contact email, social links, number of attendees) and their full event history.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | Host/group username slug. Obtainable from the groupUrl field in event results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-posh-vip-api-4b56785b/get_host_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"<string>"}'
```

### search_events

Search for events by keyword/query in a specific city. Returns paginated results matching the search term, with the same event data structure as explore_events.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | City name to search events in. |
| `cursor` | string | No | Pagination cursor from a previous response's nextCursor field. Integer encoded as string. |
| `limit` | integer | No | Maximum number of events to return per page. |
| `query` | string | Yes | Search keyword to find matching events. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-posh-vip-api-4b56785b/search_events \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","cursor":"<string>","limit":"<integer>","query":"<string>"}'
```

### search_hosts_by_city

Discover host profiles in a specific city by browsing current events and fetching each unique host's profile. Returns contact info, social links, and event lists for discovered organizers. Performs multiple requests internally (one per host).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | City name to discover hosts in. |
| `limit` | integer | No | Maximum number of host profiles to return. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-posh-vip-api-4b56785b/search_hosts_by_city \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","limit":"<integer>"}'
```