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 import a Swagger / Open API reference into Gelato programmatically. This is useful if you want to update your API documentation each time your CI build passes, or in a Git post-commit hook.

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

Import Flow

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

You'll then make a POST request to the /v1/imports/ endpoint with a number of query parameters. Include the import_type you're looking for (swagger), and a file_location which points to your publicly available file. You'll also need to include your apikey and the api_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). The ids can be accessed by either clicking the Edit button for an API or for an API Version (see screenshots below).

Edit Api

Edit Version

Once you have your API id (required) and API version id (optional), you can construct a curl request similar to this:

curl -X POST

NOTE: If you do not include the optional api_version_id query parameter in your request, you will need to specify the basePath attribute in your Open API / Swagger reference before import, which you can read more about here.

If everything goes correctly, you'll receive a response that includes a URL pointing to your brand new import. You can use this to check the status of the import in progress as follows:


Remember to add your API key to the query parameters!


If you have any issues, please get in touch at 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"