# OpenAPI, Postman and Insomnia

> The whole API as one OpenAPI 3.1 file. Import it into Postman or Insomnia and send requests with your key in a few minutes, or generate types and a client for a language the SDKs don’t cover.

Every endpoint, parameter, body, answer and error code in the BlueBot API is described in one OpenAPI 3.1 file:

```text
https://usebluebot.com/openapi.v1.json
```

The file is generated from the same code that checks each request, and BlueBot’s own tests compare the API’s answers against it, so it can’t drift from what the API does. The [API reference](https://usebluebot.com/docs/api) is built from it too. Besides the standard fields, each operation carries `x-scope`, the API key scope it needs, and `x-error-codes`, the error codes it can answer.

```bash
curl -O https://usebluebot.com/openapi.v1.json
```

## Postman

### Import the file

In Postman, press **Import**, paste `https://usebluebot.com/openapi.v1.json` and choose to import it as a **Postman Collection**. You get a “BlueBot API” collection with a folder for each part of the API (Messages, Files, Webhooks and so on) and every request inside, filled with example values. The import also makes a collection variable, `baseUrl`, set to `https://usebluebot.com/api/v1`.

### Keep your key in an environment

Press **Environments**, make one named “BlueBot”, and add a variable `bluebotApiKey` of type **secret** with your key as its value. Choose the environment in the top-right corner. Keeping the key out of the collection means you can share or export the collection without giving the key away.

### Set the collection’s auth

Open the collection, go to **Authorization**, choose **Bearer Token** and set the token to `{{bluebotApiKey}}`. Every request inherits it.

### Add idempotency keys to POSTs

Open the collection’s **Scripts** tab, choose **Pre-request** and paste:

```js title="Collection pre-request script"
// A fresh Idempotency-Key for each POST, unless the request sets its own.
if (pm.request.method === 'POST' && !pm.request.headers.has('Idempotency-Key')) {
  pm.request.headers.add({ key: 'Idempotency-Key', value: pm.variables.replaceIn('{{$guid}}') });
}
```

Each press of **Send** then gets its own key, so pressing it twice sends twice, as you’d expect while exploring. To see idempotency at work, set the header on a request yourself and send it twice.

### Send a request

Open **Account → Who am I?** (`GET /me`) and press **Send**.

| You got                         | It means                                    | Do next                                                                                 |
| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------- |
| `200` with your account and key | The key and the auth are set up.            | Try **Messages → Send a text** with your own number in `to`.                            |
| `401` `unauthorized`            | No key went, or the wrong one.              | Check the environment is chosen and the request’s auth is **Inherit auth from parent**. |
| `403` `insufficient_scope`      | The key lacks the scope this request needs. | Make a key with the scope the error names.                                              |

When the API gains an endpoint, import the file again to pick it up; Postman can replace the old collection or keep both.

## Insomnia

### Import the file

In Insomnia, choose **Import**, pick **URL**, paste `https://usebluebot.com/openapi.v1.json`, press **Scan** and then **Import**. You get a collection with every request, and a base environment with `base_url` set to the first server, `https://usebluebot.com/api/v1`.

### Add your key

Open **Manage Environments**, add a private sub-environment named “BlueBot” and give it `bluebot_api_key` with your key as its value. A private environment isn’t exported or synced, so the key stays on your machine. Choose it as the active environment.

### Set auth and idempotency keys

In the collection’s (or each folder’s) settings, set **Auth** to **Bearer Token** with the token `{{ _.bluebot_api_key }}`, and have requests inherit it. On a POST you want to send, add the header `Idempotency-Key` with Insomnia’s UUID tag, `{% uuid 'v4' %}`, as its value.

### Send a request

Run **Who am I?** (`GET /me`) and expect a `200` with your account, as in Postman above.

Bruno, Hoppscotch, Paw (RapidAPI for Mac) and most other API tools import OpenAPI the same way: give them the URL, then set a bearer token from a variable.

## Generate types or a client

For TypeScript and Python, use the [SDKs](https://usebluebot.com/docs/sdks), which add retries, pagination and webhook verification on top of what a generator gives you. For anything else, the file is a starting point.

Types for TypeScript, used with a small typed `fetch` such as `openapi-fetch`:

```bash
npx openapi-typescript https://usebluebot.com/openapi.v1.json -o bluebot-api.d.ts
```

```ts title="Typed calls with openapi-fetch"
import createClient from 'openapi-fetch';
import type { paths } from './bluebot-api';

const bluebot = createClient<paths>({
  baseUrl: 'https://usebluebot.com/api/v1',
  headers: { Authorization: `Bearer ${process.env.BLUEBOT_API_KEY}` },
});

const { data, error } = await bluebot.POST('/messages', {
  headers: { 'Idempotency-Key': crypto.randomUUID() },
  body: { to: '+15555550123', text: 'Your order is ready for pickup.' },
});
console.log(data?.state ?? error?.error.code);
```

A client for Go, Java, C#, Ruby, PHP, Kotlin, Swift and others, with OpenAPI Generator:

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://usebluebot.com/openapi.v1.json \
  -g go \
  -o ./bluebot-go
```

Swap `-g go` for `java`, `csharp`, `ruby`, `php`, `kotlin` or `swift5`. Generators read OpenAPI 3.1 with differing success, especially fields that may be `null`, so read what you get before relying on it, and add what no generator does: an `Idempotency-Key` on every POST, a retry after `Retry-After` on 429 and 5xx, and a loop over `next_cursor` for lists. [SDKs](https://usebluebot.com/docs/sdks#without-an-sdk-go-ruby-and-php) shows each.

## Keep up with changes

The file describes `/v1`, which only grows: BlueBot adds endpoints, fields and enum values to it and never removes or renames one. Code written against today’s file keeps working; to use what’s new, fetch the file again. `info.version` is the API’s current version, the same date webhook payloads carry as `api_version`. [Versioning](https://usebluebot.com/docs/concepts/versioning) explains what counts as a breaking change and how webhook payloads are pinned.