Gateway API

Base URL and path

In production, the gateway base URL is https://api.tollara.ai; other deployments may use a different host. The path prefix is set at the controller level: default /api, or under ECS /gateway/api/v1. Invoke paths are relative to that prefix.

Sync invoke

GET | POST | PUT | DELETE /api/service/{serviceId}/endpoint/{endpointId}/invoke

Header: Authorization: Bearer <serviceKey>. Optional request body for POST/PUT. Response is the backend response.

Async invoke

GET | POST | PUT | DELETE /api/service/{serviceId}/endpoint/{endpointId}/invoke/async

Same auth. Response typically includes requestId, progressUrl, and callbackUrl. Callers use progressUrl to poll status; service backends send progress/completion to usage-service URLs (see Usage API).

Auth

All invoke requests require Authorization: Bearer <serviceKey>. The gateway validates the key and subscription before forwarding. If you expose OpenAPI/Swagger for the gateway, it will document the exact paths and schemas for your deployment.

Async status/result retrieval

Poll GET /api/requests/{requestId}/status (or your deployment's gateway prefix equivalent) for progress and terminal state, then call GET /api/requests/{requestId}/result.

For large async outputs, expect the result endpoint to provide resultUrl and a short inline result summary when available.

What the gateway sends to your backend

For proxied services, the gateway forwards the caller's HTTP method, body, and relevant headers to your backend URL, and adds X-Tollara-Signature, X-Tollara-Timestamp, X-Tollara-Signing-Version: 2, and user/subscription context headers: X-Tollara-User-ID, X-Tollara-Plan, optional X-Tollara-Roles, X-Tollara-Subscription-Active, and when the caller is a subscriber, X-Tollara-Billing-Model, X-Tollara-Measurement-Type, and X-Tollara-Unit-Label. There is no remaining-quota header; the signature covers the body, timestamp, and the v2 user-context string (leading 2, no quota). See Request signing (HMAC) for how to verify.