Insomnia: import the Sume OpenAPI from a URL and set up auth

The answer

Kong's Insomnia import reference says the UI import offers File, Clipboard or URL, and that supported formats include OpenAPI 3.0 and 3.1. Sume publishes its OpenAPI 3.0.3 document at https://api.sume.com/reference/json, so choose Import, then URL, paste that address, and Insomnia builds a collection from it.

The spec describes the operations but contains no credential. Add your key as an environment variable and reference it in the Authorization header.

Steps

Open a workspace or API collection header, select Import, and pick the URL method. Confirm the preview, then import. You get a request per operation, grouped by the spec's tags, with the Jobs tag holding the status, result, cancel and events calls.

Create an environment with one variable for your key. Set the header on the collection or folder rather than per request, so you change it in one place. Sume accepts a Bearer token or an x-api-key header; send only one of them, because sending both returns 401 with the message to send only one API key credential.

A first request that is safe

Start with a read: list jobs or read the status of a job id you already have. Reads cost nothing and prove that the key and header are right. Only then try a create. For a create, add an Idempotency-Key header so that pressing Send twice by accident does not create two paid jobs.

A create returns a job.id; paste it into the status request, and check terminal and result_ready. Calling /result earlier returns 409 job_not_completed, which is expected rather than a bug.

Refreshing the collection

A URL import is a snapshot. When Sume adds endpoints, import again or compare against a stored copy. If you keep the spec in version control, use the File method on your committed copy so every teammate imports the same version.

Using the collection day to day

Duplicate the status request into a folder of your own for the jobs you are watching, and keep the job id in an environment variable so one edit updates the status, result, events and cancel requests together. Reading events_url is the quickest way to see why a job failed or was canceled, since the response gives next_action: inspect_events for those states.

Cancel is the one request to handle with care: it only works while cancelable is true, which is before generation has started. Once generation begins the field is false and cancel_url is null, so the request has nothing to act on.