API Reference

You can get a token from here and try out our API.

Health

GEThttps://api.colivara.com/v1/health/

Response

200

OK

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/health/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

First Tab

search sends a query to the server, specifying which collection to search within, the number of top results to return, and optional filters to refine the search. It returns the most relevant results based on the given parameters.

Second Tab

• query (str): The main search string used to find similar documents or pages.

• collection_name (str, optional): Specifies which collection to search in. The default value is "all", meaning it searches across all collections.

• top_k (int, optional): Limits the number of results returned. Defaults to 3, returning the top three matches.

• query_filter (Optional[Dict[str, Any]], optional): An optional dictionary to filter results based on specific criteria. This dictionary can include:

  • on: Specifies the filter target, either "document" or "collection".

  • key: Key(s) to filter by; can be a string or a list of strings.

  • value: The value(s) the key(s) should match; could be a string, integer, float, or boolean.

  • lookup: Specifies how to match the filter criteria, with options like "key_lookup", "contains", "contained_by", "has_key", "has_keys", or "has_any_keys".

Untitled

afasd

List Collections

Endpoint to list collections.

This endpoint retrieves a list of collections owned by the authenticated user.

Args: request: The request object containing authentication information.

Returns: A list of CollectionOut objects representing the collections owned by the authenticated user.

Raises: HTTPException: If there is an issue with the request or authentication.

GEThttps://api.colivara.com/v1/collections/

Authorization

Bearer

Response

200

OK

Body

application/json

id*Id

name*Name

metadata*Metadata

num_documents*Num Documents

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/collections/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

[
  {
    "name": "text"
  }
]

Get Collection

Retrieve a collection by its name.

Args: request: The request object containing authentication information. collection_name (str): The name of the collection to retrieve.

Returns: CollectionOut: The retrieved collection with its ID, name, and metadata.

Raises: HTTPException: If the collection is not found or the user is not authorized to access it.

Endpoint: GET /collections/{collection_name}

Tags: collections

Authentication: Bearer token required.

GEThttps://api.colivara.com/v1/collections/{collection_name}/

Authorization

Bearer

Path parameters

collection_name*Collection Name

Response

200404

OK

Body

application/json

id*Id

name*Name

metadata*Metadata

num_documents*Num Documents

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/collections/{collection_name}/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200404

{
  "name": "text"
}

Partial Update Collection

Partially update a collection.

This endpoint allows for partial updates to a collection's details. Only the fields provided in the payload will be updated.

Args: request: The request object containing authentication details. collection_name (str): The name of the collection to be updated. payload (PatchCollectionIn): The payload containing the fields to be updated.

Returns: dict: A message indicating the collection was updated successfully.

Raises: HTTPException: If the collection is not found or the user is not authorized to update it.

PATCHhttps://api.colivara.com/v1/collections/{collection_name}/

Authorization

Bearer

Path parameters

collection_name*Collection Name

Body

application/json

nameName

stringnull

metadataMetadata

objectnull

Response

200404

OK

Body

application/json

id*Id

name*Name

metadata*Metadata

num_documents*Num Documents

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/collections/{collection_name}/', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200404

{
  "name": "text"
}

Delete Collection

Delete a collection by its name.

This endpoint deletes a collection specified by the collection_name parameter. The collection must belong to the authenticated user.

Args: request: The HTTP request object, which includes authentication information. collection_id (int): The ID of the collection to be deleted.

Returns: dict: A message indicating that the collection was deleted successfully.

Raises: HTTPException: If the collection does not exist or does not belong to the authenticated user.

DELETEhttps://api.colivara.com/v1/collections/{collection_name}/

Authorization

Bearer

Path parameters

collection_name*Collection Name

Response

204404

No Content

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/collections/{collection_name}/', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

404

{
  "detail": "text"
}

Upsert Document

Create or update a document in a collection. Average latency is 7 seconds per page.

This endpoint allows the user to create or update a document in a collection. The document can be provided as a URL or a base64-encoded string. if the collection is not provided, a collection named "default_collection" will be used. if the collection is provided, it will be created if it does not exist.

Args: request: The HTTP request object, which includes the user information. payload (DocumentIn): The input data for creating or updating the document.

Returns: str: A message indicating that the document is being processed.

Raises: HttpError: If the document cannot be created or updated.

