# Quickstart

> Get a key, generate a typed client from the spec and run your first search from your server.

From nothing to listings on a page in four steps. The examples use TypeScript, but any language that can send HTTPS requests works.

## 1. Get a key

Keys come from the marketplace's team. In the console, **API keys → New key**, they create:

- a **secret key** (`sk_test_…` or `sk_live_…`) for your server, and
- optionally a **publishable key** (`pk_…`) for native apps.

A key is shown once. Keep the secret key out of your code and out of browsers: put it in an environment variable such as `MONGRL_SECRET_KEY`.

| Environment | API | Keys |
|---|---|---|
| Test | `https://api.staging.mongrl.com` | `sk_test_…`, `pk_test_…` |
| Live | `https://api.mongrl.com` | `sk_live_…`, `pk_live_…` |

Check a key:

```sh
curl https://api.staging.mongrl.com/v1/marketplace \
  -H "Authorization: Bearer $MONGRL_SECRET_KEY"
```

The answer is your marketplace: its currencies, languages, what a listing needs and its shipping table.

## 2. Generate a typed client

The [OpenAPI spec](https://dev.mongrl.com/openapi.json) describes every endpoint and field. Generate a client from it instead of writing requests by hand: the compiler then catches wrong paths and fields.

```sh
npm install -D @hey-api/openapi-ts
curl -o openapi.json https://dev.mongrl.com/openapi.json
```

```ts
// openapi-ts.config.ts

export default defineConfig({
  input: './openapi.json',
  output: { path: 'src/api/generated' },
  plugins: ['@hey-api/client-fetch'],
})
```

```sh
npx openapi-ts
```

Each operation becomes a typed function named after its operation id: `listListings`, `getListing`, `placeOrder`… Commit the spec with your code and update it on purpose, so a new API version never changes your build by surprise.

## 3. Call it from your server

Make the client on the server, per request, with your secret key and (when someone is signed in) their session. Never import it into code that runs in the browser.

```ts
// src/server/mongrl.ts (server only)

export function mongrl(session?: string) {
  return createClient({
    baseUrl: process.env.MONGRL_API_URL, // https://api.staging.mongrl.com
    auth: () => process.env.MONGRL_SECRET_KEY, // sent as Authorization: Bearer sk_…
    headers: session ? { 'X-User-Session': session } : undefined,
  })
}
```

```ts

const { data, error } = await listListings({
  client: mongrl(),
  query: { q: 'lounge chair', currency: 'EUR', limit: 24 },
})
if (error) throw new Error(error.detail)

for (const l of data.items ?? []) {
  console.log(l.title, l.display_price?.amount, l.images?.[0]?.urls?.medium)
}
```

`display_price` is the price in the currency you asked for. Amounts are minor units: `125000` with `SEK` is 1 250,00 kr.

## 4. Sign a user in

Requests for a user (their orders, their listings, buying) also send the user's session token. Your server gets it when the user signs in and keeps it in an HttpOnly cookie:

```ts

const { data } = await signIn({ client: mongrl(), body: { email, password } })
// Store data.session.token in an HttpOnly, Secure, SameSite=Lax cookie.

const orders = await listMyOrders({ client: mongrl(tokenFromCookie) })
```

[Authentication](https://dev.mongrl.com/guides/authentication.md) explains keys and sessions in full.

## Next

- Building with Claude, Cursor or another agent? Start with [Build with an AI agent](https://dev.mongrl.com/start/agents.md).
- Otherwise, read the guide for the part you're building: [Browsing](https://dev.mongrl.com/guides/browsing.md), [Accounts](https://dev.mongrl.com/guides/accounts.md), [Checkout](https://dev.mongrl.com/guides/checkout.md) or [Selling](https://dev.mongrl.com/guides/selling.md).