Skip to main content

API conventions

The Foundation4 REST API follows one set of conventions for routes, authentication, request bodies, errors, pagination, filters, identifiers and streaming. This page describes those conventions, which apply to every operation in the API reference. Integrators read this page before writing a client application or a client library.

Base URL and routes​

The API server serves every route at the root of the base URL, with no path prefix and no version prefix, for example $FOUNDATION4_URL/pipelines and $FOUNDATION4_URL/pipelines/{id}/search. Two groups of routes are nested:

  • OpenAI-compatible endpoint. POST /openai/v1/chat/completions, described in LLMs.
  • Model Context Protocol (MCP). The MCP server is served under /mcp, as described in MCP server.

The API uses five HTTP methods: GET to list and read, POST to create objects and to run actions such as a search, PUT to make a search index the default index of a pipeline, PATCH to change an object and DELETE to remove an object. PUT /pipelines/{id}/search-indexers/{indexer_id}/default is the only route that uses PUT.

OperationSuccess statusBody
Create an object201The new object
Read, list or change an object, or run an action200The object, the list or the result
Delete an object204None

The following operations differ from the table: POST /login returns 201 although no object is created, a document expiry request (DELETE with expire=true) returns 200, and POST /api-keys/{id}/permissions and POST /pipelines/{id}/classifications return 200 with an empty body. A request that starts work in the background returns 202 with the state of the work: rebuilding a search index (POST .../search-indexers/{indexer_id}/rebuild) and adding a distance index (POST .../search-indexers/{indexer_id}/distance-indexes). Add, rebuild or switch a search index describes these operations.

Authentication​

Every request carries the API key identifier in the x-api-key header and the secret in the x-api-key-secret header. Authenticate describes the headers and the authentication errors, and Access control describes the permissions that each operation requires.

The following routes do not require an API key: the root route /, the health check /healthz and the API documentation routes. Security hardening describes how to restrict these routes at the ingress. The Prometheus route /metrics requires no API key either, and is served on a separate port, set by app.metrics_port (9090 by default), not on the port of the API.

The installation-wide routes GET /statistics and GET /license require an admin API key, described in Access control. Any other key receives HTTP 403 with the message Forbidden: an admin API key is required. The response of POST /login reports in the field admin whether the key is an admin key.

Some operations read additional headers:

HeaderOperations
x-pipeline-idAgent execution and the agent retrieval dry run
x-llm-idAgent execution and the OpenAI-compatible endpoint

Header names are not case-sensitive.

Request bodies​

Request bodies are JSON documents sent with the header Content-Type: application/json. The following rules apply:

  • Unknown fields. A field that an operation does not define returns an error, so a misspelled optional field does not pass unnoticed. In a search request and in a request that adds a document, an unknown top-level field returns HTTP 400 with the message Unknown field `<name>`, and details.expected lists the fields of the body. In the bodies that create or change pipelines, embedding models, text splitters, LLMs, agents, API keys and taxonomies, and in the bodies that add taxonomy entries, grant permissions, change the classifications of a pipeline, create a metadata index or add a distance index, an unknown field returns HTTP 422 with a message that names the field. The parameters object of an embedding model returns HTTP 400 with the message Invalid parameter for a parameter that the provider does not define, as described in Errors. The agent search and execution bodies, the LLM and embedding model query bodies, the body that adds a search index and the deprecated fragment route ignore fields that the operation does not define.
  • Unknown query parameters. Foundation4 ignores query parameters that an operation does not define, including misspelled filter names.
  • Parsing errors. A request without the JSON content type returns HTTP 415, a body that is not valid JSON returns HTTP 400, and a body with a missing field or a field of the wrong type returns HTTP 422. These responses carry the JSON error body described in Errors, with the parsing message in message.
  • Body size. A body larger than 10 MiB (10,485,760 bytes) returns HTTP 413 with the message Failed to buffer the request body: length limit exceeded. The setting app.max_body_bytes changes the limit.

Request identifiers and cross-origin requests​

Each response from the API port carries an x-request-id header, including the responses of the root route, the health check, the API documentation routes and unknown paths. The API server generates a universally unique identifier (UUID) for each request, or keeps the value that the client sends in an x-request-id request header. The server records the value in the server's traces and in the log line of each failed request, described in Errors. Support requests quote the x-request-id value. Responses from the metrics port carry no request identifier.

