Aleph Alpha Filter Index API

openapi: 3.2.0
info:
  title: Aleph Alpha Document Index Filter Index API
  version: 0.0.0
  description: 'The Document Index is a service that provides semantic search over your knowledge base. It

    takes care of the chunking and embedding of your documents, and it keeps these embeddings in

    sync when your documents change.

    '
  contact:
    email: support@aleph-alpha.com
servers:
- url: '{host}/v1/studio/search'
  variables:
    host:
      default: https://api.pharia.example.com
tags:
- name: Filter Index
  description: Management of search filter indexes
paths:
  /filter_indexes/{namespace}:
    get:
      tags:
      - Filter Index
      security:
      - token: []
      summary: List of filter index configurations in namespace.
      description: List all filter index configurations that exist in the given namespace.
      parameters:
      - $ref: '#/components/parameters/namespace'
      responses:
        '200':
          description: A list of filter index config names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - filter-index-config-1
                - filter-index-config-2
  /filter_indexes/{namespace}/{filterIndex}:
    get:
      tags:
      - Filter Index
      security:
      - token: []
      summary: Get namespace-wide filter index configuration.
      description: Gets the parameters for the given filter index configuration.
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/filterIndex'
      responses:
        '200':
          description: A filter index config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/filterIndexConfig'
              example:
                field_name: a.nested.field
                field_type: string
    put:
      tags:
      - Filter Index
      security:
      - token: []
      summary: Define a namespace-wide filter index configuration.
      description: 'Defines a namespace-wide filter index configuration. Once a configuration is defined it can be assigned

        to indexes that are assigned to a collections of the namespace which then allows to filter searches on this index

        based on the field defined in the configuration.

        '
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/filterIndex'
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/filterIndexConfig'
            example:
              field_name: a.nested.field
              field_type: string
      responses:
        '200':
          description: No content
    delete:
      tags:
      - Filter Index
      security:
      - token: []
      summary: Delete a namespace-wide filter index configuration.
      description: 'Deletes the filter index configuration for the given namespace. This is not possible if the filter index

        is added to any assigned index.

        '
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/filterIndex'
      responses:
        '200':
          description: Filter index configuration successfully deleted.
        '409':
          description: The filter index configuration cannot be deleted because it is used.
  /collections/{namespace}/{collection}/indexes/{index}/filter_indexes:
    get:
      tags:
      - Filter Index
      security:
      - token: []
      summary: Gets the filter indexes assigned to an assigned (search) index.
      description: 'Gets the filter indexes assigned to an assigned (search) index. Searches on the assigned

        index can use these filter indexes.

        '
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/collection'
      - $ref: '#/components/parameters/index'
      responses:
        '200':
          description: A list of filter index names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - filter_index_1
                - filter_index_2
  /collections/{namespace}/{collection}/indexes/{index}/filter_indexes/{filterIndex}:
    put:
      tags:
      - Filter Index
      security:
      - token: []
      summary: Assign an existing filter index config to an assigned (search) index.
      description: 'Assigns a filter index config that exists in the same namespace as the collection to an

        index assigned to the collection. This allows you to filter results from searches over the

        search index.

        '
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/collection'
      - $ref: '#/components/parameters/index'
      - $ref: '#/components/parameters/filterIndex'
      responses:
        '200':
          description: Filter index successfully assigned.
    delete:
      tags:
      - Filter Index
      security:
      - token: []
      summary: Unassigns a filter index config from an assigned (search) index.
      description: 'Unassigns a filter index config from an assigned (search) index. Subsequent searches on the

        index will no longer be able to use the filter.

        '
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/collection'
      - $ref: '#/components/parameters/index'
      - $ref: '#/components/parameters/filterIndex'
      responses:
        '200':
          description: Filter index successfully unassigned.
components:
  parameters:
    collection:
      description: 'Collection containing documents. A search/lookup request always refers to a single collection, i.e.

        only a single collection can be searched with a single search/lookup request. The name of the collection

        must be unique within a namespace.

        Collections may only contain alphanumeric characters (a-z, A-Z, -, . and 0-9) and cannot be longer

        then 100 characters.

        '
      name: collection
      in: path
      schema:
        type: string
        maxLength: '100'
        pattern: ^[a-zA-Z0-9\-\.]+$
      required: 'true'
      example: wikipedia-de
    namespace:
      description: 'Namespace for collections of documents. Namespaces support preventing naming conflicts

        for collections. A namespace typically corresponds to an organisation.

        Namespaces may only contain alphanumeric characters (a-z, A-Z, -, . and 0-9) and

        cannot be longer than 100 characters.

        '
      name: namespace
      in: path
      schema:
        type: string
        maxLength: '100'
        pattern: ^[a-zA-Z0-9\-\.]+$
      required: 'true'
      example: aleph-alpha
    filterIndex:
      description: 'Filter index for an index assigned to a collection. Filter indexes are used to allow

        filtering of results when searching on documents in a collection. An filter index name

        can only contain alphanumeric characters (a-z, A-Z, -, . and 0-9) and cannot be longer

        than 50 characters.

        '
      name: filterIndex
      in: path
      schema:
        type: string
        maxLength: '50'
        pattern: ^[a-zA-Z0-9\-\.]+$
      required: 'true'
      example: creation-date
    index:
      description: 'Index for a collection. Indexes are used for search operations on documents in collections.

        An index name may only contain alphanumeric characters (a-z, A-Z, -, . and 0-9) and cannot

        be longer than 50 characters.

        '
      name: index
      in: path
      schema:
        type: string
        maxLength: '50'
        pattern: ^[a-zA-Z0-9\-\.]+$
      required: 'true'
      example: asymmetric
  schemas:
    filterIndexConfig:
      description: 'Represents the configuration parameters for a filter index. Filter indexes can be used to filter search

        results based on the metadata field defined in the configuration.

        '
      type: object
      properties:
        field_name:
          $ref: '#/components/schemas/metadataFilterField'
        field_type:
          type: string
          enum:
          - string
          - integer
          - float
          - boolean
          - date_time
    metadataFilterField:
      description: 'The metadata field on which to filter search results. Field names must only contain alphanumeric characters,

        dashes and underscores. Nested fields can be specified using dot notation (e.g. ''a.b'').

        Array-valued fields can either use a wildcard specifier (e.g. ''a[].b'') or a specific index (e.g. ''a[1].b'').

        The maximum length of the field name is 1000 characters.

        '
      type: string
      maxLength: '1000'
      pattern: ^([[:alnum:]\-_]+(\[[[:digit:]]{0,5}\])*\.)*[[:alnum:]\-_]+$
  securitySchemes:
    token:
      type: http
      scheme: bearer
      description: Can be generated in your [Aleph Alpha profile](https://app.aleph-alpha.com/profile)