What an OpenAPI spec is and how to get one

This page is for people who are not building APIs. It explains the file Tess asks for on Custom API.

What the file is

An API is a way for one program to ask another program to do something, such as “read the status” or “create a record.” An OpenAPI spec is a standard manual for that API. It is one file, in JSON or YAML. The file lists:

the base address the calls start from
the actions, also called endpoints, such as “get the status”
the inputs each action expects
the outputs each action returns

Tess reads that file and turns each action into a tool the chat or an agent can call. It does this only for actions written under paths. Notes you type in the Custom API dialog do not add or remove actions. The file does.

A file Tess accepts

The smallest file has four pieces. Words in the file are fixed. You do not translate openapi, info, or paths.

openapi: 3.0.3
info:
  title: Status
  version: 1.0.0
paths:
  /status:
    get:
      operationId: getStatus
      summary: Read the service status
      responses:
        "200":
          description: OK

openapi: 3.0.3 says this is OpenAPI version 3. Tess accepts 3, or a version that starts with 3.
info is the name of the API. Tess requires this block.
paths lists the actions. Tess requires at least one.
get is the action. Tess also accepts put, post, delete, patch, head, options, and trace.

The same file as JSON, which you can paste into Custom API:

{
  "openapi": "3.0.3",
  "info": { "title": "Status", "version": "1.0.0" },
  "paths": {
    "/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Read the service status",
        "responses": { "200": { "description": "OK" } }
      }
    }
  }
}

In Custom API you still fill Base URL yourself, for example https://api.example.com. The file above only describes the /status action.

What Tess accepts

Rule	Detail
Version	OpenAPI 3 only
File type	`.json`, `.yaml`, or `.yml`, or the text pasted in the dialog
Size	Up to 2 MB
Content	An `info` block, a `paths` block, and at least one action

Swagger 2.0 is an older format. Tess refuses it with this message: This file uses an older format (Swagger 2.0). Please send the OpenAPI 3 version, or ask whoever provides the API to update it.

Where to get the file

Ask the team that owns the API, or the company that sells it. Say you need the OpenAPI 3 spec, as JSON or YAML.
Open the service’s developer docs and search for OpenAPI, Swagger, or API spec.
Try common addresses on that service, such as a link ending in /openapi.json or /swagger.json.
Many API tools can export this file. The export button’s name depends on the tool. Ask the provider which export is OpenAPI 3.

How to see the version

Open the file in any text editor and read the first lines. OpenAPI 3 starts like this:

openapi: 3.0.3

or, in JSON, "openapi": "3.0.3". Swagger 2.0 starts like this:

swagger: "2.0"

If you see swagger: "2.0", Tess will not take the file until it is converted.

Convert Swagger 2.0 to OpenAPI 3

Tess does not convert the file for you. Swagger Editor does. These labels are from the current Swagger Editor source.

Open editor.swagger.io.
Open File, then Import File, and choose your Swagger 2.0 file. You can also paste the file into the editor.
Open Edit, then Convert to OpenAPI 3.0.x. This item appears only when the editor is holding a Swagger 2.0 file. It is hidden for a file that is already OpenAPI 3.
A dialog titled Convert to OpenAPI 3.0.x opens. It says the conversion uses the Swagger Converter API, that the editor contents are sent to that converter, and that the editor text is replaced by the result.
After the text updates, check that the first line is openapi: and a version starting with 3.
Open File, then Save (as JSON) or Save (as YAML), and use that download in Custom API.

The editor sends your file to the public converter at https://converter.swagger.io/api/convert. Do not use this path for a spec you cannot share outside your company. Ask your provider for an OpenAPI 3 file instead.

If there is no spec

Ask the provider for an OpenAPI 3 file. Tess cannot invent the action list. If that service already offers an MCP server, you do not need this file. Add the server with Custom MCP.

When the file is refused

What happened	What to try
The message says the file is Swagger 2.0	Convert it with the steps above, or ask for OpenAPI 3.
The message says the file does not look like OpenAPI	Check `openapi`, `info`, and `paths`, and that at least one action exists.
The message says the YAML shortcut is not supported	Ask for the JSON file, often named `openapi.json` or `swagger.json`.
The message says the file is over 2 MB	Ask for a smaller file that lists only the actions you will use.
The message says the API address is not valid	Fix Base URL on Custom API. It must be an `http` or `https` address Tess is allowed to call.
The browser says the file type is wrong	Use `.json`, `.yaml`, or `.yml`.

Back to the form: Custom API.

Connectors

MCP & API