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.
| Operation | Success status | Body |
|---|---|---|
| Create an object | 201 | The new object |
| Read, list or change an object, or run an action | 200 | The object, the list or the result |
| Delete an object | 204 | None |
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:
| Header | Operations |
|---|---|
x-pipeline-id | Agent execution and the agent retrieval dry run |
x-llm-id | Agent 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>`, anddetails.expectedlists 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. Theparametersobject of an embedding model returns HTTP 400 with the messageInvalid parameterfor 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 settingapp.max_body_byteschanges 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,PATCHandDELETE, accepts the Foundation4 request headers such asx-api-key,x-api-key-secret,x-pipeline-idandx-llm-id, and lets the page read the response headersx-request-idandx-foundation4ai-tracing-id. - Other origins. A preflight request from an origin outside the list returns 200 without an
access-control-allow-originheader, 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:
| Status | Meaning | Common messages |
|---|---|---|
| 400 | The request is invalid | Invalid parameter, Invalid metadata, Schema error, Pagination error, Invalid order_by parameter, Classification mismatch, Invalid search type or parameters, Unknown field `<name>` |
| 401 | Authentication failed | Invalid API Key or Secret, Invalid key ID, Unauthorized: No API Key specified., Unauthorized: No API Secret Key specified. |
| 403 | The 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 operation | Unauthorized: <permissions> access to <object type> required, Forbidden: an admin API key is required, Invalid license: ..., License limits exceeded for ... |
| 404 | The object does not exist, the key cannot read the object, or the path is unknown | Pipeline not found, Document not found, Classification not found, LLM not found, Not found |
| 405 | The route does not accept the method | Method not allowed |
| 409 | A unique name is already in use, another object still references the object, or a search index is not in the required state | Conflict unique error, Conflict related error, Conflict |
| 413 | The body exceeds the size limit | Failed to buffer the request body: length limit exceeded |
| 415 | The request lacks the JSON content type | A message that names the expected content type |
| 422 | The body does not match the fields of the operation | A message that starts with Failed to deserialize the JSON body |
| 500 | The server or a dependency failed | Internal server error |
| 501 | The operation is not implemented | F4ai enriched completions not implemented yet |
| 502 | The model server failed during an agent execution or an LLM query | Upstream LLM error, Upstream LLM request failed |
| 503 | A dependency is unavailable, or the gRPC service lacks a package or model files that the request needs | Unable 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:
| Mode | Parameters | Use |
|---|---|---|
| Cursor | first and after to page forward; last and before to page backward | Stable paging through lists that change during the read |
| Offset | limit and offset | Direct 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,lastandlimitaccept 1 to 1000. Another value returns HTTP 400 with the messagePagination error, anddetails.errorholds<parameter> must be between 1 and 1000, got <value>. - Total count.
count=trueaddspage_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
firstandlast, returns HTTP 400 with the messagePagination 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.
| Form | Matches objects where the field |
|---|---|
field=value | Equals the value. A repeated parameter, such as status=success&status=failed, matches objects that equal any of the values. |
field$contains=value | Contains the value, case-sensitive. A repeated parameter matches objects that contain every value. |
field$startswith=value | Starts with the value |
field$gt=value, field$ge=value | Is greater than, or greater than or equal to, the value |
field$lt=value, field$le=value | Is 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_atandexpirationare RFC 3339 timestamps in Coordinated Universal Time (UTC). - Versions. The
versionof a document or fragment is an integer: the creation time of the document version in microseconds since the Unix epoch. Theas_ofandversionquery 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:
| Route | Content |
|---|---|
GET /openapi.json | The OpenAPI document |
GET /docs | An interactive reference built with RapiDoc |
GET /_docs-swagger | The 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.