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.
An API key for the environment you call. See Create an API key.

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.

terminal

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:

{ "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.

terminal

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.

{ "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.
`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.

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.

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:

terminal

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: every endpoint, header and error code.
Limits and quotas: the limits behind a 429.
Faustine CLI: call the same operations from a shell.