Import API

This version is in Beta, there may be issues we're still working out.

Getting Started


The Gelato Import API is currently in Beta. Please let us know your feedback!

You can use this API to create new Swagger / Open API programmatically. This is useful if you say, want to update your API documentation each time your CI build passes, or in a Git post-commit hook.

There is only a single resource in the API at the moment, Imports.

Import Flow :ocean:

First, be sure that you have a Swagger definition available publicly on the internet somewhere (this could be an S3 link or similar).

Then, make a POST request to the /v1/imports/ endpoint. Include the import_type you're looking for (swagger), and a file_location parameter which points to your publicly available file. You'll also need to include the ID of the Gelato API you'd like to import to (you can find this on the "APIs & Docs" tab in your Gelato Admin panel)

POST /v1/imports?apikey=SOMEKEY&file_location=

If everything goes correctly, you'll receive a response including a URL pointing to your brand new import :sparkles:. You can use this to check out the status of the import in progress (we process the imports in the background for you)


If you have any issues, please get in touch on Thanks!


Making Authenticated Requests

The Gelato API uses API key authentication. All you need to do is include a query parameter named apikey in your requests.

Getting your API Key

Getting an API key is easy! All you need is a Mashape ID account (make sure you're subscribed to the Gelato Growth or Enterprise plan)

  1. Head to and click "Sign Up"
  2. Click the "Mashape ID" button, and log in with your Mashape ID.
  3. Click the "Dashboard" link, then the "Get API Key" button.

Success! Your Gelato API Key is now available on your dashboard at


We use the JSON API errors format for Gelato API errors. Error response bodies will look something like the following:

 "errors": [
    "status": 400,
    "source": { "parameter": "file_location" },
    "title":  "file_location is required",
    "detail": "You must specify a `file_location` parameter with the location of the file to import"