Example: POST /documents/upsert-document/ { "name": "my_document", "metadata": {"author": "John Doe"}, "collection": "my_collection", "url": "https://example.com/my_document.pdf, "wait": true # optional, if true, the response will be sent after waiting for the document to be processed. Otherwise, it will be done asynchronously. }

POSThttps://api.colivara.com/v1/documents/upsert-document/

Authorization

Bearer

Body

application/json

name*Name

metadataMetadata

collection_nameCollection Name

The name of the collection to which the document belongs. If not provided, the document will be added to the default_collection. Use 'all' to access all collections belonging to the user.

urlUrl

stringnull

base64Base64

stringnull

waitWait

booleannull

Response

201202400402

Created

Body

application/json

id*Id

name*Name

metadataMetadata

urlUrl

stringnull

num_pages*Num Pages

collection_name*Collection Name

pagesPages

array of PageOutnull

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/documents/upsert-document/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text"
    }),
});
const data = await response.json();

Response

201202400402

{
  "name": "text",
  "url": "text",
  "collection_name": "text",
  "pages": [
    {
      "document_name": "text",
      "img_base64": "text"
    }
  ]
}

Get Document

Retrieve a specific document from the user documents. Default collection is "default_collection". To get all documents, use collection_name="all".

Args: request: The HTTP request object. document_name (str): The ID of the document to retrieve. expand (Optional[str]): A comma-separated list of fields to expand in the response. If "pages" is included, the document's pages will be included.

Returns: DocumentOut: The retrieved document with its details.

Raises: HTTPException: If the document or collection is not found.

Example: GET /documents/{document_name}/?collection_name={collection_name}&expand=pages

GEThttps://api.colivara.com/v1/documents/{document_name}/

Authorization

Bearer

Path parameters

document_name*Document Name

Query parameters

Response

200404409

OK

Body

application/json

id*Id

name*Name

metadataMetadata

urlUrl

stringnull

num_pages*Num Pages

collection_name*Collection Name

pagesPages

array of PageOutnull

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/documents/{document_name}/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200404409

{
  "name": "text",
  "url": "text",
  "collection_name": "text",
  "pages": [
    {
      "document_name": "text",
      "img_base64": "text"
    }
  ]
}

Partial Update Document

Partially update a document.

This endpoint allows for partial updates to a document's details. Only the fields provided in the payload will be updated. If the URL is changed or base64 is provided, the document will be re-embedded. Otherwise, only the metadata and name will be updated.

Args: request: The request object containing authentication details. document_name (str): The name of the document to be updated. payload (DocumentInPatch): The payload containing the fields to be updated.

Returns: Tuple[int, DocumentOut] | Tuple[int, GenericError]: A tuple containing the status code and the updated document or an error message.

Raises: HTTPException: If the document is not found or the user is not authorized to update it.

PATCHhttps://api.colivara.com/v1/documents/{document_name}/

Authorization

Bearer

Path parameters

document_name*Document Name

Body

application/json

nameName

stringnull

metadataMetadata

objectnull

collection_nameCollection Name

The name of the collection to which the document belongs. If not provided, the document will be added to the default_collection. Use 'all' to access all collections belonging to the user.

stringnull

urlUrl

stringnull

base64Base64

stringnull

Response

200402404409

OK

Body

application/json

id*Id

name*Name

metadataMetadata

urlUrl

stringnull

num_pages*Num Pages

collection_name*Collection Name

pagesPages

array of PageOutnull

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/documents/{document_name}/', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200402404409

{
  "name": "text",
  "url": "text",
  "collection_name": "text",
  "pages": [
    {
      "document_name": "text",
      "img_base64": "text"
    }
  ]
}

List Documents

Fetch a list of documents for a given collection.

This endpoint retrieves documents associated with a specified collection name. Optionally, it can expand the response to include pages of each document.

Args: request (Request): The request object. collection_name (Optional[str]): The name of the collection to fetch documents from. Defaults to "default_collection". Use "all" to fetch documents from all collections. expand (Optional[str]): A comma-separated string specifying additional fields to include in the response. If "pages" is included, the pages of each document will be included.

Returns: List[DocumentOut]: A list of documents with their details. If expanded, includes pages of each document.

Raises: HTTPException: If the collection or documents are not found.

Example: GET /documents/?collection_name=default_collection&expand=pages

GEThttps://api.colivara.com/v1/documents/

Authorization

Bearer

Query parameters

