API Reference

Welcome to Cosmos Platform API Reference. Try and develop using our Orchestration Models, which include:

  • LLM chatting and embedding
  • Translation Models
  • Web Models
  • Files Parsing and Querying
  • Vision (to come)
Here you will find the code to directly reach our API endpoints, and you can also use our libraries.

Getting started?

Check out our Cosmos Platform Documentation guides and tutorials.

BASE URL

https://platform.cosmos-suite.ai/api/v1
This is the root endpoint for all API requests. Endpoints calls are relative to this server address.

CLIENT LIBRARIES

Cosmos (Python)

Official Python package for interacting with Cosmos API.

View on PyPI

INSTALL

# If using Poetry package manager:

$ poetry add delos-cosmos

# Or default PIP package manager:

$ pip install delos-cosmos

INITIALIZATION

from cosmos import CosmosClient

cosmos_client = CosmosClient(your-cosmos-api-key)

USE

response = cosmos_client.llm_chat_request(text="Hello Cosmos!")

print(response)

LLM

LLM Chat

POST
/llm/chat

Chat with a LLM. Requires authentication using an API key.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform.

Body Parameters

textstring
REQUIRED

The message to be sent to the LLM.

modelstring

The model to chat with. Options are `gpt-4o-mini` (default), `gpt-4o`, `gpt-3.5` (legacy), `gpt-4-turbo`, `command-r`, `command-r-plus`, `llama-3-70b-instruct`, `mistral-large`, `mistral-small`, being `gpt-4o-mini` the default.

Returns

messagestring

Request outcome message.

request_idstring

ID of the request.

response_idstring

ID of the response from the LLM.

statusstring

Status of the request.

status_codeinteger

HTTP status code.

timestampstring

Timestamp of the response.

/llm/chat
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.llm_chat_request( text="Hello Cosmos!", model="gpt-4o-mini", ) print(response)
Response
{ "request_id": "a7049c4f-a7cc-46d1-80e9-2b7ecb8b4a22", "response_id": "792b9b3d-3650-4ef1-8d5a-7d4911427bea", "status_code": 200, "status": "success", "message": "Chat response received.", "data": "Hello! How can I assist you today?", "error": null, "timestamp": "2024-12-03T14:36:53.029212Z", "cost": 7e-05, }

Embed text

POST
/llm/embed

Generates an embedding for the provided text.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

textstring
REQUIRED

Text to be embedded

Returns

messagestring

Request outcome message.

request_idstring

ID of the request.

response_idstring

ID of the response.

statusstring

Status of the request.

status_codeinteger

HTTP status code.

timestampstring

Timestamp of the response.

