With OpenAI’s new Actions feature allowing you to get a GPT that uses your own API, many new doors are open. However giving an AI an access token the keys to your API and telling it to have fun may lead you to realise that one of the doors available leads to the empty lift shaft of overwritten data, or the bottomless well of cloud bill shock. To reduce the risks, OpenAI supports an extension x-openai-isConsequential that you can add to your OpenAPI description, to indicate which endpoints should not be called without a human confirmation step.

I’m not doing much with OpenAI right now, but I do plenty with OpenAPI and the question “how do I add this field to my existing API description?” is one that I can answer! What’s more, you can use the advice in this post to add other extensions or additions to your OpenAPI descriptions using Overlays, this advice isn’t OpenAI-specific, but it’s used in the examples.

(is anyone else confused by the OpenAI vs OpenAPI similarity yet? I am ….)

OpenAPI Overlays

The OpenAPI Initiative has a group working on a feature called Overlays which solves exactly this problem, where the OpenAPI description exists, but needs some tweaks. Sadly, not very many tools support this yet – the ones I know of are my overlays-js library that I’ll use for the examples in this post, and Speakeasy CLI.

Overlay Example

This example shows an Overlay that adds the x-openai-isConsequential field to all POST endpoints:

overlay: 1.0.0
info:
title: Add OpenAPI annotations
version: 1.0.0
actions:
- target: "$.paths.*.post"
update:
x-openai-isConsequential: true

The target field accepts JSONPath, so edit this expression as required to capture the endpoints you want to flag. Note also that you can add as many action steps as you need to, so if it’s simpler to add specific targets rather than trying to JSONPath to the right subset, that is an option! (there’s a bug with the overlays library that means structured overlays don’t work well at this moment, so use targeted overlays).

Use overlayjs to update the API description

Check the installation instructions to get the tool installed if you don’t have it already.

Run the command and supply the API description as --openapi and the overlay as --overlay. For example, the following command applies overlay.js to openapi.js:

overlayjs --openapi openapi.yaml --overlay overlay.js > new-openapi.yaml

The command writes to stdout, so you can direct the output wherever you would like it to go. In my case, I’ve directed it to a file called new-openapi.yaml.

Take a look at the updated OpenAPI description, or diff it against the original, and you should see that the post endpoints now have the OpenAI x-openai-isConsequential: true added.

By using OpenAPI Overlays, you get a standard format and a choice of tools to apply it with. You can prepare an OpenAPI file for use with OpenAI, even if you are an API consumer and have no input into the way that the OpenAPI is created – or if you just want to avoid cluttering other stages of your API lifecycle with the metadata specific to the OpenAI use case. Hopefully this helped you get your OpenAPI in shape for OpenAI (yes, still confusing to have such similar words!), I’d be happy to hear how you get on if you want to share in the comments.