SDKs and tools

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.

Open in Claude Open in ChatGPT .md

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 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://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:

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, 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://usebluebot.com/openapi.v1.json -o bluebot-api.d.ts

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:

Terminal

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