Skip to main content
Version: 2026-09

Foundation4 API

The Foundation4 REST API manages pipelines, documents, search, language models, agents and the objects that they depend on. This section lists every operation of the API server, grouped by the type of object. Each page describes the request, the responses and the permissions that the operation requires, with the same request as a curl, Python, TypeScript and Ruby example.

  • Base URL. Every path is relative to the base URL of the API server in a deployment. The API has no path prefix.
  • Authentication. Every operation except the welcome message and the health check requires an API key, sent in the x-api-key and x-api-key-secret headers. Authenticate describes the headers and defines the shell variables FOUNDATION4_URL, FOUNDATION4_API_KEY and FOUNDATION4_API_SECRET that every example uses.
  • Examples. The Python, TypeScript and Ruby examples use only the standard library of each language (urllib.request in Python 3, fetch in Node.js 18 or later, net/http in Ruby), so they run on hosts without access to a package registry. They read FOUNDATION4_URL, FOUNDATION4_API_KEY, FOUNDATION4_API_SECRET and identifiers such as PIPELINE_ID from the environment, so the shell exports each variable. The TypeScript examples use top-level await and run as ES modules: Node.js 22.6 or later runs a .mts file directly with the --experimental-strip-types option. Each example prints the status code and the response body.
  • Conventions. API conventions describes pagination, list filters, ordering, identifiers, timestamps and streaming responses, which the operation pages do not repeat.
  • Errors. Every authenticated operation can also return the errors of the key check and of request parsing. Errors describes the error format and every error message.
  • Search and filters. Search requests and Filter operators describe the body of a search request in detail.

Each deployment also serves the OpenAPI document of the installed version at GET /openapi.json and an interactive reference at GET /docs. The document offered for download on this page includes the corrections from the review of the code. The same requests are offered as a collection in Postman format for API clients, and Send requests from an API client describes the import.

Authentication​

Identifier of the API key, sent in the x-api-key header.

Security Scheme Type:

apiKey

Header parameter name:

x-api-key