# Call a gateway over REST and OpenAPI

Every operation a gateway serves over MCP is also an HTTP endpoint. A REST call uses the same API key, goes through the same rules and appears in the same logs as an MCP call. Use it from code, scripts and tools that do not speak MCP.

## Before you begin

- A gateway that serves at least one API. See [Create a gateway](https://docs.faustine.ai/agent-gateway/create-a-gateway/).
- An API key for the environment you call. See [Create an API key](https://docs.faustine.ai/agent-gateway/api-keys/).

## Call an operation

The URL of an operation is the REST base of the environment, the namespace of the API and the key of the operation. The gateway's **Connect** tab shows the **REST base**, and **REST / OpenAPI** under **Entry points** has a `curl` command for a sample operation.

Send the operation's input as a JSON body. Replace `<GATEWAY_KEY>` with the key you saved when you created it.

```bash
curl -X POST "https://gateway.faustine.ai/<workspace>/<gateway>/api/<namespace>/<operation>" \
  -H "Authorization: Bearer <GATEWAY_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

A successful call returns `200` with the status and the body your API returned:

```json
{ "status": 200, "body": { } }
```

A read-only operation also accepts `GET`, with the input in the query string. Values are read as JSON where they parse as a boolean, a number, `null`, an object or an array, unless the operation's schema declares the field as a string.

```bash
curl "https://gateway.faustine.ai/<workspace>/<gateway>/api/<namespace>/<operation>?limit=2" \
  -H "Authorization: Bearer <GATEWAY_KEY>"
```

For another environment, add its slug after the gateway: `https://gateway.faustine.ai/<workspace>/<gateway>/staging/api/…`.

## Choose a connection

When an API has more than one connection in the environment, name the one to use in the `X-Faustine-Connection` header, or in a `$connection` field of the input.

## Read errors

An error has this body. `requestId` is the ID of the request in the gateway's **Logs** tab.

```json
{ "error": { "code": "scope", "message": "…", "requestId": "req_…" } }
```

| Status | Meaning |
| --- | --- |
| `401` | The key is missing, wrong, or belongs to another environment. |
| `403` | The gateway denied the call: the key's scope, a read-only key, an operation that requires confirmation, or an IP address rule. The body has a `denyReason`. |
| `404` | The environment does not expose an operation with that key. |
| `405` | `GET` on an operation that is not read-only. Use `POST`. |
| `409` | A repeated write was held back. See [Repeated writes](https://docs.faustine.ai/agent-gateway/repeated-writes/). |
| `429` | A rate limit, quota or concurrency limit was reached. The `Retry-After` header says how many seconds to wait. |
| `502` | Your API answered with an error. The body also has the `status` and `body` it returned. |
| `503` | The gateway is paused. |

Every response has an `X-Faustine-Manifest-Version` header with the version of the set of operations the environment serves. For the full contract, see [Gateway HTTP](https://docs.faustine.ai/reference/gateway-http/).

## Import the OpenAPI document

Each environment serves an OpenAPI 3.1 document of its operations. Any client that reads OpenAPI can import it, such as Postman, Insomnia or a code generator. Authentication is an HTTP bearer with the API key.

```text
https://gateway.faustine.ai/<workspace>/<gateway>/openapi.json
```

The document is public while **Public docs** is on in the gateway's **Docs** tab. While it is off, send the key to fetch it, and the document lists only the operations that key can call:

```bash
curl -H "Authorization: Bearer <GATEWAY_KEY>" https://gateway.faustine.ai/<workspace>/<gateway>/openapi.json
```

## What you see after the first call

In the portal, the request appears in the gateway's **Logs** tab with the channel **REST**, and the **REST / OpenAPI** card in the **Connect** tab shows when the client was last seen.

## Next steps

- [Gateway HTTP](https://docs.faustine.ai/reference/gateway-http/): every endpoint, header and error code.
- [Limits and quotas](https://docs.faustine.ai/agent-gateway/limits/): the limits behind a `429`.
- [Faustine CLI](https://docs.faustine.ai/apps/cli/): call the same operations from a shell.