Response

200

OK

Body

application/json

id*Id

name*Name

metadataMetadata

urlUrl

stringnull

num_pages*Num Pages

collection_name*Collection Name

pagesPages

array of PageOutnull

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/documents/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

[
  {
    "name": "text",
    "url": "text",
    "collection_name": "text",
    "pages": [
      {
        "document_name": "text",
        "img_base64": "text"
      }
    ]
  }
]

Delete Document

Delete a document by its Name.

This endpoint deletes a document specified by the document_name parameter. The document must belong to the authenticated user.

Args: request: The HTTP request object, which includes authentication information. collection_name (name): The name of the collection containing the document. Defaults to "default_collection". Use "all" to access all collections belonging to the user. document_name (int): The name of the document to be deleted.

Returns: dict: A message indicating that the document was deleted successfully.

Raises: HTTPException: If the document does not exist or does not belong to the authenticated user.

Example: DELETE /documents/delete-document/{document_name}/?collection_name={collection_name}

DELETEhttps://api.colivara.com/v1/documents/delete-document/{document_name}/

Authorization

Bearer

Path parameters

document_name*Document Name

Query parameters

Response

204404409

No Content

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/documents/delete-document/{document_name}/', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

404409

{
  "detail": "text"
}

Search

Search for pages similar to a given query.

This endpoint allows the user to search for pages similar to a given query. The search is performed across all documents in the specified collection.

Args: request: The HTTP request object, which includes the user information. payload (QueryIn): The input data for the search, which includes the query string and collection ID.

Returns: QueryOut: The search results, including the query and a list of similar pages.

Raises: HttpError: If the collection does not exist or the query is invalid.

Example: POST /search/ { "query": "dog", "collection_name": "my_collection", "top_k": 3, "query_filter": { "on": "document", "key": "breed", "value": "collie", "lookup": "contains" } }

POSThttps://api.colivara.com/v1/search/

Authorization

Bearer

Body

application/json

query*Query

collection_nameCollection Name

stringnull

top_kTop K

integernull

query_filterany of

QueryFilternull

Response

200402503

OK

Body

application/json

query*Query

results*Results

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/search/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "query": "text"
    }),
});
const data = await response.json();

Response

200402503

{
  "query": "text",
  "results": [
    {
      "collection_name": "text",
      "document_name": "text",
      "raw_score": 0,
      "normalized_score": 0,
      "img_base64": "text"
    }
  ]
}

File To Imgbase64

Upload one file, converts to images and return their base64 encoded strings with 1-indexed page numberss.

Args: request: The HTTP request object. file UploadedFile): One uploaded file

Returns: List[FileOut]: A list of FileOut objects containing the base64 encoded strings of the images.

POSThttps://api.colivara.com/v1/helpers/file-to-imgbase64/

Authorization

Bearer

Body

multipart/form-data

file*File

Response

200

OK

Body

application/json

img_base64*Img Base64

page_number*Page Number

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/helpers/file-to-imgbase64/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "file": "binary"
    }),
});
const data = await response.json();

Response

200

[
  {
    "img_base64": "text"
  }
]

File To Base64

Upload one file, converts to base64 encoded strings.

Args: request: The HTTP request object. file UploadedFile): One uploaded file

Returns: str: base64 encoded string of the file.

POSThttps://api.colivara.com/v1/helpers/file-to-base64/

Authorization

Bearer

Body

multipart/form-data

file*File

Response

200

OK

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/helpers/file-to-base64/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "file": "binary"
    }),
});
const data = await response.json();

Embeddings

Embed a list of documents.

This endpoint allows the user to embed a list of documents.

Args: request: The HTTP request object, which includes the user information. payload (EmbeddingsIn): The input data for embedding the documents.

Returns: EmbeddingsOut: The embeddings of the documents and metadata.

Raises: HttpError: If the documents cannot be embedded.

POSThttps://api.colivara.com/v1/embeddings/

Authorization

Bearer

Body

application/json

input_data*Input Data

task*TaskEnum

imagequery

Response

200402503

OK

Body

application/json

data*Data

model*Model

usage*Usage

Request

JavaScriptCurlPython

const response = await fetch('https://api.colivara.com/v1/embeddings/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "input_data": [
        "text"
      ],
      "task": "image"
    }),
});
const data = await response.json();

Response

200402503

{
  "data": [],
  "model": "text"
}