For the full and updated reference list please refer to https://docs.circlemind.co/api-reference.

​
Introduction

The Circlemind REST API allows you to interact with our platform programmatically. You can use the API to perform various operations such as creating, reading, updating, and deleting resources.

​
Base URL

All API requests are made to the following base URL:

https://api.circlemind.co/

​
Authentication

The API uses api key authentication. You need to include your API key in the apiKey header of each request:

apiKey: YOUR_API_KEY

​
Response Format

All responses are in JSON format.

​
Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. A 2xx status code indicates success, while a 4xx or 5xx status code indicates an error. The response body will include an error message with more details (.detail).

​
Example Request

Here is an example of a request to fetch the list of your graphs:

curl -X GET "https://api.circlemind.co/list_graphs" -H "apiKey: YOUR_API_KEY"

All requests, except add and query, immediately return a response.

​
Adding and Quering Memories

After creating a graph, the two most important operations are add and query. Both operations send a request to our workers that get switfly processed and can be tracked until completion.

​
Add Request

In order to perform a memory addition, we need to send an add request to the workers. The processing is asynchronous and can be optionally tracked until completion.

const axios = require('axios');
const YOUR_API_KEY = 'YOUR_API_KEY';
const graphName = 'your_graph_name';

async function send_add_request(graphName, data) {
    const url = `https://api.circlemind.co/graph/${graphName}/insert`;
    const response = await axios.post(url, data, {
        headers: { apiKey: YOUR_API_KEY }
    });
}

const data = {
    memory: 'Your memory text here',
    metadata: JSON.stringify({
        id: 'unique-id-123'
    })
};
send_add_request(graphName, data);

​
Query Request

Similarly, here is an example of how to query using the CircleMind API in JavaScript:

const axios = require('axios');
const YOUR_API_KEY = 'YOUR_API_KEY';
const graphName = 'your_graph_name';

async function send_query_request(graphName: str, data: object) {
    const url = `https://api.circlemind.co/graph/${graphName}/query`
    const response = await axios.post(url, data, {
        headers: { apiKey: YOUR_API_KEY }
    });
    return response.data;
}

async function get_query_response(handle: object) {
    const url = `https://api.circlemind.co/graph/${graphName}/query/${handle.requestId}`;
    let status = 'CREATED';
    let data = null;

    while (!['DONE', 'FAILED'].includes(status)) {
        console.info('Waiting for response...');
        await new Promise((resolve) => setTimeout(resolve, 1000));
        const response = await axios.get(url, {
            headers: { apiKey: YOUR_API_KEY },
            params: { requestTime: handle.requestTime }
        });
        data = await reponse.data;
        status = data.status;        
    }
    if (status === 'FAILED') {
      throw new Error('Query failed.')
    }
    return [data.answer, data.context];
}

const data = {
    query: 'Your query string here',
    parameters: JSON.stringify({
        only_context: true, // Set to true to return only the context of the query
        with_references: false // Set to true to include text references in the response
    })
};

send_query_request(graphName, data).then(
    (handle) => get_query_response(handle)
).then(([answer, context] => console.log(answer, context)))

In this example:

  • Replace YOUR_API_KEY with your actual API key.

  • Replace your_graph_name with the name of your graph.

  • The query field should contain your query.

  • The parameters field is an optional JSON string that can include:

    • only_context: Set to true to return only the context of the query instead of processing it via an LLM.

    • with_references: Set to true to include references in the response.

    • entities_max_tokens, relations_max_tokens, chunks_max_tokens to control the maxmimum amount of tokens allowed in the context. Check the sdk documentation for more information.

To get the answer, we track the status of the query request. Upon completion, the querying result can be found in answer (the LLM generated answer) and context (the context passed to the LLM). Note that the same procedure can be used to track add requests using the endpoint https://api.circlemind.co/graph/{graph_name}/insert/{request_id}.

For more detailed information on each endpoint, refer to the full API reference at https://docs.circlemind.co/api-reference.

Query