> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tess.im/llms.txt
> Use this file to discover all available pages before exploring further.

# What an OpenAPI spec is and how to get one

> A plain-language guide to the file Tess reads when you build a Custom API server.

This page is for people who are not building APIs. It explains the file Tess asks for on [Custom API](https://docs.tess.im/en/custom-api.md).

## 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`.

```yaml theme={null}
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:

```json theme={null}
{
  "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

1. Ask the team that owns the API, or the company that sells it. Say you need the **OpenAPI 3** spec, as JSON or YAML.
2. Open the service's developer docs and search for **OpenAPI**, **Swagger**, or **API spec**.
3. Try common addresses on that service, such as a link ending in `/openapi.json` or `/swagger.json`.
4. 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:

```yaml theme={null}
openapi: 3.0.3
```

or, in JSON, `"openapi": "3.0.3"`.

Swagger 2.0 starts like this:

```yaml theme={null}
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.

1. Open [editor.swagger.io](https://editor.swagger.io).
2. Open **File**, then **Import File**, and choose your Swagger 2.0 file. You can also paste the file into the editor.
3. 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.
4. 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.
5. After the text updates, check that the first line is `openapi:` and a version starting with `3`.
6. 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](https://docs.tess.im/en/mcp-custom.md).

## 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](https://docs.tess.im/en/custom-api.md). 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](https://docs.tess.im/en/custom-api.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.