/llm/embed
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.llm_embed_request(text="Hello world") print(response)
Response
{ "request_id":"6cbd9a37-8ffc-40ab-9f52-be4b35cafeb4", "response_id":"ba740405-7854-48ff-8a13-d9075ebfb32e", "status_code":200, "status":"success", "message":"Text successfully embedded.", "data": { "embeddings": [ { "id": 0, "text": "Hello world", "embedding": [ -0.018942920491099358, -0.012851867824792862, ..., -0.01006540097296238, 0.0035288927610963583, -0.013837556354701519 ] } }, "error":null, "timestamp":"2024-12-03T14:38:10.930607Z", "cost":0.00017 }

Translate

Translate text

POST
/translate-text

Translate a text using the specified output language.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform.

Body Parameters

textstring
REQUIRED

The text to be translated

output_languagestring
REQUIRED

ISO 639-1 code of the target language

input_languagestring

ISO 639-1 code of the origin language

Returns

translationstring

Translated text

costfloat

Translation cost in credits or currency

/translate-text
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.translate_text_request( text="Hello, how are you?", output_language="fr", ) print(response)
Response
{ "message": "Request completed successfully", "request_id": "123e4567-e89b-12d3-a456-426614174000", "response_id": "123e4567-e89b-12d3-a456-426614174001", "status": "success", "status_code": 200, "data": { "translation": "Hola, ¿cómo estás?" }, "error": null, "timestamp": "2024-10-15T13:32:34.727776Z", "cost": 0.00002 }

Translate a file

POST
/translate-file

Translate a file using the specified return type.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform.

Body Parameters

filestring
REQUIRED

File (path and name) to be translated

output_languagestring
REQUIRED

ISO 639-1 code of the target language

input_languagestring

ISO 639-1 code of the origin language

return_typestring

The format for the translation result. Default is `raw_text`.

Returns

translationstring

Translated text

costfloat

Translation cost in credits or currency

file_urlstring

URL to download the translated file (if `url` return type)

file_byteslist[bytes]

Byte data of the translated file (if applicable)

/translate-file
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") local_filepath = "/path/to/filename.docx" response = cosmos_client.translate_file_request( filepath=local_filepath, output_language="it", return_type="raw_text", ) print(response)
Response
{ "request_id": "a92aebfd-231b-4d7f-8721-369f4de4805e", "response_id": "0fc761ce-963b-4459-9d46-3f15ca6eb911", "status_code": 200, "status": "success", "message": "Translation completed successfully", "data": { "translation": "Ciao, questo è un documento di prova.", "file_url": null, "file_bytes": null }, "error": null, "timestamp": "2024-10-16T07:25:41.793412Z", "cost": 0.00004, }

Files

List Index

GET
/files/list_index

Lists all index that are 'active' or in 'countdown' for the organization with their details.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Returns

dataarray

Array of index objects including index_uuid, created_at, expires_at, status, and vectorized status

/files/list_index
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.files_index_list_request() print(response)
Response
{ "request_id": "1fb2732b-3632-4c61-bcb7-25078c9b3d87", "response_id": "4fc9c0ae-3fae-4725-a25c-28161dc8ea89", "status_code": 200, "status": "success", "message": "Retrieved 2 indices.", "data": { "indices": [ { "index_uuid": "277bed11-c6a1-4d5e-98f2-7dd9737e", "name": "Financial reports", "status": "active", "vectorized": false, "created_at": "2024-12-03T11:29:11.234237+00:00", "updated_at": "2024-12-03T11:29:11.234242+00:00", "expires_at": null, "storage": { "size_bytes": 147086, "size_mb": 0.14, "num_files": 1, }, }, { "index_uuid": "0850f0d1-72d5-4f2a-80f3-6718c5cd6", "name": "Resarch Articles", "status": "countdown", "vectorized": true, "created_at": "2024-12-02T16:30:55.310428+00:00", "updated_at": "2024-12-03T11:06:53.366713+00:00", "expires_at": "2024-12-03T15:07:53.129516+00:00", "storage": { "size_bytes": 26385089, "size_mb": 25.16, "num_files": 7, }, }, ], "total_storage": { "bytes": 27648191, "mb": 26.37, "limit_mb": 100, "usage_percentage": 26.4, }, }, "error": null, "timestamp": "2024-12-03T14:03:26.680425Z", "cost": 0.0, }

Index Details

GET
/files/index_details

Fetches details about a specified index, such as its current status, expiration time, vectorization state, and a list of files it contains.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Query Parameters

index_uuidstring
REQUIRED

The unique id for the files index

Returns

dataobject

Index details including index_uuid, vectorized status, status, expires_at, and files list

/files/index_details
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.files_index_details_request( index_uuid="35d885a5-fc92-4ae5-b030", ) print(response)
Response
{ "request_id":"e08e604b-356b-4f24-b497-058c2410a034", "response_id":"8341bb51-7574-4281-bc76-27e150456e65", "status_code":200, "status":"success", "message":"Index 35d885a5-fc92-4ae5-b030 details retrieved.", "data":{ "index_uuid":"277bed11-c6a1-4d5e-98f2-7dd9737ee881", "name":"Financial Reports", "vectorized":false, "status":"active", "expires_at":null, "created_at":"2024-12-03T11:29:11.234237+00:00", "updated_at":"2024-12-06T08:32:01.732122+00:00", "storage": { "size_bytes":83503, "size_mb":0.08, "num_files":3 }, "files":[ { "file_hash":"3c67b758c34d1e316c2968ed68b96", "filename":"Q3_2023_Financial_Report.pdf", "size":2743841 }, { "file_hash":"8dab82b1f69972cb9d9d4261b20d5", "filename":"Presentation.pptx", "size":1178274 }, { "file_hash":"c0d5aaf3791eeee1001e50f9377", "filename":"Investment_Report_2023.docx", ":28620 } ] }, "error":null, "timestamp":"2024-12-06T09:33:40.459524Z", "cost":0.0 }

Parse files

POST
/files/parse

Universal reader and parser that reads a text file and parses it into a unified structure.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

filebinary
REQUIRED

The file to be processed for chunking

extract_typestring

The type of chunking to perform. Default is `chunks` (extracting custom sized blocks of text), `pages` (reading content by pages), and `file` (parsing all content in a single field).

filter_pagesstring

Pages to extract. When not provided, all pages are parsed.

k_mininteger

Minimum chunk size. Default: 500 tokens.

k_maxinteger

Maximum chunk size. Default: 600 tokens.

overlapinteger

Allowed overlapping allowed between chunks. Default: 0 tokens.

Returns

dataobject

Chunked content based on extract type

metadataobject

Processing metadata including cost

/files/parse
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.files_parse_request( filepath=Path("/path/to/file1.docx"), extract_type="chunks", k_min=500, k_max=1000, overlap=0, filter_pages=[], ) print(response)
Response
{ "request_id": "f251c467-58bb-4686-a965-5686322b53a7", "response_id": "5f15975c-780d-47c1-86e1-0185af5efa0c", "status_code": 200, "status": "success", "message": "File parsed successfully", "data": { "chunks": [ { "content": "(Your file contents...)", "size": 501, "page": 1, "position": {}, }, { "content": "**3.2 Figure 2...**", "size": 30, "page": 2, "position": {}, }, ], }, "error": null, "timestamp": "2024-12-03T14:12:46.462944Z", "cost": 0.0027, }

Create Index

POST
/files/create_index_and_parse

Creates an index for the uploaded files and parses their content.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

namestring
REQUIRED

Name for the index

filesarray
REQUIRED

Array of files to be uploaded and indexed

Returns

messagestring

Request outcome message

statusstring

Status of the request

/files/create_index_and_parse
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") filepaths = [ "/path/to/file1.docx", "/path/to/file2.pdf", "/path/to/file3.txt", ] response = cosmos_client.files_index_create_request( filepaths=filepaths, name="My Files Index", ) print(response)
Response
{ "request_id": "fa86ced4-eb83-4c7d-afbf-57a00f952889", "response_id": "4d2d91fa-75aa-4c68-b903-16a92a84a80d", "status_code": 200, "status": "success", "message": "Index created successfully", "data": { "index_uuid": "277bed11-c6a1-4d5e-98f2-7dd9737ee881", "name": "My Files Index", "created_at": "2024-12-03T11:29:11.234237+00:00", "updated_at": "2024-12-03T11:29:11.234242+00:00", "vectorized": "False", "status": "active", "files": { "26a79e1e7233ef12c763c4a0e6b322168c": { "file_hash": "26a79e1e7233ef12c763c4a0e6b322168c", "filename": "file1.docx", "size": 147086, }, "127a213247f5b08eecb212b28775e521f6": { "file_hash": "127a213247f5b08eecb212b28775e521f6", "filename": "file2.pdf", "size": 147086, }, "f66d2345d7c64ea7e46806b81bf2649b9": { "file_hash": "f66d2345d7c64ea7e46806b81bf2649b9", "filename": "file3.txt", "size": 147086, }, }, }, "error": null, "timestamp": "2024-12-03T13:51:19.123547Z", "cost": 0.0027, }

Add Files To Index

POST
/files/add_files_to_index

Adds new files to an existing index.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

index_uuidstring
REQUIRED

The unique id for the files index

filesarray
REQUIRED

Array of files to be added to the index

Returns

index_uuidstring

Unique identifier of the existing index

new_filesarray

List of file hashes added to the index

processed_chunksinteger

Number of chunks processed from new files

/files/add_files_to_index
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") filepaths = [ "/path/to/file1.docx", "/path/to/file2.pdf", "/path/to/file3.txt", ] response = cosmos_client.files_index_add_files_request( index_uuid="d01fab70-124e-440f-bb4a-397b32ff00cb", filepaths=filepaths, ) print(response)
Response
{ "request_id": "53c5e71a-6616-4e99-87bb-f4247111907f", "response_id": "1f5a8543-b892-4085-9147-5d9930665ee9", "status_code": 200, "status": "success", "message": "Files added and processed successfully", "data": { "index_uuid": "d01fab70-124e-440f-bb4a-397b32ff00cb", "new_files": ["127a213247f5b08eecb212b28775e"], "processed_chunks": 2, }, "error": null, "timestamp": "2024-12-06T08:32:01.743056Z", "cost": 0.001, }

Embed Index

POST
/files/embed_index

Vectorize Index Content. Calculates the vectorized representations of all text contents within the specified index.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

index_uuidstring
REQUIRED

The unique id for the files index

Returns

messagestring

Request outcome message

request_idstring

ID of the request

response_idstring

ID of the response

statusstring

Status of the request

status_codeinteger

HTTP status code

timestampstring

Timestamp of the response

/files/embed_index
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.files_index_embed_request( index_uuid="e5c156e2-aa64-4c7b-9f3e", ) print(response)
Response
{ "request_id": "a1fc8f56-79d8-428a-9b04-e69e5cdc16b2", "response_id": "6bee942a-b792-4e1e-aa61-31721c9edb1e", "status_code": 200, "status": "success", "message": "Index 'e5c15...-9f3e' successfully vectorized.", "data": { "index_uuid": "e5c156e2-aa64-4c7b-9f3e", }, "error": null, "timestamp": "2024-12-03T13:39:32.689477Z", "cost": 0.00034, }

Ask Index

POST
/files/ask_index

Queries a vectorized index for information related to a given question.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

index_uuidstring
REQUIRED

UUID of the index to be queried

questionstring
REQUIRED

Question about the documents in the index

output_languagestring

Desired output language code

active_filesarray

Comma-separated list of file hashes

Returns

answerstring

Response to the question based on indexed data

sourcesobject

Mapping of file identifiers to source file hashes

/files/ask_index
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.files_index_ask_request( index_uuid="f2503e3e-676a-4673-8ed5-cd7c8b627cea", question="Where is the mentioned power station located?", output_language="en", ) print(response)
Response
{ "message": "Request completed successfully", "request_id": "123e4567-e89b-12d3-a456-426614174000", "response_id": "123e4567-e89b-12d3-a456-426614174001", "status": "success", "status_code": 200, "data": { "answer": "Station is located in Oldbury ('FILE:1').", "sources": { 1: "file1_hash", 2: "file2_hash", }, }, "timestamp": "2024-10-15T13:32:34.727776Z", }

Rename Index

PUT
/files/rename_index

Renames an existing index based on the provided index UUID.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

index_uuidstring
REQUIRED

UUID of the index to be queried

namestring
REQUIRED

New name for the index

Returns

messagestring

Request outcome message

statusstring

Status of the request

index_uuidstring

The unique ID for the files index

old_namestring

The old name of the index

new_namestring

The new name of the index

updated_atstring

Timestamp when the index was updated

/files/rename_index
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.files_index_rename_request( index_uuid="0850f0d1-72d5-4f2a-80f3-6718c5cd6933", name="New name", ) print(response)
Response
{ "message": "Index name 'Old name' changed to 'New name'.", "request_id": "123e4567-e89b-12d3-a456-426614174000", "response_id": "123e4567-e89b-12d3-a456-426614174001", "status": "success", "status_code": 200, "index_uuid": "0850f0d1-72d5-4f2a-80f3-6718c5cd6933", "old_name": "Old name", "new_name": "New name", "updated_at": "2024-10-15T13:32:34.727776Z", }

Restore Index

PUT
/files/restore_index

Cancels the deletion or expiry of an index within the 2h from the *delete_index* request.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

index_uuidstring
REQUIRED

The unique id for the files index

Returns

index_uuidstring

Unique identifier of the index

statusstring

Updated status of the index

/files/restore_index
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.files_index_restore_request( index_uuid="123e4567-e89b-12d3-a456", ) print(response)
Response
{ "request_id": "123e4567-e89b-12d3-a456-426614174000", "response_id": "123e4567-e89b-12d3-a456-426614174001", "status_code": 200, "status": "success", "message": "Index restored successfully", "data": { "index_uuid": "123e4567-e89b-12d3-a456", "status": "active", }, "timestamp": "2024-11-18T12:00:00Z", }

Delete Files

DELETE
/files/delete_files_from_index

Deletes specific files from an existing index using their file hashes.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

index_uuidstring
REQUIRED

The unique id for the files index

files_hashesarray
REQUIRED

List of file hashes to delete from the index

Returns

index_uuidstring

Unique identifier of the index

remaining_filesarray

List of file hashes remaining in the index

/files/delete_files_from_index
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") hash1 = "127a213247f5b08eecb212b28775e521f69" response = cosmos_client.files_index_delete_files_request( index_uuid="d01fab70-124e-440f-bb4a-397b32ff00cb", files_hashes=[hash1, hash2], ) print(response)
Response
{ "request_id": "cffa76cd-87c9-4617-9290-af43671e069e", "response_id": "4607b131-1e31-4c1b-aca8-34138cdb46b6", "status_code": 200, "status": "success", "message": "File(s) deleted from index successfully", "data": { "index_uuid": "d01fab70-124e-440f-bb4a-397b32ff00cb", "remaining_files": [ "c0d5aaf3791eeee1001eff515a822206ab8df5650f93771ca", "f66d2345d7c64ea7e46806b81bf2649b9ffcfc78428feba00", ], }, "error": null, "timestamp": "2024-12-03T14:26:19.919794Z", "cost": 0.0, }

Delete Index

DELETE
/files/delete_index

Marks an existing index for deletion. It will be effective after 2h.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

index_uuidstring
REQUIRED

The unique id for the files index

Returns

index_uuidstring

Unique identifier of the index

statusstring

Updated status of the index

/files/delete_index
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.files_index_delete_request( index_uuid="277bed11-c6a1-4d5e-98f2", ) print(response)
Response
{ "request_id": "c2957b77-34f7-467a-8bb5-0f2f7c517dee", "response_id": "06655901-e06c-4e0c-a28f-6143fa034143", "status_code": 200, "status": "success", "message": "Index marked for deletion", "data": { "index_uuid": "277bed11-c6a1-4d5e-98f2", "expires_at": "2024-12-03T16:32:31.779965+00:00", }, "error": null, "timestamp": "2024-12-03T14:32:31.779965Z", "cost": 0.0, }

Web

Search

POST
/search

Perform a web search using the provided text and output language.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Body Parameters

textstring
REQUIRED

Request to be searched

output_languagestring

Output language code

desired_urlsarray

Comma-separated list of URLs to be priviledged in the search

Returns

reformulationstring

Reformulated search query

urlsarray

List of URLs related to the search

answerstring

Direct answer to the search query

/search
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.web_search_request( text="What is the capital of France?", output_language="en", desired_urls=["wikipedia.fr"] ) print(response)
Response
{ "request_id": "8f032022-8391-4036-8707-63a955d4518d", "response_id": "72495910-cbaf-434c-89c2-401590251adf", "status_code": 200, "status": "success", "message": "Search completed successfully", "data": { "reformulation": "What is the capital of France?", "urls": [ "https://www.example.com/paris", "https://www.travel.example/france", ], "answer": "The capital of France is Paris 'URL:1'...", }, "error": null, "timestamp": "2024-12-03T14:19:47.081348Z", "cost": 0.0042, }

Status

Health

GET
/health

Check the health status of the API.

Headers

apikeystring
REQUIRED

API key to authenticate requests to CosmosPlatform

Returns

statusstring

Health status of the API

messagestring

Status message

/health
from cosmos import CosmosClient cosmos_client = CosmosClient(apikey="my-cosmos-api-key") response = cosmos_client.status_health_request() print(response)
Response
{ "request_id": "849f6bde-375f-47e2-9977-8a3e521088b9", "response_id": "c5761413-b79a-412c-b324-95ce8dcf4d18", "status_code": 200, "status": "ok", "message": "Welcome to CosmosPlatform", "data": null, "error": null, "timestamp": "2024-12-03T14:22:58.671943Z", "cost": 0.0, }