The Document Index is a service that provides semantic search over your knowledge base. It handles chunking and embedding of documents and keeps embeddings in sync, and exposes namespaces, collections, documents, indexes and filter indexes for hybrid semantic and keyword retrieval.
{
"openapi": "3.1.0",
"info": {
"title": "Aleph Alpha Document Index API",
"version": "0.0.0",
"description": "The Document Index is a service that provides semantic search over your knowledge base. It\ntakes care of the chunking and embedding of your documents, and it keeps these embeddings in\nsync when your documents change.\n",
"contact": {
"email": "support@aleph-alpha.com"
}
},
"components": {
"securitySchemes": {
"token": {
"type": "http",
"scheme": "bearer",
"description": "Can be generated in your [Aleph Alpha profile](https://app.aleph-alpha.com/profile)"
}
},
"schemas": {
"searchQueryParameters": {
"description": "The parameters for finding document sections within a collection based on a semantic search.\n",
"type": "object",
"properties": {
"query": {
"$ref": "#/components/schemas/query"
},
"max_results": {
"type": "integer",
"description": "Maximum number of found documents to return. Default 1."
},
"min_score": {
"type": "number",
"format": "float",
"description": "Filter out results with a cosine similarity score below this value. Scores range from -1 to 1.\nFor searches on hybrid indexes, the Document Index applies the min_score to the semantic results\nbefore fusion of result sets. As fusion re-scores results, returned scores may exceed this value.\n"
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/filter"
},
"description": "A filter for search results that restricts the results to those document sections that match the filter criteria.\nThe individual conditions of this array are AND-combined (i.e. all conditions must match). This can for example be\nused to restrict the returned sections based on their modality (i.e. image or text), or on their metadata.\n"
}
},
"required": [
"query"
]
},
"queryResult": {
"description": "The result for semantic document search.\nAn array of document names and content of the found documents in the given collection.\n",
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/documentSection"
},
{
"type": "object",
"properties": {
"score": {
"type": "number",
"format": "float",
"description": "Search score of the found section, where a higher score indicates a closer match.\nWill be between -1 and 1. A score closer to -1 indicates the section opposes the\nquery. A score close 0 suggests the section is unrelated to the query. A score\nclose to 1 suggests the section is related to the query. The score depends on\nthe index configuration, e.g. the score of a section differs for hybrid and\nnon-hybrid indexes. For searches on hybrid indexes, the score can exceed the\nmin_score of the query as the min_score only applies to the semantic similarity\nsub-query.\n"
}
}
}
]
}
},
"transitioningResult": {
"description": "The result for a transitioning documents query.\n",
"type": "object",
"properties": {
"currently_embedding": {
"type": "integer"
},
"currently_archiving": {
"type": "integer"
}
},
"required": [
"currently_embedding",
"currently_archiving"
]
},
"textCursor": {
"description": "A position within a document. The cursor is always inclusive of the current position, in both start and end positions.\n",
"type": "object",
"properties": {
"modality": {
"type": "string",
"enum": [
"text"
]
},
"item": {
"type": "integer",
"description": "Index of the item in the document"
},
"position": {
"type": "integer",
"description": "The character position the cursor can be found at within the string."
}
}
},
"imageCursor": {
"description": "A position within a document. The cursor is always inclusive of the current position, in both start and end positions.\n",
"type": "object",
"properties": {
"modality": {
"type": "string",
"enum": [
"image"
]
},
"item": {
"type": "integer",
"description": "Index of the item in the document"
}
}
},
"documentInformation": {
"description": "Information about a document",
"type": "object",
"properties": {
"path": {
"$ref": "#/components/schemas/documentPath"
},
"created": {
"type": "string",
"format": "date-time"
},
"version": {
"type": "integer",
"minimum": "1"
}
}
},
"documentSection": {
"description": "A section of a document.\n",
"type": "object",
"properties": {
"path": {
"$ref": "#/components/schemas/documentPath"
},
"section": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/text"
},
{
"$ref": "#/components/schemas/image"
}
]
}
},
"start": {
"oneOf": [
{
"$ref": "#/components/schemas/textCursor"
},
{
"$ref": "#/components/schemas/imageCursor"
}
]
},
"end": {
"description": "Inclusive cursor. The section of the document includes whatever is at this position",
"oneOf": [
{
"$ref": "#/components/schemas/textCursor"
},
{
"$ref": "#/components/schemas/imageCursor"
}
]
}
}
},
"documentVersion": {
"description": "The version of a document with the creation timestamp.\n",
"type": "object",
"properties": {
"version": {
"type": "integer"
},
"created_timestamp": {
"type": "string",
"format": "date-time"
},
"archived_timestamp": {
"type": "string",
"format": "date-time"
}
}
},
"documentPath": {
"description": "The path to a document. A path uniquely identifies a document among all managed documents.",
"type": "object",
"properties": {
"name": {
"description": "Name of the document. The name is unique within a collection.",
"type": "string",
"maxLength": "512"
},
"collection": {
"description": "Collection containing documents. The name of the collection must be unique within a namespace.\n",
"type": "string",
"maxLength": "100"
},
"namespace": {
"description": "Namespace for collections of documents. Namespaces support preventing naming conflicts\nfor collections. A namespace typically corresponds to an organisation.\n",
"type": "string",
"maxLength": "100"
}
}
},
"document": {
"description": "Represents a document. The actual content of the document is an array of text and image elements.\nThe version field allow to evolve the schema. The documentation here describes only the most recent version.\n",
"type": "object",
"properties": {
"schema_version": {
"type": "string",
"enum": [
"V1"
]
},
"contents": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/text"
},
{
"$ref": "#/components/schemas/image"
}
]
}
},
"metadata": {
"description": "Store any metadata about the document. Accepts any valid JSON. You can filter search\nresults based on these metadata fields using filter indexes.\n"
}
},
"required": [
"schema_version",
"content"
]
},
"indexConfig": {
"description": "Represents the configuration of an index. You can assign indexes to collections and use them\nfor efficient content-based searching.\n",
"type": "object",
"required": [
"chunk_size"
],
"properties": {
"chunk_size": {
"type": "integer",
"minimum": "1",
"maximum": "2046",
"description": "The Document Index chunks documents before embedding them. This field specifies\nthe maximum number of tokens in a chunk. Chunking adheres to semantic boundaries where\npossible.\n"
},
"chunk_overlap": {
"type": "integer",
"minimum": "0",
"maximum": "2045",
"default": "0",
"description": "The Document Index chunks documents before embedding them. This field specifies the\nmaximum number of tokens of overlap between consecutive chunks. Chunking adheres to\nsemantic boundaries where possible.\n"
},
"embedding_type": {
"type": "string",
"enum": [
"symmetric",
"asymmetric"
],
"deprecated": "true",
"description": "The embedding representation to embed with. This field is deprecated and will be\nremoved in a future version. Use the `embedding` field with the `semantic_embed`\nstrategy instead. Note: for backwards compatibility, the Document Index will always\nreturn this field. For cases where a value for it is not applicable (e.g., with the\n`instructable_embed` embedding strategy, it will return `asymmetric`.\n"
},
"hybrid_index": {
"type": "string",
"enum": [
"bm25"
],
"description": "If set, the Document Index will maintain a hybrid (i.e. semantic and keyword) index.\nSearches on this index will query both semantic and keyword indexes, combining results\nwith Reciprocal Rank Fusion (RRF).\n"
},
"embedding": {
"type": "object",
"description": "The embedding configuration, i.e., how to embed chunks of documents in the index. You\nmust specify this field (recommended), or the `embedding_type` field (deprecated).\n",
"oneOf": [
{
"type": "object",
"description": "Semantic embed. This is the standard way to embed documents.\n",
"required": [
"strategy",
"model_name",
"representation"
],
"properties": {
"strategy": {
"type": "string",
"enum": [
"semantic_embed"
]
},
"model_name": {
"type": "string",
"description": "The name of the model to use for embedding."
},
"representation": {
"type": "string",
"enum": [
"symmetric",
"asymmetric"
],
"description": "The representation to use for embedding.\nUse \"symmetric\" when the queries and documents are the same, e.g., for classification tasks.\nUse \"asymmetric\" when the queries and documents are different, e.g., for search tasks.\nFor more details about the difference between symmetric and asymmetric semantic embeddings,\nsee our blog post: https://www.aleph-alpha.com/luminous-explore-a-model-for-world-class-semantic-representation\n"
}
}
},
{
"type": "object",
"description": "Instructable embed. This lets you prompt embedding models with custom instructions\nfor queries and documents. Steering the model like this can help the model\nunderstand nuances of your specific data and ultimately lead to embeddings that are\nmore useful for your use-case.\n",
"required": [
"strategy",
"model_name"
],
"properties": {
"strategy": {
"type": "string",
"enum": [
"instructable_embed"
]
},
"model_name": {
"type": "string",
"description": "The name of the model to use for embedding."
},
"query_instruction": {
"type": "string",
"description": "The instruction to use for embedding queries."
},
"document_instruction": {
"type": "string",
"description": "The instruction to use for embedding document chunks."
}
}
}
]
}
}
},
"filterIndexConfig": {
"description": "Represents the configuration parameters for a filter index. Filter indexes can be used to filter search\nresults based on the metadata field defined in the configuration.\n",
"type": "object",
"properties": {
"field_name": {
"$ref": "#/components/schemas/metadataFilterField"
},
"field_type": {
"type": "string",
"enum": [
"string",
"integer",
"float",
"boolean",
"date_time"
]
}
}
},
"filter": {
"description": "A logical combination of filter conditions.\n",
"type": "object",
"oneOf": [
{
"type": "object",
"description": "Logical conjunction, i.e. forms the predicate \"filterCondition1 AND filterCondition2 AND ...\"",
"properties": {
"with": {
"$ref": "#/components/schemas/filterConditions"
}
}
},
{
"type": "object",
"description": "Logical conjunction of negations, i.e. forms the predicate \"(NOT filterCondition1) AND (NOT filterCondition2) AND ...\"",
"properties": {
"without": {
"$ref": "#/components/schemas/filterConditions"
}
}
},
{
"type": "object",
"description": "Logical disjunction, i.e. forms the predicate \"filterCondition1 OR filterCondition2 OR ...\"",
"properties": {
"withOneOf": {
"$ref": "#/components/schemas/filterConditions"
}
}
}
]
},
"filterConditions": {
"type": "array",
"description": "A collection of filter conditions that are combined according to the parent filter combinator.\n",
"items": {
"oneOf": [
{
"type": "object",
"description": "Matches sections that have at least one item with the given modality.\n",
"properties": {
"modality": {
"type": "string",
"enum": [
"text",
"image"
]
}
}
},
{
"type": "object",
"description": "Matches sections whose metadata fields match the given condition. You must specify the field, and can only specify\na single condition.\n",
"properties": {
"metadata": {
"type": "object",
"required": [
"field"
],
"properties": {
"field": {
"$ref": "#/components/schemas/metadataFilterField"
},
"greater_than": {
"type": "number",
"format": "double"
},
"greater_than_or_equal_to": {
"type": "number",
"format": "double"
},
"less_than": {
"type": "number",
"format": "double"
},
"less_than_or_equal_to": {
"type": "number",
"format": "double"
},
"after": {
"type": "string",
"format": "date-time"
},
"at_or_after": {
"type": "string",
"format": "date-time"
},
"before": {
"type": "string",
"format": "date-time"
},
"at_or_before": {
"type": "string",
"format": "date-time"
},
"equal_to": {
"type": [
"string",
"integer",
"boolean"
]
},
"is_null": {
"type": "boolean",
"description": "This condition matches all metadata fields with a value of null.\nThe only allowed value for this condition is true.\n"
}
},
"oneOf": [
{
"required": [
"greater_than"
]
},
{
"required": [
"greater_than_or_equal_to"
]
},
{
"required": [
"less_than"
]
},
{
"required": [
"less_than_or_equal_to"
]
},
{
"required": [
"after"
]
},
{
"required": [
"at_or_after"
]
},
{
"required": [
"before"
]
},
{
"required": [
"at_or_before"
]
},
{
"required": [
"equal_to"
]
},
{
"required": [
"is_null"
]
}
]
}
}
}
]
}
},
"metadataFilterField": {
"description": "The metadata field on which to filter search results. Field names must only contain alphanumeric characters,\ndashes and underscores. Nested fields can be specified using dot notation (e.g. 'a.b').\nArray-valued fields can either use a wildcard specifier (e.g. 'a[].b') or a specific index (e.g. 'a[1].b').\nThe maximum length of the field name is 1000 characters.\n",
"type": "string",
"maxLength": "1000",
"pattern": "^([[:alnum:]\\-_]+(\\[[[:digit:]]{0,5}\\])*\\.)*[[:alnum:]\\-_]+$"
},
"query": {
"description": "Represents a query as is an array of text and image elements.\n",
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/text"
},
{
"$ref": "#/components/schemas/image"
}
]
}
},
"text": {
"description": "Represent a single piece of continuous text. The modality must always be 'text'.",
"type": "object",
"properties": {
"modality": {
"type": "string",
"enum": [
"text"
]
},
"text": {
"type": "string"
}
},
"required": [
"modality",
"text"
]
},
"image": {
"description": "Image data as base64-encoded bytes. Supperted types are PNG, JPG, GIF, BMP, WEBP.",
"type": "object",
"properties": {
"modality": {
"type": "string",
"enum": [
"image"
]
},
"bytes": {
"type": "string"
}
},
"required": [
"modality",
"bytes"
]
}
},
"parameters": {
"namespace": {
"description": "Namespace for collections of documents. Namespaces support preventing naming conflicts\nfor collections. A namespace typically corresponds to an organisation.\nNamespaces may only contain alphanumeric characters (a-z, A-Z, -, . and 0-9) and\ncannot be longer than 100 characters.\n",
"name": "namespace",
"in": "path",
"schema": {
"type": "string",
"maxLength": "100",
"pattern": "^[a-zA-Z0-9\\-\\.]+$"
},
"required": "true",
"example": "aleph-alpha"
},
"collection": {
"description": "Collection containing documents. A search/lookup request always refers to a single collection, i.e.\nonly a single collection can be searched with a single search/lookup request. The name of the collection\nmust be unique within a namespace.\nCollections may only contain alphanumeric characters (a-z, A-Z, -, . and 0-9) and cannot be longer\nthen 100 characters.\n",
"name": "collection",
"in": "path",
"schema": {
"type": "string",
"maxLength": "100",
"pattern": "^[a-zA-Z0-9\\-\\.]+$"
},
"required": "true",
"example": "wikipedia-de"
},
"name": {
"description": "Name of the document. The name must be unique within a collection and should not exceed 512 characters.\n",
"name": "name",
"in": "path",
"schema": {
"type": "string",
"maxLength": "512"
},
"required": "true",
"example": "Climate_change"
},
"version": {
"description": "Which version of the document to retrieve.",
"name": "version",
"in": "path",
"schema": {
"type": "integer"
},
"required": "true",
"example": "1"
},
"index": {
"description": "Index for a collection. Indexes are used for search operations on documents in collections.\nAn index name may only contain alphanumeric characters (a-z, A-Z, -, . and 0-9) and cannot\nbe longer than 50 characters.\n",
"name": "index",
"in": "path",
"schema": {
"type": "string",
"maxLength": "50",
"pattern": "^[a-zA-Z0-9\\-\\.]+$"
},
"required": "true",
"example": "asymmetric"
},
"filterIndex": {
"description": "Filter index for an index assigned to a co
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aleph-alpha/refs/heads/main/openapi/aleph-alpha-pharia-search-openapi.json
This is an independent, third-party profile of PhariaSearch / Document Index API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.