{ "info": { "name": "Foundation4 API", "description": "The operations of the Foundation4 API, generated with the endpoint reference of the Foundation4 documentation. Set `FOUNDATION4_URL`, `FOUNDATION4_API_KEY` and `FOUNDATION4_API_SECRET` before the first request, and keep the secret out of shared or synchronized values. The variables of identifiers, such as `PIPELINE_ID`, take values from earlier responses. Send requests one at a time: running the whole collection sends every request, including the delete operations.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "Core", "description": "The welcome message and the health check of the API server. Neither operation requires an API key.", "item": [ { "name": "Get the welcome message", "request": { "method": "GET", "header": [], "url": { "raw": "{{FOUNDATION4_URL}}/", "host": [ "{{FOUNDATION4_URL}}" ], "path": [] }, "description": "Returns the plain-text string `Foundation4.ai API`. Client applications and operators use the operation to check that the API server is reachable.\n\n**Permissions.** None. The operation requires no API key." }, "response": [] }, { "name": "Check the API server health", "request": { "method": "GET", "header": [], "url": { "raw": "{{FOUNDATION4_URL}}/healthz", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "healthz" ] }, "description": "Returns a health report of the API server in JSON. A response shows that the API server accepts HTTP requests.\n\n**Permissions.** None. The operation requires no API key." }, "response": [] } ] }, { "name": "Authentication", "description": "API keys, the permissions that each key holds, and the permissions of the calling key on objects. Access control describes the permission model.", "item": [ { "name": "List API keys", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/api-keys", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "api-keys" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Returns only the API key with this identifier." }, { "key": "name", "value": "", "disabled": true, "description": "Returns only API keys whose name equals this value, case-sensitive." }, { "key": "name$contains", "value": "", "disabled": true, "description": "Matches objects whose `name` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "name$startswith", "value": "", "disabled": true, "description": "Matches objects whose `name` starts with the value." }, { "key": "name$gt", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than the value." }, { "key": "name$ge", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than or equal to the value." }, { "key": "name$lt", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than the value." }, { "key": "name$le", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than or equal to the value." }, { "key": "description", "value": "", "disabled": true, "description": "Returns only API keys whose description equals this value, case-sensitive." }, { "key": "description$contains", "value": "", "disabled": true, "description": "Matches objects whose `description` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "created_at", "value": "", "disabled": true, "description": "Returns only API keys created at exactly this time, in RFC 3339 format." }, { "key": "created_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than the value." }, { "key": "created_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than the value." }, { "key": "created_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than or equal to the value." }, { "key": "created_at$le", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than or equal to the value." }, { "key": "updated_at", "value": "", "disabled": true, "description": "Returns only API keys last changed at exactly this time, in RFC 3339 format." }, { "key": "updated_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than the value." }, { "key": "updated_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than the value." }, { "key": "updated_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than or equal to the value." }, { "key": "updated_at$le", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than or equal to the value." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `name`, `active`, `expiration`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns a page of the API keys that the calling key can read, without the secrets. The list supports filters, ordering and cursor or offset pagination, as described in API conventions.\n\n**Permissions.** Read on the API keys. The list contains only the keys that the calling key can read." }, "response": [] }, { "name": "Create an API key", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/api-keys", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "api-keys" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"support-portal-search\",\n \"description\": \"Search key for the support portal\",\n \"expiration\": \"2027-09-30T00:00:00Z\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates an API key with permissions on object types and returns the new key with a generated secret. Foundation4 returns the secret only in this response and stores only a hash, so a lost secret cannot be recovered. Permissions on individual objects are granted afterward with `POST /api-keys/{api_key_id}/permissions`.\n\n**Permissions.** Write on the `api-keys` object type. Each permission in `permissions` must be contained in the calling key's permission on the same object type. When the calling key's allow-list on `pipelines` is not `*`, each classification in `classifications` must be in the calling key's allow-list.\n\nAccess control describes permissions and classification allow-lists." }, "response": [] }, { "name": "Get an API key", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/api-keys/{{API_KEY_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "api-keys", "{{API_KEY_ID}}" ] }, "description": "Returns one API key, without the secret.\n\n**Permissions.** Read on the API key." }, "response": [] }, { "name": "Update an API key", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/api-keys/{{API_KEY_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "api-keys", "{{API_KEY_ID}}" ] }, "body": { "mode": "raw", "raw": "{\n \"active\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Changes the name, description, active status or expiration time of an API key. Fields that the request omits keep their values, and `null` removes the description or the expiration time. Deactivation with `\"active\": false` takes effect on the next request that uses the key.\n\n**Permissions.** Write on the API key." }, "response": [] }, { "name": "Delete an API key", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/api-keys/{{API_KEY_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "api-keys", "{{API_KEY_ID}}" ] }, "description": "Deletes an API key and the key's permission entries. Requests that use the deleted key are refused from the next request. A key cannot delete itself.\n\n**Permissions.** Write on the `api-keys` object type." }, "response": [] }, { "name": "List the permissions of an API key", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/api-keys/{{API_KEY_ID}}/permissions", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "api-keys", "{{API_KEY_ID}}", "permissions" ] }, "description": "Returns every permission entry of an API key: the entries on object types and the entries on individual objects. An entry on an object type has the object identifier `00000000-0000-0000-0000-000000000000`.\n\n**Permissions.** Read on the API key.\n\nAccess control describes permission entries." }, "response": [] }, { "name": "Set the permissions of an API key", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/api-keys/{{API_KEY_ID}}/permissions", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "api-keys", "{{API_KEY_ID}}", "permissions" ] }, "body": { "mode": "raw", "raw": "{\n \"permissions\": [\n {\n \"object_type\": \"pipelines\",\n \"object_id\": \"{{PIPELINE_ID}}\",\n \"permission\": 5\n }\n ],\n \"classifications\": [\n \"public\",\n \"internal\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Adds, changes or removes permission entries of an API key; entries that the request does not name are unchanged. An entry replaces the entry with the same object type and object identifier, and a permission of 0 removes the entry. Foundation4 applies all entries in one transaction, so a refused entry leaves every entry unchanged.\n\n**Permissions.** Write on the API key. Each granted permission must be contained in the calling key's permission on the object type or on the object. When the calling key's allow-list on `pipelines` is not `*`, the granted classifications must be in the calling key's allow-list for the pipeline.\n\nScoped keys describes the request with an example." }, "response": [] }, { "name": "Check an API key", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/login", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "login" ] }, "description": "Checks the API key in the `x-api-key` and `x-api-key-secret` headers and returns the name and description of the key and the key's permissions on object types. The request has no body. The response has status 201, although the operation creates no object.\n\n**Permissions.** None. Any valid API key can call the operation.\n\nAuthenticate describes the authentication headers." }, "response": [] }, { "name": "Get permissions on object types", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/permissions", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "permissions" ] }, "description": "Returns the permissions of the calling API key on object types, with the classification allow-list of the `pipelines` permission. Permissions on individual objects are not included; `GET /permissions/{object_type}/{object_id}` reports the permission on one object.\n\n**Permissions.** None. The operation reports the permissions of the calling key, and any valid API key can call the operation.\n\nAccess control describes the permission model." }, "response": [] }, { "name": "Get permissions on several objects", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/permissions/{{OBJECT_TYPE}}?object_id={{OBJECT_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "permissions", "{{OBJECT_TYPE}}" ], "query": [ { "key": "object_id", "value": "{{OBJECT_ID}}", "description": "Identifier of an object. The parameter is repeated for each object." } ] }, "description": "Returns the permissions of the calling API key on several objects of one type, as an object that maps each object identifier to a permission from 0 to 7. The request names each object in a separate `object_id` query parameter, such as `?object_id=&object_id=`. Each permission combines the key's permission on the object type with the key's permission on the object.\n\n**Permissions.** None. The operation reports the permissions of the calling key, and any valid API key can call the operation.\n\nAccess control describes the permission model." }, "response": [] }, { "name": "Get the permission on an object", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/permissions/{{OBJECT_TYPE}}/{{OBJECT_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "permissions", "{{OBJECT_TYPE}}", "{{OBJECT_ID}}" ] }, "description": "Returns the permission of the calling API key on one object, as the sum of the permission bits: read 4, write 2 and execute 1. The value combines the key's permission on the object type with the key's permission on the object.\n\n**Permissions.** None. The operation reports the permissions of the calling key, and any valid API key can call the operation.\n\nAccess control describes the permission model." }, "response": [] } ] }, { "name": "Pipelines", "description": "Pipelines, the classifications of a pipeline and the metadata indexes of a pipeline. Pipelines describes the settings of a pipeline.", "item": [ { "name": "List pipelines", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Returns only the pipeline with this identifier." }, { "key": "name", "value": "", "disabled": true, "description": "Returns only pipelines whose name equals this value, case-sensitive." }, { "key": "name$contains", "value": "", "disabled": true, "description": "Matches objects whose `name` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "name$startswith", "value": "", "disabled": true, "description": "Matches objects whose `name` starts with the value." }, { "key": "name$gt", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than the value." }, { "key": "name$ge", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than or equal to the value." }, { "key": "name$lt", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than the value." }, { "key": "name$le", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than or equal to the value." }, { "key": "description", "value": "", "disabled": true, "description": "Returns only pipelines whose description equals this value, case-sensitive." }, { "key": "description$contains", "value": "", "disabled": true, "description": "Matches objects whose `description` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "created_at", "value": "", "disabled": true, "description": "Matches objects whose `created_at` equals the value." }, { "key": "created_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than the value." }, { "key": "created_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than the value." }, { "key": "created_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than or equal to the value." }, { "key": "created_at$le", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than or equal to the value." }, { "key": "updated_at", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` equals the value." }, { "key": "updated_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than the value." }, { "key": "updated_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than the value." }, { "key": "updated_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than or equal to the value." }, { "key": "updated_at$le", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than or equal to the value." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `name`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns a page of pipelines that the key can read. The response is a paginated envelope. Results can be filtered by field and ordered, as described in API conventions.\n\n**Permissions.** Read on a pipeline includes that pipeline in the list. The list returns only the pipelines the key can read." }, "response": [] }, { "name": "Create a pipeline", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"support-kb\",\n \"description\": \"Support knowledge base\",\n \"embedding_model_id\": \"{{EMBEDDING_MODEL_ID}}\",\n \"default_text_splitter_id\": \"{{TEXT_SPLITTER_ID}}\",\n \"classifications\": [\n \"public\",\n [\n \"internal\",\n \"public\"\n ]\n ],\n \"has_full_text_search\": true,\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"product\": {\n \"type\": \"string\"\n }\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a pipeline. The embedding model and the full-text search setting are fixed at creation and cannot change afterwards. The request names the classifications the pipeline defines and an optional metadata schema. The response body is the new pipeline.\n\n**Permissions.** Write on the `pipelines` object type. Creating a pipeline also requires write on the text splitter named in the request, and write on the embedding model when the request names one.\n\nSee Pipelines." }, "response": [] }, { "name": "Get a pipeline", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}" ] }, "description": "Returns a pipeline by identifier. The response body is the pipeline together with the embedding models the pipeline uses, keyed by vector embedding identifier.\n\n**Permissions.** Read on the pipeline.\n\nSee Pipelines." }, "response": [] }, { "name": "Update a pipeline", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}" ] }, "body": { "mode": "raw", "raw": "{\n \"description\": \"Support knowledge base for every product\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Changes the name, description, default text splitter or metadata schema of a pipeline. The embedding model, the full-text search setting and the classifications cannot be changed through this operation. The response body shows the pipeline as it was before the change, so a client application reads the pipeline with `GET /pipelines/{pipeline_id}` to confirm the new values.\n\n**Permissions.** Write on the pipeline.\n\nSettings that can change explains why a client sends every change to a pipeline in one request." }, "response": [] }, { "name": "Delete a pipeline", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}" ] }, "description": "Deletes a pipeline, every document and version in the pipeline, and the pipeline's tables. The deletion is permanent. The response has no body.\n\n**Permissions.** Write on the pipeline.\n\nSee Pipelines." }, "response": [] }, { "name": "List pipeline classifications", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/classifications", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "classifications" ] }, "description": "Returns the classifications the pipeline defines and the inheritance relationships between them. The `hierarchy` field is a list of pairs, each holding a classification and the inherited classification.\n\n**Permissions.** Read on the pipeline and the `*` classification allow-list, because the response includes the inheritance relationships.\n\nSee Classifications." }, "response": [] }, { "name": "Modify pipeline classifications", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/classifications", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "classifications" ] }, "body": { "mode": "raw", "raw": "{\n \"add\": [\n [\n \"finance\",\n \"internal\"\n ]\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Adds and removes classifications and inheritance relationships in one transaction. The request body holds an `add` list and a `remove` list, each using the classification forms of the create request. Additions are processed before removals. Removing a classification permanently deletes every document that carries the classification. The response has no body.\n\n**Permissions.** Write on the pipeline and the `*` classification allow-list.\n\nSee Classifications." }, "response": [] }, { "name": "List metadata indexes", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/indexes", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "indexes" ] }, "description": "Returns the metadata indexes defined on a pipeline. The response body is a JSON array. Each element holds the index identifier and the metadata fields the index covers.\n\n**Permissions.** Read and execute on the pipeline.\n\nSee Pipelines." }, "response": [] }, { "name": "Create a metadata index", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/indexes", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "indexes" ] }, "body": { "mode": "raw", "raw": "{\n \"columns\": [\n \"product\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a metadata index on one or more top-level metadata fields of a pipeline. Each field named in `columns` must be a top-level field declared in the pipeline's metadata schema with a scalar type. The response body is the new index.\n\n**Permissions.** Write and execute on the pipeline.\n\nSee Pipelines." }, "response": [] }, { "name": "Get a metadata index", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/indexes/{{INDEX_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "indexes", "{{INDEX_ID}}" ] }, "description": "Returns a metadata index of a pipeline by identifier. The response body holds the index identifier and the fields the index covers.\n\n**Permissions.** Read and execute on the pipeline.\n\nSee Pipelines." }, "response": [] }, { "name": "Delete a metadata index", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/indexes/{{INDEX_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "indexes", "{{INDEX_ID}}" ] }, "description": "Deletes a metadata index of a pipeline. The operation does not check that the index exists, so a request for an index that does not exist also returns HTTP 204. The response has no body.\n\n**Permissions.** Write and execute on the pipeline.\n\nSee Pipelines." }, "response": [] } ] }, { "name": "Documents", "description": "Documents, document versions and fragments. Documents, versions and fragments describes the lifecycle of a document.", "item": [ { "name": "Add a document with pipeline ID in body", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/documents", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "documents" ] }, "body": { "mode": "raw", "raw": "{\n \"pipeline_id\": \"{{PIPELINE_ID}}\",\n \"classification\": \"public\",\n \"external_identifier\": \"kb-password-reset\",\n \"metadata\": {\n \"product\": \"accounts\"\n },\n \"contents\": \"To reset a password, open Settings, choose Security and select Reset password. A reset link is sent to the registered email address and expires after 30 minutes.\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Adds a document, or a new version of an existing document, to the pipeline named in the `pipeline_id` field of the body. The operation behaves as `POST /pipelines/{pipeline_id}/documents`: processing is asynchronous, and the response returns the new version with the status `pending`, or `failed` when the processing job cannot be queued.\n\n**Permissions.** Read and execute on the pipeline, execute on the text splitter that processes the document, and the document's classification in the allow-list.\n\nDocuments, versions and fragments describes the request fields, processing and versions." }, "response": [] }, { "name": "Get a document version", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/documents/{{DOCUMENT_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "documents", "{{DOCUMENT_ID}}" ], "query": [ { "key": "version", "value": "", "disabled": true, "description": "Version to return, in microseconds since the Unix epoch, as returned in the `version` field. Without the parameter, the operation returns the latest version." } ] }, "description": "Returns one version of a document, found by the document identifier alone. Without the `version` query parameter, the response is the latest version of the document, whether or not that version has expired. The `status` field of the response shows whether processing of the version is complete.\n\n**Permissions.** Read on the document's pipeline.\n\nDocuments, versions and fragments describes versions and the processing status." }, "response": [] }, { "name": "Delete or expire a document by ID", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/documents/{{DOCUMENT_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "documents", "{{DOCUMENT_ID}}" ], "query": [ { "key": "as_of", "value": "", "disabled": true, "description": "Point in time in microseconds since the Unix epoch. The operation then applies only to versions created at or before that time." }, { "key": "expire", "value": "", "disabled": true, "description": "Whether to expire the document instead of deleting the document. The default is `false`." } ] }, "description": "Deletes or expires a document found by the document identifier alone, without the pipeline identifier. Without `expire`, the operation permanently removes every version and every fragment of the document and returns status 204. With `expire=true`, the operation marks every current version as expired and returns status 200, and the version history remains readable.\n\n**Permissions.** To delete: read, write and execute on the pipeline, and the document's classification in the allow-list. To expire: write and execute on the pipeline, and the document's classification in the allow-list.\n\nDocuments, versions and fragments compares expiry and deletion." }, "response": [] }, { "name": "List document versions", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/documents/{{DOCUMENT_ID}}/versions", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "documents", "{{DOCUMENT_ID}}", "versions" ], "query": [ { "key": "as_of", "value": "", "disabled": true, "description": "Point in time in microseconds since the Unix epoch. The array then contains the versions created at or before that time and, without `include_expired`, only the versions that had not expired at that time." }, { "key": "include_expired", "value": "", "disabled": true, "description": "Whether to include expired versions. The default is `false`." } ] }, "description": "Returns the versions of a document as a JSON array, newest first, without the list envelope. By default the array contains only current versions, and `include_expired=true` adds the expired versions. A document identifier that matches no version returns an empty array.\n\n**Permissions.** Read on the document's pipeline.\n\nDocuments, versions and fragments describes versions and point-in-time reads." }, "response": [] }, { "name": "List documents", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/documents", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "documents" ], "query": [ { "key": "metadata", "value": "", "disabled": true, "description": "Metadata filter as URL-encoded JSON, in the filter language of search requests. The filter must match the pipeline's metadata schema." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `external_identifier`, `classification`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." }, { "key": "as_of", "value": "", "disabled": true, "description": "Point in time in microseconds since the Unix epoch. The list then contains the versions created at or before that time that had not expired at that time." }, { "key": "id", "value": "", "disabled": true, "description": "Returns only the versions of the document with this identifier." }, { "key": "external_identifier", "value": "", "disabled": true, "description": "Returns only the versions whose external identifier equals this value." }, { "key": "external_identifier$contains", "value": "", "disabled": true, "description": "Matches objects whose `external_identifier` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "created_at", "value": "", "disabled": true, "description": "Returns only the versions created at this time, in RFC 3339 format." }, { "key": "created_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than the value." }, { "key": "created_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than the value." }, { "key": "created_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than or equal to the value." }, { "key": "created_at$le", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than or equal to the value." }, { "key": "updated_at", "value": "", "disabled": true, "description": "Returns only the versions last changed at this time, in RFC 3339 format." }, { "key": "updated_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than the value." }, { "key": "updated_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than the value." }, { "key": "updated_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than or equal to the value." }, { "key": "updated_at$le", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than or equal to the value." }, { "key": "status", "value": "", "disabled": true, "description": "Returns only the versions with this processing status: `pending`, `success` or `failed`." } ] }, "description": "Returns one page of the document versions in a pipeline that are current, or that were current at the time given in `as_of`. A document with several current versions appears once for each version. Query parameters filter the list by document fields and by metadata, and the `status` filter finds versions whose processing is not complete.\n\n**Permissions.** Read on the pipeline.\n\nAPI conventions describes pagination, field filters and ordering, and Filter operators describes the `metadata` filter." }, "response": [] }, { "name": "Add a document", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/documents", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "documents" ] }, "body": { "mode": "raw", "raw": "{\n \"classification\": \"public\",\n \"external_identifier\": \"kb-password-reset\",\n \"metadata\": {\n \"product\": \"accounts\"\n },\n \"contents\": \"To reset a password, open Settings, choose Security and select Reset password. A reset link is sent to the registered email address and expires after 30 minutes.\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Adds a document to a pipeline, or a new version of the document that has the same `external_identifier` in the pipeline. Processing is asynchronous: the response returns the new version with the status `pending`, or `failed` when the processing job cannot be queued. The client application retrieves the document until the status is `success`.\n\n**Permissions.** Read and execute on the pipeline, execute on the text splitter that processes the document, and the document's classification in the allow-list.\n\nDocuments, versions and fragments describes the request fields, processing and versions." }, "response": [] }, { "name": "Delete or expire all documents", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/documents", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "documents" ], "query": [ { "key": "as_of", "value": "", "disabled": true, "description": "Point in time in microseconds since the Unix epoch. The operation then applies only to versions created at or before that time." }, { "key": "expire", "value": "", "disabled": true, "description": "Whether to expire the documents instead of deleting the documents. The default is `false`." } ] }, "description": "Deletes or expires every document in a pipeline. Without `expire`, the operation permanently removes every version and every fragment and returns status 204. With `expire=true`, the operation marks every current version as expired and returns status 200.\n\n**Permissions.** Write and execute on the pipeline, and an allow-list that includes every classification of the pipeline.\n\nDocuments, versions and fragments compares expiry and deletion." }, "response": [] }, { "name": "Get a document", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/documents/{{DOCUMENT_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "documents", "{{DOCUMENT_ID}}" ], "query": [ { "key": "as_of", "value": "", "disabled": true, "description": "Point in time in microseconds since the Unix epoch. The operation then returns the latest version created at or before that time and, without `include_expired`, only a version that had not expired at that time." }, { "key": "include_expired", "value": "", "disabled": true, "description": "Whether to consider expired versions. The default is `false`." } ] }, "description": "Returns the latest current version of a document in a pipeline, with the processing status in the `status` field. A client application retrieves the document after adding the document to find out when processing is complete. `as_of` returns the version that was current at a given time, and `include_expired=true` also considers expired versions.\n\n**Permissions.** Read on the pipeline.\n\nDocuments, versions and fragments describes the processing lifecycle and point-in-time reads." }, "response": [] }, { "name": "Delete or expire a document", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/documents/{{DOCUMENT_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "documents", "{{DOCUMENT_ID}}" ], "query": [ { "key": "as_of", "value": "", "disabled": true, "description": "Point in time in microseconds since the Unix epoch. The operation then applies only to versions created at or before that time." }, { "key": "expire", "value": "", "disabled": true, "description": "Whether to expire the document instead of deleting the document. The default is `false`." } ] }, "description": "Deletes or expires a document in a pipeline. Without `expire`, the operation permanently removes every version and every fragment of the document and returns status 204. With `expire=true`, the operation marks every current version as expired and returns status 200, and the version history remains readable.\n\n**Permissions.** To delete: read, write and execute on the pipeline, and the document's classification in the allow-list. To expire: write and execute on the pipeline, and the document's classification in the allow-list.\n\nDocuments, versions and fragments compares expiry and deletion." }, "response": [] }, { "name": "List document fragments", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/documents/{{DOCUMENT_ID}}/fragments", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "documents", "{{DOCUMENT_ID}}", "fragments" ], "query": [ { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `order_id`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." }, { "key": "as_of", "value": "", "disabled": true, "description": "Point in time in microseconds since the Unix epoch. The operation then lists the fragments of the latest version created at or before that time." }, { "key": "contents", "value": "", "disabled": true, "description": "Whether to include the decrypted text of each fragment in `page_content`. The default is `false`." } ] }, "description": "Returns one page of the fragments of one document version, in the order of the fragments within the version. The version is the latest version of the document, or the latest version created at or before `as_of`, including an expired version. The fragment text is included in `page_content` only when the request sets `contents=true`.\n\n**Permissions.** Read and execute on the pipeline.\n\nDocuments, versions and fragments describes fragments, and API conventions describes pagination." }, "response": [] }, { "name": "Get fragments by ID", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/fragments?id={{ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "fragments" ], "query": [ { "key": "id", "value": "{{ID}}", "description": "Identifier of a fragment to return. Repeat the parameter for each fragment, for example `?id=&id=`. Without the parameter, the array is empty." } ] }, "description": "Returns the fragments of a pipeline that have the given identifiers, as a JSON array without the list envelope. The array omits identifiers that match no fragment and fragments whose classification is outside the key's classification allow-list for the pipeline, and includes expired fragments. The order of the array is not defined. Each fragment holds the identifier, classification, metadata, version and position, but not the text: the fragment list of the document version returns the text when the request sets `contents=true`.\n\n**Permissions.** Read and execute on the pipeline.\n\nDocuments, versions and fragments describes fragments." }, "response": [] }, { "name": "Get fragments by ID (deprecated)", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/fragments", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "fragments" ] }, "body": { "mode": "raw", "raw": "{\n \"ids\": [\n \"{{FRAGMENT_ID}}\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "This operation is deprecated. `GET /pipelines/{pipeline_id}/fragments` with one `id` query parameter for each fragment replaces the operation. The operation returns the same fragments as the `GET` operation, for the identifiers in the `ids` field of the body.\n\n**Permissions.** Read and execute on the pipeline." }, "response": [] } ] }, { "name": "Search", "description": "Similarity, maximal marginal relevance (MMR) and full-text search of a pipeline. Search requests describes every field of the request.", "item": [ { "name": "Search a pipeline", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/pipelines/{{PIPELINE_ID}}/search", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "pipelines", "{{PIPELINE_ID}}", "search" ] }, "body": { "mode": "raw", "raw": "{\n \"query\": \"How can finance export invoices?\",\n \"classification\": \"internal\",\n \"type\": \"similarity\",\n \"params\": {\n \"k\": 3\n },\n \"filters\": {\n \"product\": {\n \"$eq\": \"billing\"\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "description": "Runs one similarity, maximal marginal relevance (MMR) or full-text search on a pipeline and returns the matching fragments as a JSON array, without the list envelope. The request body names the search text, the reader's classifications, the search type with the parameters of the type and an optional metadata filter.\n\n**Permissions.** Read and execute on the pipeline.\n\nSearch requests describes every field, the search types, the response and the errors." }, "response": [] } ] }, { "name": "Taxonomies", "description": "Taxonomies and taxonomy entries, which extend metadata filters across a hierarchy of values. Metadata, filters and taxonomies describes taxonomy filters.", "item": [ { "name": "List taxonomies", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/taxonomies", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "taxonomies" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Returns only the taxonomy with this identifier." }, { "key": "name", "value": "", "disabled": true, "description": "Returns only taxonomies whose name equals this value, case-sensitive." }, { "key": "name$contains", "value": "", "disabled": true, "description": "Matches objects whose `name` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "name$startswith", "value": "", "disabled": true, "description": "Matches objects whose `name` starts with the value." }, { "key": "name$gt", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than the value." }, { "key": "name$ge", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than or equal to the value." }, { "key": "name$lt", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than the value." }, { "key": "name$le", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than or equal to the value." }, { "key": "description", "value": "", "disabled": true, "description": "Returns only taxonomies whose description equals this value, case-sensitive." }, { "key": "description$contains", "value": "", "disabled": true, "description": "Matches objects whose `description` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "created_at", "value": "", "disabled": true, "description": "Matches objects whose `created_at` equals the value." }, { "key": "created_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than the value." }, { "key": "created_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than the value." }, { "key": "created_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than or equal to the value." }, { "key": "created_at$le", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than or equal to the value." }, { "key": "updated_at", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` equals the value." }, { "key": "updated_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than the value." }, { "key": "updated_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than the value." }, { "key": "updated_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than or equal to the value." }, { "key": "updated_at$le", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than or equal to the value." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `name`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns a page of taxonomies that the key can read. The response is a paginated envelope. Results can be filtered by field and ordered, as described in API conventions.\n\n**Permissions.** Read on a taxonomy includes that taxonomy in the list. The list returns only the taxonomies the key can read." }, "response": [] }, { "name": "Create a taxonomy", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/taxonomies", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "taxonomies" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"regions\",\n \"description\": \"Regions, countries and cities\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a taxonomy. A taxonomy is independent of any pipeline, so one taxonomy can serve several pipelines. Entries are added with a separate operation. The response body is the new taxonomy.\n\n**Permissions.** Write on the `taxonomies` object type.\n\nSee Metadata, filters and taxonomies." }, "response": [] }, { "name": "Get a taxonomy", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/taxonomies/{{TAXONOMY_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "taxonomies", "{{TAXONOMY_ID}}" ] }, "description": "Returns a taxonomy by identifier. The response body is the taxonomy.\n\n**Permissions.** Read on the taxonomy.\n\nSee Metadata, filters and taxonomies." }, "response": [] }, { "name": "Update a taxonomy", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/taxonomies/{{TAXONOMY_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "taxonomies", "{{TAXONOMY_ID}}" ] }, "body": { "mode": "raw", "raw": "{\n \"description\": \"Sales regions, countries and cities\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Changes the name or description of a taxonomy. The response body is the updated taxonomy.\n\n**Permissions.** Write on the taxonomy.\n\nSee Metadata, filters and taxonomies." }, "response": [] }, { "name": "Delete a taxonomy", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/taxonomies/{{TAXONOMY_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "taxonomies", "{{TAXONOMY_ID}}" ] }, "description": "Deletes a taxonomy and every entry in the taxonomy. The response has no body.\n\n**Permissions.** Write on the taxonomy.\n\nSee Metadata, filters and taxonomies." }, "response": [] }, { "name": "List taxonomy entries", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/taxonomies/{{TAXONOMY_ID}}/entries", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "taxonomies", "{{TAXONOMY_ID}}", "entries" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Matches objects whose `id` equals the value." }, { "key": "parent", "value": "", "disabled": true, "description": "Returns only entries whose parent field has this name." }, { "key": "parent$contains", "value": "", "disabled": true, "description": "Matches objects whose `parent` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "parent$startswith", "value": "", "disabled": true, "description": "Matches objects whose `parent` starts with the value." }, { "key": "child", "value": "", "disabled": true, "description": "Returns only entries whose child field has this name." }, { "key": "child$contains", "value": "", "disabled": true, "description": "Matches objects whose `child` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "child$startswith", "value": "", "disabled": true, "description": "Matches objects whose `child` starts with the value." }, { "key": "created_at", "value": "", "disabled": true, "description": "Matches objects whose `created_at` equals the value." }, { "key": "created_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than the value." }, { "key": "created_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than the value." }, { "key": "created_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than or equal to the value." }, { "key": "created_at$le", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than or equal to the value." }, { "key": "updated_at", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` equals the value." }, { "key": "updated_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than the value." }, { "key": "updated_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than the value." }, { "key": "updated_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than or equal to the value." }, { "key": "updated_at$le", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than or equal to the value." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns a page of the entries of a taxonomy. Each entry links a parent field and value to a child field and value. The response is a paginated envelope. Results can be filtered by field and ordered, as described in API conventions.\n\n**Permissions.** Read on the taxonomy.\n\nSee Metadata, filters and taxonomies." }, "response": [] }, { "name": "Create taxonomy entries", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/taxonomies/{{TAXONOMY_ID}}/entries", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "taxonomies", "{{TAXONOMY_ID}}", "entries" ] }, "body": { "mode": "raw", "raw": "[\n {\n \"parent\": \"region\",\n \"parent_value\": \"Europe\",\n \"child\": \"country\",\n \"child_value\": \"France\"\n },\n {\n \"parent\": \"region\",\n \"parent_value\": \"Europe\",\n \"child\": \"country\",\n \"child_value\": \"Germany\"\n },\n {\n \"parent\": \"country\",\n \"parent_value\": \"France\",\n \"child\": \"city\",\n \"child_value\": \"Paris\"\n }\n]", "options": { "raw": { "language": "json" } } }, "description": "Adds entries to a taxonomy. The request body is a JSON array of entries, each linking a parent field and value to a child field and value. The response body is the array of entries that were created. Changes take effect in the next search, without reprocessing any document.\n\n**Permissions.** Write on the taxonomy.\n\nSee Metadata, filters and taxonomies." }, "response": [] }, { "name": "Delete taxonomy entries", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/taxonomies/{{TAXONOMY_ID}}/entries?entry_id={{ENTRY_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "taxonomies", "{{TAXONOMY_ID}}", "entries" ], "query": [ { "key": "entry_id", "value": "{{ENTRY_ID}}", "description": "Identifier of a taxonomy entry to delete. The parameter is repeated once for each entry, and at least one value is required." } ] }, "description": "Deletes taxonomy entries by identifier. The identifiers are given in the `entry_id` query parameter, repeated once for each entry. The response has no body.\n\n**Permissions.** Write on the taxonomy.\n\nSee Metadata, filters and taxonomies." }, "response": [] } ] }, { "name": "Providers", "description": "The embedding providers and text splitter providers that the deployment supports. Providers and models lists every provider with the parameters that the provider accepts.", "item": [ { "name": "List embedding providers", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/providers/embeddings", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "providers", "embeddings" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Returns only the embedding provider with this identifier." }, { "key": "provider", "value": "", "disabled": true, "description": "Returns only embedding providers whose name equals this value, such as `FastEmbedEmbeddings`. The match is case-sensitive." }, { "key": "provider$contains", "value": "", "disabled": true, "description": "Matches objects whose `provider` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "provider$startswith", "value": "", "disabled": true, "description": "Matches objects whose `provider` starts with the value." }, { "key": "description", "value": "", "disabled": true, "description": "Returns only embedding providers whose description equals this value, case-sensitive." }, { "key": "description$contains", "value": "", "disabled": true, "description": "Matches objects whose `description` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `provider`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns a page of the embedding providers that the key can read. The five embedding providers that Foundation4 supports are created with the deployment, and no operation creates, changes or deletes a provider. Filters apply to the provider name and the description. `order_by` accepts `id`, `created_at`, `updated_at` and `provider`. API conventions describes pagination, filters and ordering.\n\n**Permissions.** Read on the embedding providers. The list contains only the embedding providers that the key can read.\n\nProviders and models describes each provider." }, "response": [] }, { "name": "Get an embedding provider", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/providers/embeddings/{{EMBEDDING_PROVIDER_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "providers", "embeddings", "{{EMBEDDING_PROVIDER_ID}}" ] }, "description": "Returns one embedding provider. An embedding provider is an engine that Foundation4 supports for converting text into vectors, such as `FastEmbedEmbeddings`. The name of the provider is the value of the `provider` field of an embedding model.\n\n**Permissions.** Read on the embedding provider.\n\nProviders and models describes each provider." }, "response": [] }, { "name": "List text splitter providers", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/providers/text-splitters", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "providers", "text-splitters" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Returns only the text splitter provider with this identifier." }, { "key": "provider", "value": "", "disabled": true, "description": "Returns only text splitter providers whose name equals this value, such as `RecursiveCharacterTextSplitter`. The match is case-sensitive." }, { "key": "provider$contains", "value": "", "disabled": true, "description": "Matches objects whose `provider` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "provider$startswith", "value": "", "disabled": true, "description": "Matches objects whose `provider` starts with the value." }, { "key": "description", "value": "", "disabled": true, "description": "Returns only text splitter providers whose description equals this value, case-sensitive." }, { "key": "description$contains", "value": "", "disabled": true, "description": "Matches objects whose `description` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `provider`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns a page of the text splitter providers that the key can read. The seven text splitter providers that Foundation4 supports are created with the deployment, and no operation creates, changes or deletes a provider. Filters apply to the provider name and the description. `order_by` accepts `id`, `created_at`, `updated_at` and `provider`. API conventions describes pagination, filters and ordering.\n\n**Permissions.** Read on the text splitter providers. The list contains only the text splitter providers that the key can read.\n\nProviders and models describes each provider." }, "response": [] }, { "name": "Get a text splitter provider", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/providers/text-splitters/{{TEXT_SPLITTER_PROVIDER_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "providers", "text-splitters", "{{TEXT_SPLITTER_PROVIDER_ID}}" ] }, "description": "Returns one text splitter provider. A text splitter provider is a splitting method that Foundation4 supports, such as `RecursiveCharacterTextSplitter`. The name of the provider is the value of the `provider` field of a text splitter.\n\n**Permissions.** Read on the text splitter provider.\n\nProviders and models describes each provider and the provider's parameters." }, "response": [] } ] }, { "name": "Embedding Models", "description": "Embedding models, which convert fragments and queries into vectors. Embedding models and text splitters describes the object type.", "item": [ { "name": "List embedding models", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/embedding-models", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "embedding-models" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Returns only the embedding model with this identifier." }, { "key": "name", "value": "", "disabled": true, "description": "Returns only embedding models whose name equals this value, case-sensitive." }, { "key": "name$contains", "value": "", "disabled": true, "description": "Matches objects whose `name` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "name$startswith", "value": "", "disabled": true, "description": "Matches objects whose `name` starts with the value." }, { "key": "name$gt", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than the value." }, { "key": "name$ge", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than or equal to the value." }, { "key": "name$lt", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than the value." }, { "key": "name$le", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than or equal to the value." }, { "key": "provider", "value": "", "disabled": true, "description": "Returns only embedding models whose provider name equals this value, such as `FastEmbedEmbeddings`. The match is case-sensitive." }, { "key": "provider$contains", "value": "", "disabled": true, "description": "Matches objects whose `provider` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "provider$startswith", "value": "", "disabled": true, "description": "Matches objects whose `provider` starts with the value." }, { "key": "description", "value": "", "disabled": true, "description": "Returns only embedding models whose description equals this value, case-sensitive." }, { "key": "description$contains", "value": "", "disabled": true, "description": "Matches objects whose `description` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "created_at", "value": "", "disabled": true, "description": "Returns only embedding models created at exactly this time, in RFC 3339 format." }, { "key": "created_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than the value." }, { "key": "created_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than the value." }, { "key": "created_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than or equal to the value." }, { "key": "created_at$le", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than or equal to the value." }, { "key": "updated_at", "value": "", "disabled": true, "description": "Returns only embedding models last changed at exactly this time, in RFC 3339 format." }, { "key": "updated_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than the value." }, { "key": "updated_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than the value." }, { "key": "updated_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than or equal to the value." }, { "key": "updated_at$le", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than or equal to the value." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `name`, `provider`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns a page of the embedding models that the key can read. Filters apply to the name, provider, description and timestamps. `order_by` accepts `id`, `created_at`, `updated_at`, `name` and `provider`. API conventions describes pagination, filters and ordering.\n\n**Permissions.** Read on the embedding models. The list contains only the embedding models that the key can read." }, "response": [] }, { "name": "Create an embedding model", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/embedding-models", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "embedding-models" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"minilm-l6\",\n \"description\": \"FastEmbed all-MiniLM-L6-v2\",\n \"provider\": \"FastEmbedEmbeddings\",\n \"model\": \"Qdrant/all-MiniLM-L6-v2-onnx\",\n \"size\": 0\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates an embedding model: a configured instance of an embedding provider, with a model name and provider parameters. Before storing the embedding model, Foundation4 embeds a test string with the provider, so the request fails when the provider cannot load the model. A `size` of 0 stores the measured number of dimensions, and a nonzero `size` must equal the measured number. After creation, only `name` and `description` can change.\n\n**Permissions.** Write on the `embedding-models` object type and write on the embedding provider that `provider` names.\n\nEmbedding models and text splitters shows example requests, and Providers and models lists the models and parameters of each provider." }, "response": [] }, { "name": "Get an embedding model", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/embedding-models/{{EMBEDDING_MODEL_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "embedding-models", "{{EMBEDDING_MODEL_ID}}" ] }, "description": "Returns one embedding model: the provider, the model name, the number of dimensions and the provider parameters.\n\n**Permissions.** Read on the embedding model." }, "response": [] }, { "name": "Update an embedding model", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/embedding-models/{{EMBEDDING_MODEL_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "embedding-models", "{{EMBEDDING_MODEL_ID}}" ] }, "body": { "mode": "raw", "raw": "{\n \"description\": \"FastEmbed all-MiniLM-L6-v2, 384 dimensions\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Changes the `name` or the `description` of an embedding model. Fields that the request omits keep their values, and `\"description\": null` removes the description. The provider, model name, size and parameters cannot change, and Foundation4 ignores these fields in the request. A different model or different parameters require a new embedding model.\n\n**Permissions.** Write on the embedding model." }, "response": [] }, { "name": "Delete an embedding model", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/embedding-models/{{EMBEDDING_MODEL_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "embedding-models", "{{EMBEDDING_MODEL_ID}}" ] }, "description": "Deletes an embedding model. An embedding model that a pipeline uses cannot be deleted: the request returns HTTP 409 until every pipeline that uses the embedding model is deleted.\n\n**Permissions.** Write on the embedding model." }, "response": [] }, { "name": "Embed a text with an embedding model", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/embedding-models/{{EMBEDDING_MODEL_ID}}/query", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "embedding-models", "{{EMBEDDING_MODEL_ID}}", "query" ] }, "body": { "mode": "raw", "raw": "{\n \"query\": \"How can finance export invoices?\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Converts one text into a vector with the embedding model and returns the vector. Client applications use this operation to test an embedding model. The vector has `size` numbers, one for each dimension of the embedding model. Foundation4 embeds the text as given, with no prefix or instruction. The first request for an embedding model on each API server instance loads the model.\n\n**Permissions.** Read and execute on the embedding model." }, "response": [] } ] }, { "name": "Text Splitters", "description": "Text splitters, which divide documents into fragments. Embedding models and text splitters describes the object type.", "item": [ { "name": "List text splitters", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/text-splitters", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "text-splitters" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Returns only the text splitter with this identifier." }, { "key": "provider", "value": "", "disabled": true, "description": "Returns only text splitters whose provider name equals this value, such as `RecursiveCharacterTextSplitter`. The match is case-sensitive." }, { "key": "provider$contains", "value": "", "disabled": true, "description": "Matches objects whose `provider` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "provider$startswith", "value": "", "disabled": true, "description": "Matches objects whose `provider` starts with the value." }, { "key": "description", "value": "", "disabled": true, "description": "Returns only text splitters whose description equals this value, case-sensitive." }, { "key": "description$contains", "value": "", "disabled": true, "description": "Matches objects whose `description` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "created_at", "value": "", "disabled": true, "description": "Returns only text splitters created at exactly this time, in RFC 3339 format." }, { "key": "created_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than the value." }, { "key": "created_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than the value." }, { "key": "created_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than or equal to the value." }, { "key": "created_at$le", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than or equal to the value." }, { "key": "updated_at", "value": "", "disabled": true, "description": "Returns only text splitters last changed at exactly this time, in RFC 3339 format." }, { "key": "updated_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than the value." }, { "key": "updated_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than the value." }, { "key": "updated_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than or equal to the value." }, { "key": "updated_at$le", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than or equal to the value." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `provider`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns a page of the text splitters that the key can read. Filters apply to the provider, the description and the timestamps. `order_by` accepts `id`, `created_at`, `updated_at` and `provider`. API conventions describes pagination, filters and ordering.\n\n**Permissions.** Read on the text splitters. The list contains only the text splitters that the key can read." }, "response": [] }, { "name": "Create a text splitter", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/text-splitters", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "text-splitters" ] }, "body": { "mode": "raw", "raw": "{\n \"provider\": \"RecursiveCharacterTextSplitter\",\n \"description\": \"1,000-character fragments with 200 characters of overlap\",\n \"parameters\": {\n \"chunk_size\": 1000,\n \"chunk_overlap\": 200\n }\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a text splitter: a configured instance of a text splitter provider, with parameters. A text splitter has no name, and a deployment can hold several text splitters of the same provider. Before storing the text splitter, Foundation4 splits a test string with the provider, so the request fails when the provider does not accept the parameters. After creation, only `description` can change.\n\n**Permissions.** Write on the `text-splitters` object type and write on the text splitter provider that `provider` names.\n\nEmbedding models and text splitters shows example requests, and Providers and models lists the parameters of each provider." }, "response": [] }, { "name": "Get a text splitter", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/text-splitters/{{TEXT_SPLITTER_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "text-splitters", "{{TEXT_SPLITTER_ID}}" ] }, "description": "Returns one text splitter: the provider and the parameters that Foundation4 passes to the provider.\n\n**Permissions.** Read on the text splitter." }, "response": [] }, { "name": "Update a text splitter", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/text-splitters/{{TEXT_SPLITTER_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "text-splitters", "{{TEXT_SPLITTER_ID}}" ] }, "body": { "mode": "raw", "raw": "{\n \"description\": \"Support articles: 1,000-character fragments with 200 characters of overlap\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Changes the `description` of a text splitter. `\"description\": null` removes the description, and an omitted field keeps the current description. The provider and the parameters cannot change, and Foundation4 ignores these fields in the request. Different parameters require a new text splitter.\n\n**Permissions.** Write on the text splitter." }, "response": [] }, { "name": "Delete a text splitter", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/text-splitters/{{TEXT_SPLITTER_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "text-splitters", "{{TEXT_SPLITTER_ID}}" ] }, "description": "Deletes a text splitter. A text splitter that is the default text splitter of a pipeline cannot be deleted: the request returns HTTP 409 until each such pipeline uses another default text splitter or is deleted.\n\n**Permissions.** Write on the text splitter." }, "response": [] } ] }, { "name": "Llms", "description": "Language models (LLMs) registered with Foundation4, direct queries to a model and the OpenAI-compatible chat completions endpoint. LLMs describes the object type and the response formats.", "item": [ { "name": "List LLMs", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/llms", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "llms" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Returns only the LLM with this identifier." }, { "key": "name", "value": "", "disabled": true, "description": "Returns only the LLM with exactly this name." }, { "key": "name$contains", "value": "", "disabled": true, "description": "Matches objects whose `name` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "name$startswith", "value": "", "disabled": true, "description": "Matches objects whose `name` starts with the value." }, { "key": "name$gt", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than the value." }, { "key": "name$ge", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than or equal to the value." }, { "key": "name$lt", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than the value." }, { "key": "name$le", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than or equal to the value." }, { "key": "description", "value": "", "disabled": true, "description": "Returns only LLMs with exactly this description." }, { "key": "description$contains", "value": "", "disabled": true, "description": "Matches objects whose `description` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "endpoint", "value": "", "disabled": true, "description": "Returns only LLMs with exactly this endpoint URL." }, { "key": "endpoint$contains", "value": "", "disabled": true, "description": "Matches objects whose `endpoint` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "created_at", "value": "", "disabled": true, "description": "Returns only LLMs created at exactly this time, as an RFC 3339 timestamp." }, { "key": "created_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than the value." }, { "key": "created_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than the value." }, { "key": "created_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than or equal to the value." }, { "key": "created_at$le", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than or equal to the value." }, { "key": "updated_at", "value": "", "disabled": true, "description": "Returns only LLMs last changed at exactly this time, as an RFC 3339 timestamp." }, { "key": "updated_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than the value." }, { "key": "updated_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than the value." }, { "key": "updated_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than or equal to the value." }, { "key": "updated_at$le", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than or equal to the value." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `name`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns one page of the LLM registrations that the key can read, in the list envelope. Query parameters filter the list by field values and set the order and the page. The list has no filter on the model name.\n\n**Permissions.** Read on the LLMs in the list. The list contains only the LLMs that the key can read, so a key without read permission on any LLM receives an empty list.\n\nAPI conventions describes pagination, filters and ordering." }, "response": [] }, { "name": "Register an LLM", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/llms", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "llms" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"internal-general\",\n \"description\": \"General-purpose model on the internal model server\",\n \"endpoint\": \"http://llm.internal:8000/v1\",\n \"model\": \"example-model-8b-instruct\",\n \"api_key\": \"change-me\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Registers a connection to a model server that exposes an OpenAI-compatible API. Foundation4 does not contact the model server during registration, so an incorrect endpoint or API key appears only when the LLM is first used. Foundation4 encrypts the API key before storage, and no response returns the key.\n\n**Permissions.** Write on the LLM object type (`llms`).\n\nLLMs describes the fields of a registration and the requirements on the model server." }, "response": [] }, { "name": "Get an LLM", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/llms/{{LLM_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "llms", "{{LLM_ID}}" ] }, "description": "Returns the registration of one LLM. The response never contains the API key of the registration.\n\n**Permissions.** Read on the LLM.\n\nLLMs describes the fields of an LLM registration." }, "response": [] }, { "name": "Update an LLM", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/llms/{{LLM_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "llms", "{{LLM_ID}}" ] }, "body": { "mode": "raw", "raw": "{\n \"model\": \"example-model-70b-instruct\",\n \"api_key\": \"change-me\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Changes the fields of an LLM registration that the request names, and keeps the stored value of every omitted field. A `null` value clears `description` or `api_key`, and a new `api_key` value replaces the stored key. Foundation4 does not contact the model server during the update.\n\n**Permissions.** Write on the LLM.\n\nLLMs describes the fields of a registration." }, "response": [] }, { "name": "Delete an LLM", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/llms/{{LLM_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "llms", "{{LLM_ID}}" ] }, "description": "Deletes an LLM registration. Agents store no LLM, so the deletion changes no agent. Agent executions and queries that name the deleted LLM then return HTTP 404.\n\n**Permissions.** Write on the LLM." }, "response": [] }, { "name": "Query an LLM", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/llms/{{LLM_ID}}/query", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "llms", "{{LLM_ID}}", "query" ] }, "body": { "mode": "raw", "raw": "{\n \"query\": \"In one sentence, what is a text splitter?\",\n \"stream\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Sends `query` to the LLM as a single user message, without a system message or retrieval, and returns the generated answer. The `stream` field selects the response format: newline-delimited JSON (NDJSON) by default, server-sent events with `\"sse\"` or plain text with `false`. The direct query calls the Responses API of the model server, so the LLM registration requires an API key.\n\n**Permissions.** Execute on the LLM.\n\nResponse formats describes the three formats, and API conventions describes how a model server failure appears in each format." }, "response": [] }, { "name": "Relay a chat completion", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "x-llm-id", "value": "{{LLM_ID}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/openai/v1/chat/completions", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "openai", "v1", "chat", "completions" ] }, "body": { "mode": "raw", "raw": "{\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": \"Answer in one sentence.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"What is retrieval-augmented generation?\"\n }\n ],\n \"temperature\": 0.2\n}", "options": { "raw": { "language": "json" } } }, "description": "Relays an OpenAI chat completion request to the chat completions API of the LLM named in the `x-llm-id` header. Foundation4 forwards the body unchanged, inserts the registered model name when the body has no `model` field and sends the API key of the registration, when the registration has one, as a bearer token. Foundation4 returns the model server's status and body, including error responses, and performs no retrieval, prompt templating or tracing.\n\n**Permissions.** Execute on the LLM.\n\nLLMs describes the endpoint." }, "response": [] } ] }, { "name": "Agents", "description": "Agents, the prompts that agents build, retrieval without generation, execution and execution traces. Agents and prompt templates describes agents.", "item": [ { "name": "List agents", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/agents", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "agents" ], "query": [ { "key": "id", "value": "", "disabled": true, "description": "Returns only the agent with this identifier." }, { "key": "name", "value": "", "disabled": true, "description": "Returns only the agent with exactly this name." }, { "key": "name$contains", "value": "", "disabled": true, "description": "Matches objects whose `name` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "name$startswith", "value": "", "disabled": true, "description": "Matches objects whose `name` starts with the value." }, { "key": "name$gt", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than the value." }, { "key": "name$ge", "value": "", "disabled": true, "description": "Matches objects whose `name` is greater than or equal to the value." }, { "key": "name$lt", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than the value." }, { "key": "name$le", "value": "", "disabled": true, "description": "Matches objects whose `name` is less than or equal to the value." }, { "key": "description", "value": "", "disabled": true, "description": "Returns only agents with exactly this description." }, { "key": "description$contains", "value": "", "disabled": true, "description": "Matches objects whose `description` contains the value, case-sensitive. Repeat the parameter to require several values." }, { "key": "created_at", "value": "", "disabled": true, "description": "Returns only agents created at exactly this time, as an RFC 3339 timestamp." }, { "key": "created_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than the value." }, { "key": "created_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than the value." }, { "key": "created_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is greater than or equal to the value." }, { "key": "created_at$le", "value": "", "disabled": true, "description": "Matches objects whose `created_at` is less than or equal to the value." }, { "key": "updated_at", "value": "", "disabled": true, "description": "Returns only agents last changed at exactly this time, as an RFC 3339 timestamp." }, { "key": "updated_at$gt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than the value." }, { "key": "updated_at$lt", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than the value." }, { "key": "updated_at$ge", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is greater than or equal to the value." }, { "key": "updated_at$le", "value": "", "disabled": true, "description": "Matches objects whose `updated_at` is less than or equal to the value." }, { "key": "first", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return from the start of the list, or after the `after` cursor." }, { "key": "after", "value": "", "disabled": true, "description": "Cursor mode: the cursor after which the page starts, taken from `page_info.after` of the previous page." }, { "key": "last", "value": "", "disabled": true, "description": "Cursor mode: the number of objects to return before the `before` cursor." }, { "key": "before", "value": "", "disabled": true, "description": "Cursor mode: the cursor before which the page ends, taken from `page_info.before`." }, { "key": "limit", "value": "", "disabled": true, "description": "Offset mode: the number of objects to return. The default page size is 25." }, { "key": "offset", "value": "", "disabled": true, "description": "Offset mode: the number of objects to skip." }, { "key": "count", "value": "", "disabled": true, "description": "When `true`, adds `page_info.count`, the total number of matching objects." }, { "key": "order_by", "value": "", "disabled": true, "description": "Sort fields: `id`, `created_at`, `updated_at`, `name`. A `-` prefix sorts in descending order. A field name alone sorts in ascending order, as does a `+` prefix sent encoded as `%2B`. Repeat the parameter to sort by several fields. The default order is `id` ascending." } ] }, "description": "Returns one page of the agents that the key can read, in the list envelope. Query parameters filter the list by field values and set the order and the page.\n\n**Permissions.** Read on the agents in the list. The list contains only the agents that the key can read, so a key without read permission on any agent receives an empty list.\n\nAPI conventions describes pagination, filters and ordering." }, "response": [] }, { "name": "Create an agent", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/agents", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "agents" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"support-answers\",\n \"description\": \"Answers support questions from the product knowledge base\",\n \"prompt\": [\n {\n \"role\": \"system\",\n \"template\": \"Answer using only the reference text. If the reference text does not contain the answer, say that the answer is not available.\"\n },\n {\n \"role\": \"user\",\n \"template\": \"Reference text:\\n{context}\\n\\nQuestion: {question}\"\n }\n ],\n \"placeholders\": [\n {\n \"name\": \"question\",\n \"type\": \"query\"\n },\n {\n \"name\": \"context\",\n \"type\": \"similarity\",\n \"target\": \"question\",\n \"params\": {\n \"k\": 5\n }\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates an agent from a prompt template and the placeholders that the template uses. Foundation4 validates the definition before storing the agent: the prompt contains at least one `system` message and one `user` message, the last message is a `user` message, every name in braces is a placeholder of the agent and every retrieval placeholder targets a `query` placeholder. Agent executions run `query`, `similarity` and `mmr` placeholders.\n\n**Permissions.** Write on the agent object type (`agents`).\n\nAgents and prompt templates describes prompt templates and placeholders." }, "response": [] }, { "name": "Get an agent", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/agents/{{AGENT_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "agents", "{{AGENT_ID}}" ] }, "description": "Returns the stored definition of an agent: the prompt template, the placeholders and the metadata. An agent stores no pipeline and no LLM, because each execution names both.\n\n**Permissions.** Read on the agent.\n\nAgents and prompt templates describes the agent definition." }, "response": [] }, { "name": "Update an agent", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/agents/{{AGENT_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "agents", "{{AGENT_ID}}" ] }, "body": { "mode": "raw", "raw": "{\n \"description\": \"Answers support questions from the product and billing knowledge base\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Changes the fields of an agent that the request names, and keeps the stored value of every omitted field. `prompt`, `placeholders` and `metadata` replace the stored values whole, and `description` accepts `null` to clear the description. Foundation4 validates the resulting prompt template and placeholders with the rules of agent creation, including stored values that the request leaves unchanged.\n\n**Permissions.** Write on the agent.\n\nAgents and prompt templates describes prompt templates and placeholders." }, "response": [] }, { "name": "Delete an agent", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/agents/{{AGENT_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "agents", "{{AGENT_ID}}" ] }, "description": "Deletes an agent. Executions that name the deleted agent then return HTTP 404.\n\n**Permissions.** Write on the agent." }, "response": [] }, { "name": "Execute an agent", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "x-pipeline-id", "value": "{{PIPELINE_ID}}" }, { "key": "x-llm-id", "value": "{{LLM_ID}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/agents/{{AGENT_ID}}/execute", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "agents", "{{AGENT_ID}}", "execute" ] }, "body": { "mode": "raw", "raw": "{\n \"prompt\": {\n \"question\": \"How can finance export invoices?\"\n },\n \"classification\": \"internal\",\n \"stream\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Runs an agent: retrieves fragments for the retrieval placeholders from the pipeline named in `x-pipeline-id`, inserts the input values and the fragment text into the prompt template, and sends the messages to the LLM named in `x-llm-id`. The `stream` field selects the response format: newline-delimited JSON (NDJSON) by default, server-sent events with `\"sse\"` or plain text with `false`. With `tracing` set to `true`, Foundation4 records a trace for 60 minutes and returns the trace identifier in the `x-foundation4ai-tracing-id` response header.\n\n**Permissions.** Execute on the agent, the pipeline and the LLM.\n\nAgents and prompt templates describes execution, and LLMs describes the requirements on the model server and the response formats." }, "response": [] }, { "name": "Get the prompt of an agent", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/agents/{{AGENT_ID}}/prompt", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "agents", "{{AGENT_ID}}", "prompt" ] }, "description": "Returns the prompt template and the placeholders of an agent as stored, without substitution, and `input_variables`: the names of the `query` placeholders whose values each execution supplies in `prompt`.\n\n**Permissions.** Read on the agent.\n\nAgents and prompt templates describes the tools for testing an agent." }, "response": [] }, { "name": "Run an agent retrieval dry run", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" }, { "key": "x-pipeline-id", "value": "{{PIPELINE_ID}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{FOUNDATION4_URL}}/agents/{{AGENT_ID}}/search", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "agents", "{{AGENT_ID}}", "search" ] }, "body": { "mode": "raw", "raw": "{\n \"prompt\": {\n \"question\": \"How can finance export invoices?\"\n },\n \"classification\": \"internal\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Runs the retrieval placeholders of an agent against the pipeline named in the `x-pipeline-id` header, without calling an LLM, and returns the fragments that each retrieval placeholder retrieves. The body takes the `prompt`, `classification` and `filters` fields of an agent execution. A client application uses the dry run to test the placeholders, filters and classifications of an agent.\n\n**Permissions.** Execute on the agent and on the pipeline.\n\nAgents and prompt templates describes retrieval placeholders, and Filter operators describes the filter language." }, "response": [] }, { "name": "Get an execution trace", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{FOUNDATION4_API_KEY}}" }, { "key": "x-api-key-secret", "value": "{{FOUNDATION4_API_SECRET}}" } ], "url": { "raw": "{{FOUNDATION4_URL}}/tracing/{{EXECUTION_ID}}", "host": [ "{{FOUNDATION4_URL}}" ], "path": [ "tracing", "{{EXECUTION_ID}}" ] }, "description": "Returns the trace of an agent execution that ran with `tracing` set to `true`: the input values, the fragments that each retrieval placeholder retrieved and the messages as sent to the LLM. The trace does not contain the answer, and Foundation4 keeps a trace for 60 minutes after the execution.\n\n**Permissions.** None on an object. Only the API key that ran the execution can read the trace.\n\nAgents and prompt templates describes tracing." }, "response": [] } ] } ], "variable": [ { "key": "FOUNDATION4_URL", "value": "http://localhost:8080" }, { "key": "FOUNDATION4_API_KEY", "value": "" }, { "key": "FOUNDATION4_API_SECRET", "value": "" }, { "key": "AGENT_ID", "value": "" }, { "key": "API_KEY_ID", "value": "" }, { "key": "DOCUMENT_ID", "value": "" }, { "key": "EMBEDDING_MODEL_ID", "value": "" }, { "key": "EMBEDDING_PROVIDER_ID", "value": "" }, { "key": "ENTRY_ID", "value": "" }, { "key": "EXECUTION_ID", "value": "" }, { "key": "FRAGMENT_ID", "value": "" }, { "key": "ID", "value": "" }, { "key": "INDEX_ID", "value": "" }, { "key": "LLM_ID", "value": "" }, { "key": "OBJECT_ID", "value": "" }, { "key": "OBJECT_TYPE", "value": "" }, { "key": "PIPELINE_ID", "value": "" }, { "key": "TAXONOMY_ID", "value": "" }, { "key": "TEXT_SPLITTER_ID", "value": "" }, { "key": "TEXT_SPLITTER_PROVIDER_ID", "value": "" } ] }