# OpenAPI, Postman and Insomnia

> The whole API as one OpenAPI 3.1 file, and a ready-made Postman collection and Insomnia export built from it. 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 DogBot API is described in one OpenAPI 3.1 file:

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

The file is generated from the same code that checks each request, and DogBot’s own tests compare the API’s answers against it, so it can’t drift from what the API does. The [API reference](https://getdogbot.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://getdogbot.com/openapi.v1.json
```

## Postman

DogBot publishes a ready-made Postman collection, built from the same file, with your key, auth and idempotency keys already set up, and an environment to keep your key in. Import them from these addresses:

```text
https://getdogbot.com/postman/dogbot.postman_collection.json
https://getdogbot.com/postman/dogbot.postman_environment.json
```

### Import both

In Postman, press **Import**, paste the collection’s address, then do the same with the environment’s. You get a “DogBot API” collection with a folder for each part of the API (Messages, Files, Chats and so on) and every request inside, filled with example values and a saved example of what it answers, and an environment named “DogBot”.

### Add your key

In DogBot, open **Developers → API keys**, make a key and copy it. In Postman, open **Environments → DogBot** and paste the key into the **Current value** of `dogbotApiKey`. It’s a secret variable, so Postman hides it on screen, and a current value isn’t synced or exported, so you can share the collection without giving the key away. Then choose “DogBot” in the environment menu in the top-right corner.

### 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`.               |
| “There was an error in evaluating the pre-request script” with `dogbotApiKey is empty` | The collection stopped the request because it had no key.   | Choose the “DogBot” environment and check the key is in **Current value**. |
| `401` `unauthorized`                                                                   | The key went, but DogBot doesn’t know it or it was revoked. | Copy the key again, or make a new one if it was revoked.                   |
| `403` `insufficient_scope`                                                             | The key lacks the scope this request needs.                 | Make a key with the scope the error names.                                 |

What the collection does for you:

- **Auth.** Every request uses Bearer auth with `{{dogbotApiKey}}`, from the collection, except **Device → DogBot’s status** (`GET /status`), which needs no key.
- **Idempotency keys.** Each POST gets a fresh `Idempotency-Key`, unless the request sets its own. Pressing **Send** twice therefore sends twice, as you’d expect while exploring. To see idempotency at work, add an `Idempotency-Key` header to a request yourself and send it twice: the second answer is the first again, with `Idempotent-Replayed: true`.
- **Parameters.** Optional query parameters are listed on each request, turned off, with an example value; tick the ones you want. Path parameters (`:id`, `:person`) hold example ids, so replace them with real ones from an earlier answer.
- **Somewhere else.** `baseUrl` in the environment is `https://getdogbot.com/api/v1`. Change it to point the collection at another address.

When the API gains an endpoint, import the collection again, and Postman offers to replace the one you have. You can also import `https://getdogbot.com/openapi.v1.json` itself as a Postman collection, but then you set up the auth, the environment and the idempotency keys yourself.

## Insomnia

The same requests as an Insomnia export:

```text
https://getdogbot.com/insomnia/dogbot.insomnia.json
```

### Import it

In Insomnia, choose **Import**, pick **URL**, paste the address and import it. You get a “DogBot API” collection with a folder for each part of the API.

### Add your key

Open **Manage Environments**, choose the private sub-environment “DogBot” and set `dogbot_api_key` to your key. A private environment isn’t exported or synced, so the key stays on your machine. Make “DogBot” the active environment.

### Send a request

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

Each request uses Bearer auth with `{{ _.dogbot_api_key }}`, and each POST has an `Idempotency-Key` header whose value is Insomnia’s `{% uuid 'v4' %}` tag, so every send gets a new key.

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://getdogbot.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://getdogbot.com/openapi.v1.json -o dogbot-api.d.ts
```

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

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

const { data, error } = await dogbot.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://getdogbot.com/openapi.v1.json \
  -g go \
  -o ./dogbot-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://getdogbot.com/docs/sdks#without-an-sdk-go-ruby-and-php) shows each.

## Keep up with changes

The file describes `/v1`, which only grows: DogBot 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://getdogbot.com/docs/concepts/versioning) explains what counts as a breaking change and how webhook payloads are pinned.
