# API reference

When a web service of an [application](/user-guide/engineering/applications) has an OpenAPI (or
Swagger) file in its repository, Productmind shows it as a browsable API reference: its endpoints
grouped by tag, with their parameters, request and response schemas, examples and code samples.
**Try it** sends real requests to a live preview of the application or to one of its deployed
environments, and shows the answers.

<Availability permission="Applications: Read to read an API reference. Sessions: Read as well to send requests to a live preview. Applications: Update to set a service's API description file and to send requests to a deployed environment." />

## Working with an API reference

### To browse a service's API reference

1. Open the application and choose **API reference**, under **Run** in its list of sections. You
   can also choose **View API reference** on a web service's line in **Services**.
2. The reference opens on the first service that has an API description. The list of
   applications folds away to give it room; choose the list button at the top left to bring it
   back.
3. To switch to another service, or to an API description no service uses, choose the service's
   name at the top of the reference and pick another.

The bar at the top says which file the reference is read from, on which branch, and whether it was
found automatically or set on the service. Choose the file's name to open it at your git
provider. It also shows the OpenAPI version, the number of operations, and where **Try it** can
send. Use **Search**, above the list of endpoints, to find one.

The file is read from the application's **Base** branch. Productmind finds it automatically: a
file named `openapi.json`, `openapi.yaml`, `swagger.json` or `swagger.yaml` (or `.yml`), or ending
in `.openapi.json` or `.openapi.yaml`, outside dependency, build and test folders. With one web
service, it takes the file nearest the repository's root. With several, each takes the file in a
folder named like the service.

### To set a service's API description file

If the file has another name, is somewhere else, or belongs to another service:

1. Open the application's **API reference** and pick the service.
2. Choose **Change file**, or **Set the file's path** when none was found. In **Services**, the
   service's line has the same choice: **Change**, or **Set path**.
3. Search the repository's files and pick the file, or type its path and press **Enter**.

To go back to finding the file automatically, choose **Change file**, then **Find it
automatically**.

### To try a request

**Try it** in the API reference sends a real request and shows the answer. It sends only to:

- a **live preview** of a session that runs this application, while the preview is running. Its
  API must answer under the preview's address, as a live preview serves it.
- one of the application's **deployed environments**. Its address is the environment's live
  address; you can change the host to any host under the environment's domain, such as
  `api.example.com`.

The bar at the top of the reference says where requests go: **Try it** with the first live
preview or environment it can reach (point at it to see them all), or **Try it off**, with what to
do to turn it on.

1. Open the API reference and choose an endpoint.
2. Choose **Test Request**.
3. Pick the live preview or the environment in the server list, fill in the parameters and the
   body, and choose **Send**.

Each endpoint shows a code sample for the selected server; choose another language above it, such
as Python or JavaScript.

Productmind sends the request for you: your browser never calls the address itself. The servers
listed in the file are shown, but a request to one of them is not sent, and the answer says where
**Try it** can send. When there is no running preview and no deployed environment, **Test
Request** is hidden.

On a **Production** environment, any request other than GET, HEAD or OPTIONS asks **Send this
request to Production?** first. Every request sent to an environment is recorded in the
[audit log](/user-guide/settings/identity-and-access/audit-log): its method, path, status and
environment, never its headers or body.

## Permissions

| To | You need |
| --- | --- |
| Read a service's API reference | **Applications: Read** |
| Set or clear a service's API description file | **Applications: Update** |
| Send **Try it** requests to a live preview | **Applications: Read** and **Sessions: Read** |
| Send **Try it** requests to a deployed environment | **Applications: Update** |

See [Roles and permissions](/user-guide/reference/roles-and-permissions).

## Limits

| Limit | Value |
| --- | --- |
| API description file | 4 MB, in one file: references to other files are not followed |
| **Try it** request body | 1 MB |
| **Try it** answer | Up to 4 MB; a longer answer is cut, and says so |
| **Try it** time | 30 seconds |
| **Try it** requests | 60 a minute |

## Troubleshooting

### A live preview answers 404

**Try it** reaches a preview at the preview's own address, under the session and the port. An API
that only answers at the root of its server answers 404 there: make it answer under the address
the live preview gives it.

### The reference shows an older version of the API

The file is read from the application's **Base** branch, so a change a session made to it shows
once it is merged there.
