Skip to content

API overview

The Fourier Platform API is an HTTPS gateway in front of Fourier’s clinical models. You call it with an API key from the Fourier Platform console. For each request, the gateway verifies the key and checks that your organization has access to the model you requested. It then applies your rate limit, records usage, and forwards the request to the model.

Base URLs

Section titled “Base URLs”

The gateway has one base URL per environment:

Environment Base URL
Staging https://gateway.staging.fourierhealth.com
Production https://gateway.fourierhealth.com

Authentication

Section titled “Authentication”

Send your API key as a bearer token in the Authorization header of every request to a /v1 path:

Authorization: Bearer fh_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys start with fh_. A request with a missing, malformed, revoked, or expired key gets a 401 problem response. A valid key whose organization doesn’t have access to the endpoint or model gets 403. For the key format and the rejection codes, see Authentication. To create and manage keys, see API keys.

Requests

Section titled “Requests”
  • Send a JSON body with Content-Type: application/json. The gateway parses the body as JSON only when the Content-Type header contains json; otherwise it rejects the request with 400 invalid_body.
  • The body must be at most 1 MiB. Larger bodies get 413 payload_too_large.
  • Optional: Send an x-request-id header. The gateway uses your value as the request ID and returns it in the response; without it, the gateway generates a UUID.

OpenAI compatibility

Section titled “OpenAI compatibility”

POST /v1/embeddings has the same request and response shape as the OpenAI embeddings API, so the official openai SDKs work against the gateway. Point the SDK’s base URL at the gateway with a /v1 suffix and pass your Fourier API key as the API key. The one Fourier-specific field, input_type, isn’t in the SDK types: pass it through extra_body in Python, and widen the parameter type in TypeScript. The following examples create a client with each SDK:

import os


from openai import OpenAI


client = OpenAI(
    api_key=os.environ["FOURIER_API_KEY"],
    base_url="https://gateway.fourierhealth.com/v1",
)

For a complete example with input_type, see Embeddings.

Response headers

Section titled “Response headers”

The gateway sets the following response headers:

Header Present on Meaning
content-type Every response application/json; charset=utf-8 for a success, application/problem+json; charset=utf-8 for an error.
x-request-id Every response The request ID: the value you sent in x-request-id, or a UUID the gateway generated. Quote it when you contact support.
x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset Responses that reached the rate limit check Your limit for the requested model, how many requests remain in the current window, and seconds until the window frees up. See Rate limits.
retry-after 429 and 503 Seconds to wait before retrying.
allow 405 The methods the path supports.

Errors

Section titled “Errors”

Errors are RFC 9457 problem responses: a JSON body with status, title, code, and usually detail, served as application/problem+json. Use the code field to decide how to handle an error. For every code the gateway returns, see Errors.

Health endpoint

Section titled “Health endpoint”

GET /health needs no API key and returns 200 with a JSON body whose status is ok when the gateway is serving requests. Use it for connectivity checks; it doesn’t tell you whether a model is available.

Endpoints

Section titled “Endpoints”

The gateway serves the following endpoints:

Method Path Description
POST /v1/embeddings Embeds clinical text with ClinEmbed-1. See Embeddings.
GET /health Gateway liveness check.

A path the gateway doesn’t serve returns 404 not_found. A method a path doesn’t support returns 405 method_not_allowed with an allow header.