The API server answers cross-origin requests from a web page only for the origins in the setting app.cors_allowed_origins, which the Helm chart sets from the value api-server.corsAllowedOrigins. The list is empty by default, so a browser blocks every cross-origin call to the API, and the dashboard, which calls the API from its own origin, needs no entry. The following rules apply:

  • Origins. Each entry is an origin in the form https://app.example.com, with the scheme, the host name and, if not the default, the port. The entry * allows any origin.
  • Methods and headers. For an allowed origin, the API server accepts the methods GET, POST, PUT, PATCH and DELETE, accepts the Foundation4 request headers such as x-api-key, x-api-key-secret, x-pipeline-id and x-llm-id, and lets the page read the response headers x-request-id and x-foundation4ai-tracing-id.
  • Other origins. A preflight request from an origin outside the list returns 200 without an access-control-allow-origin header, and the browser then blocks the request.

A web application that calls the API from the browser holds an API key in the browser, where every user of the application can read the key. Such an application therefore uses a key whose permissions and classification allow-list suit every user of the application.

Errors​

An error from an API operation returns a JSON body with a message field and, for some errors, a details field:

{
"error": {
"message": "Invalid metadata",
"details": {"product": "123 is not of type \"string\""}
}
}

The status code and message identify the error; the API has no separate error code field. The content of details depends on the error. Errors raised by the web framework before an operation runs, such as parsing errors, header errors, requests for unknown paths and methods that a route does not accept, use the same JSON body. Errors lists these errors and the few responses without the JSON body. The following table lists the status codes and common messages, and Errors lists every message and the cause of the message:

StatusMeaningCommon messages
400The request is invalidInvalid parameter, Invalid metadata, Schema error, Pagination error, Invalid order_by parameter, Classification mismatch, Invalid search type or parameters, Unknown field `<name>`
401Authentication failedInvalid API Key or Secret, Invalid key ID, Unauthorized: No API Key specified., Unauthorized: No API Secret Key specified.
403The key lacks a permission, the request names a classification outside the key's classification allow-list, the route requires an admin API key, or the license does not permit the operationUnauthorized: <permissions> access to <object type> required, Forbidden: an admin API key is required, Invalid license: ..., License limits exceeded for ...
404The object does not exist, the key cannot read the object, or the path is unknownPipeline not found, Document not found, Classification not found, LLM not found, Not found
405The route does not accept the methodMethod not allowed
409A unique name is already in use, another object still references the object, or a search index is not in the required stateConflict unique error, Conflict related error, Conflict
413The body exceeds the size limitFailed to buffer the request body: length limit exceeded
415The request lacks the JSON content typeA message that names the expected content type
422The body does not match the fields of the operationA message that starts with Failed to deserialize the JSON body
500The server or a dependency failedInternal server error
501The operation is not implementedF4ai enriched completions not implemented yet
502The model server failed during an agent execution or an LLM queryUpstream LLM error, Upstream LLM request failed
503A dependency is unavailable, or the gRPC service lacks a package or model files that the request needsUnable to validate the API key; try again later, Provider unavailable

Schema error and Pagination error carry the reason in details.error, and Schema error carries the field name, where one applies, in details.field. A Schema error on a search or list request usually means that a filter references a metadata field that the pipeline schema does not declare. A Pagination error means that the request combines offset and cursor parameters, combines first with last, requests a page size outside 1 to 1000, or carries an invalid cursor.

Most requests for a single object that the key cannot read return HTTP 404, the same status as for an object that does not exist. The document operations of a pipeline return HTTP 403 when the pipeline exists and the key lacks the permission or the classification, as described in Access control.

Pagination​

List operations return a page of results in the following envelope:

{
"data": [],
"page_info": {
"has_next": false,
"has_prev": false,
"order_by": null
},
"query_info": {}
}

data holds the objects, page_info describes the page and query_info repeats the filters that the server recognized. A filter that is missing from query_info was not applied. Search results, the versions of a document, fragments requested by identifier, the search indexes of a pipeline and the distance indexes of a search index return a plain JSON array instead of the envelope. The fragment list of a document version uses the envelope. The path list of a pipeline (GET /pipelines/{id}/paths) returns data and a next path instead of page_info, and pages with first and after, as described in Document paths.

Lists support two pagination modes, selected by the query parameters of the request:

ModeParametersUse
Cursorfirst and after to page forward; last and before to page backwardStable paging through lists that change during the read
Offsetlimit and offsetDirect access to a page by position

