Gateway HTTP

Gateway HTTP is the HTTP surface of an Agent Gateway environment: the MCP endpoint, the REST mirror, the documents it publishes and the sign-in endpoints. Use this page when you call a gateway from your own code or need to read an error.

URLs

Every URL of an environment starts with the same base. <workspace> is your workspace's slug and <gateway> is the gateway's slug.

https://gateway.faustine.ai/<workspace>/<gateway>                  the default environment
https://gateway.faustine.ai/<workspace>/<gateway>/<environment>    any other environment

With a custom domain, your domain replaces gateway.faustine.ai/<workspace>: https://<your-domain>/<gateway>[/<environment>]. Both addresses keep working.

/openapi.json, /docs and /skill.md are public by default. When an environment's docs are not public, they require a credential and show only the operations that credential can call. See Customize the gateway docs page.

In the REST path, <namespace> is the API's namespace and <operation> is the rest of the operation key. The operation crm.contacts.create is served at /api/crm/contacts.create.

Authentication

Every request to /mcp and /api carries a bearer token.

Authorization: Bearer fik_…

A credential works on the environment it belongs to. On any other environment or gateway, the response is the same as for an unknown credential.

Sign-in with OAuth

The gateway is its own OAuth 2.0 authorization server, one per environment. A request without a valid token gets 401 with a challenge that names the metadata document:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://gateway.faustine.ai/<workspace>/<gateway>/.well-known/oauth-protected-resource"

A session is valid only on the host it was obtained through. A token issued on gateway.faustine.ai does not work on a custom domain, and the reverse.

Failed authentication

A 401 body is JSON with a message field.

After 30 failed authentications from one IP address in a minute, every request from that address gets 429 with the code auth_throttled and a Retry-After header, until the minute ends.

Request headers

Response headers

REST requests

A REST call runs one operation. The request body is the operation's input.

With GET, a query value is read as a boolean, a number, null or JSON when it looks like one, unless the operation's schema declares the field as a string. A repeated key becomes an array.

<GATEWAY_KEY> is an API key of the environment.

curl -X POST https://gateway.faustine.ai/<workspace>/<gateway>/api/crm/contacts.create \
  -H "Authorization: Bearer <GATEWAY_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Ada", "last_name": "Lovelace", "email": "[email protected]"}'

REST responses

A successful call returns 200 with the status and the body your API answered.

{
  "status": 201,
  "body": { "id": 42, "first_name": "Ada", "last_name": "Lovelace", "email": "[email protected]" }
}

Under fan-out routing, body is { "byConnection": [ … ] } with one entry per connection.

Errors

A failed call returns an error envelope.

{
  "error": {
    "code": "scope",
    "message": "Denied (scope): This key is not scoped for \"crm.contacts.delete\"",
    "requestId": "req_01JCD9T3W8Q2M4X6Z0V5B7N1KP"
  },
  "denyReason": "scope"
}

Over MCP, a failed operation is a tool result marked as an error, with the same message as its text. A request refused before any tool runs (a paused gateway, a channel or an IP restriction) is an HTTP error with the envelope.

Refused by the credential or the environment

Wrong request

Limits

Every 429 carries Retry-After in seconds. See Limits and quotas for the defaults.

Repeated writes

These codes exist when the environment deduplicates repeated writes. A repeat of a finished write is not an error: it returns 200 with the stored response of the first call.

See Repeated writes.

Your API and recipes

Next steps

• Call a gateway over REST and OpenAPI: generate a client from the OpenAPI document.
• Connect clients: connect an MCP client instead of calling HTTP yourself.
• Logs: find a request by its ID.