Skip to the page

SDKs and tools

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 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.

Terminal
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 gotIt meansDo next
200 with your account and keyThe 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 emptyThe collection stopped the request because it had no key.Choose the “DogBot” environment and check the key is in Current value.
401 unauthorizedThe 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_scopeThe 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, 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:

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

Terminal
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 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 explains what counts as a breaking change and how webhook payloads are pinned.