The following rules apply to both modes:

  • Default mode. A request without pagination parameters uses cursor mode with a page size of 25.
  • Page size. The default page size is 25 in both modes. first, last and limit accept 1 to 1000. Another value returns HTTP 400 with the message Pagination error, and details.error holds <parameter> must be between 1 and 1000, got <value>.
  • Total count. count=true adds page_info.count, the total number of matching objects, at the cost of an additional database query.
  • Exclusive modes. A request that combines cursor and offset parameters, or first and last, returns HTTP 400 with the message Pagination error.

In cursor mode, page_info carries the cursors before (of the first object on the page) and after (of the last object) and the flags has_next and has_prev. The next page is requested with after set to page_info.after, and the previous page with last and before set to page_info.before. Cursors are opaque strings. has_prev is true when objects precede the page.

A cursor records the values of the order fields. The server appends the fields that identify an object, id and for documents also created_at, to every order that lacks them, so objects with equal values in the order_by fields, such as classification, keep a fixed place, and cursor paging neither skips nor repeats objects at page boundaries. page_info.order_by lists the order with the appended fields. A cursor is used with the same order_by as the request that returned the cursor.

The following request reads the first page of 10 pipelines and the total count:

curl "$FOUNDATION4_URL/pipelines?first=10&count=true" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET"

Filters and ordering​

List operations accept filters as query parameters named after the fields of the object, with an optional operator suffix. The fields that accept filters differ by operation and are listed in the API reference.

FormMatches objects where the field
field=valueEquals the value. A repeated parameter, such as status=success&status=failed, matches objects that equal any of the values.
field$contains=valueContains the value, case-sensitive. A repeated parameter matches objects that contain every value.
field$startswith=valueStarts with the value
field$gt=value, field$ge=valueIs greater than, or greater than or equal to, the value
field$lt=value, field$le=valueIs less than, or less than or equal to, the value

Timestamps in filters use RFC 3339 format with the Z suffix, or with the + of an offset encoded as %2B. In a shell command, the $ of an operator suffix is escaped as \$ inside double quotes:

curl "$FOUNDATION4_URL/embedding-models?name\$contains=MiniLM" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET"

$contains and $startswith match % and _ as literal characters. The other operator suffixes take one value, and a repeated parameter with one of these suffixes returns HTTP 400 with a message that starts with Failed to deserialize query string.

order_by sets the order of a list: order_by=name sorts ascending and order_by=-created_at sorts descending. The default order is id ascending. A field that the operation cannot sort by returns HTTP 400 with the message Invalid order_by parameter.

The document list also accepts status and a metadata filter written in the filter language of search requests, described in Metadata, filters and taxonomies.

Identifiers, timestamps and versions​

  • Identifiers. Every object identifier is a UUID. Document identifiers are time-ordered UUIDs (version 7).
  • Timestamps. created_at, updated_at, expired_at and expiration are RFC 3339 timestamps in Coordinated Universal Time (UTC).
  • Versions. The version of a document or fragment is an integer: the creation time of the document version in microseconds since the Unix epoch. The as_of and version query parameters of document and fragment operations take the same integers.

Streaming responses​

Agent execution and direct LLM queries return the generated answer in one of three formats, selected by the stream field of the request: newline-delimited JSON (NDJSON) by default, server-sent events with "sse", or plain text with false. Response formats describes each format.

A streamed response has status 200 as soon as the response starts, so an error from the model server during generation cannot change the status. The response then ends with an error line in NDJSON, or an error event in server-sent events, that carries the message Upstream LLM error. A model server that fails before the first part of the response, or during a request with "stream": false, makes the request return HTTP 502 with the same message. Errors describes each case.

API documentation routes​

The API server publishes a description of the API in OpenAPI format and two interactive viewers:

RouteContent
GET /openapi.jsonThe OpenAPI document
GET /docsAn interactive reference built with RapiDoc
GET /_docs-swaggerThe same reference in Swagger UI

The viewers load every asset from the API server, so both work in an air-gapped deployment. The interactive reference accepts the key identifier and secret for trying operations and does not store them between visits. Send requests from an API client describes the viewers and desktop API clients.

Deprecated routes​

POST /pipelines/{id}/fragments, which reads fragments by identifier from a JSON body, is deprecated. GET /pipelines/{id}/fragments with one id query parameter for each fragment replaces the route.