API Reference

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

PreviousAdvanced filtering NextSDKs

Last updated 2 months ago

Was this helpful?

Health

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

Response

Request

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

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

Body

query*Query

collection_nameCollection Name

top_kTop K

query_filterany of

Response

Body

query*Query

results*Results

Request

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",
      "collection_name": "all",
      "top_k": 3,
      "query_filter": {
        "on": "document",
        "lookup": "key_lookup"
      }
    }),
});
const data = await response.json();

Response

{
  "query": "text",
  "results": [
    {
      "collection_name": "text",
      "collection_id": 1,
      "collection_metadata": {},
      "document_name": "text",
      "document_id": 1,
      "document_metadata": {},
      "page_number": 1,
      "raw_score": 1,
      "normalized_score": 1,
      "img_base64": "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

Body

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

base64Base64

waitWait

use_proxyUse Proxy

Response

Created

Body

id*Id

name*Name

metadataMetadata

urlUrl

num_pages*Num Pages

collection_name*Collection Name

pagesPages

Request

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",
      "metadata": {},
      "collection_name": "default_collection",
      "wait": false,
      "use_proxy": false
    }),
});
const data = await response.json();

Response

{
  "id": 1,
  "name": "text",
  "metadata": {},
  "url": "text",
  "num_pages": 1,
  "collection_name": "text",
  "pages": [
    {
      "document_name": "text",
      "img_base64": "text",
      "page_number": 1
    }
  ]
}

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

Response

Body

id*Id

name*Name

metadata*Metadata

num_documents*Num Documents

Request

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

Response

[
  {
    "id": 1,
    "name": "text",
    "metadata": {},
    "num_documents": 1
  }
]

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

Path parameters

collection_name*Collection Name

Response

Body

id*Id

name*Name

metadata*Metadata

num_documents*Num Documents

Request

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

Response

{
  "id": 1,
  "name": "text",
  "metadata": {},
  "num_documents": 1
}

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

Path parameters

collection_name*Collection Name

Body

nameName

metadataMetadata

Response

Body

id*Id

name*Name

metadata*Metadata

num_documents*Num Documents

Request

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({
      "metadata": {}
    }),
});
const data = await response.json();

Response

{
  "id": 1,
  "name": "text",
  "metadata": {},
  "num_documents": 1
}

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

Path parameters

collection_name*Collection Name

Response

No Content

Request

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

Response

{
  "detail": "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

Path parameters

document_name*Document Name

Query parameters

Response

Body

id*Id

name*Name

metadataMetadata

urlUrl

num_pages*Num Pages

collection_name*Collection Name

pagesPages

Request

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

Response

{
  "id": 1,
  "name": "text",
  "metadata": {},
  "url": "text",
  "num_pages": 1,
  "collection_name": "text",
  "pages": [
    {
      "document_name": "text",
      "img_base64": "text",
      "page_number": 1
    }
  ]
}

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

Path parameters

document_name*Document Name

Body

nameName

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

base64Base64

use_proxyUse Proxy

Response

Body

id*Id

name*Name

metadataMetadata

urlUrl

num_pages*Num Pages

collection_name*Collection Name

pagesPages

Request

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({
      "metadata": {},
      "collection_name": "default_collection",
      "use_proxy": false
    }),
});
const data = await response.json();

Response

{
  "id": 1,
  "name": "text",
  "metadata": {},
  "url": "text",
  "num_pages": 1,
  "collection_name": "text",
  "pages": [
    {
      "document_name": "text",
      "img_base64": "text",
      "page_number": 1
    }
  ]
}

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

Query parameters

Response

Body

id*Id

name*Name

metadataMetadata

urlUrl

num_pages*Num Pages

collection_name*Collection Name

pagesPages

Request

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

Response

[
  {
    "id": 1,
    "name": "text",
    "metadata": {},
    "url": "text",
    "num_pages": 1,
    "collection_name": "text",
    "pages": [
      {
        "document_name": "text",
        "img_base64": "text",
        "page_number": 1
      }
    ]
  }
]

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

Path parameters

document_name*Document Name

Query parameters

Response

No Content

Request

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

{
  "detail": "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

Body

file*File

Response

Body

img_base64*Img Base64

page_number*Page Number

Request

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": "text"
    }),
});
const data = await response.json();

Response

[
  {
    "img_base64": "text",
    "page_number": 1
  }
]

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

Body

file*File

Response

Request

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": "text"
    }),
});
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

Body

input_data*Input Data

task*TaskEnum

imagequery

Response

Body

data*Data

model*Model

usage*Usage

Request

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": [
        null
      ],
      "task": "image"
    }),
});
const data = await response.json();

Response

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