4Minds API Reference

Models

List All Available Models

GET /api/v1/user/model List all available models in your account.

curl -X GET https://api.4minds.ai/api/v1/user/model \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Model Details

GET /api/v1/user/model/{model_id} Get details about a specific model.

Parameters

Parameter	Type	Required	Description
model_id	string	Yes	The unique identifier of the model

curl -X GET https://api.4minds.ai/api/v1/user/model/{model_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a New Model

POST /api/v1/user/model Create a new model (optionally with a dataset attached).

curl -X POST https://api.4minds.ai/api/v1/user/model \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "your-model-name",
    "dataset": "optional-dataset-id"
  }'

Delete a Model

DELETE /api/v1/user/model/{id} Delete a model by ID.

Parameters

Parameter	Type	Required	Description
id	string	Yes	The unique identifier of the model to delete

curl -X DELETE https://api.4minds.ai/api/v1/user/model/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Conversations

List All Conversations

GET /api/v1/user/conversations Retrieves all conversations for a specific model.

Query Parameters

Parameter	Type	Required	Description
model_id	string	Yes	The ID of the model to list conversations for

curl -X GET "https://api.4minds.ai/api/v1/user/conversations?model_id=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a New Conversation

POST /api/v1/user/conversations Creates a new conversation thread.

curl -X POST "https://api.4minds.ai/api/v1/user/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "1",
    "title": "New Conversation"
  }'

Rename a Conversation

PATCH /api/v1/user/conversations/{conversation_id} Updates the title of an existing conversation.

Path Parameters

Parameter	Type	Required	Description
conversation_id	string	Yes	The ID of the conversation to rename

curl -X PATCH "https://api.4minds.ai/api/v1/user/conversations/conversation_id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Conversation Title"
  }'

Delete a Conversation

DELETE /api/v1/user/conversations/{conversation_id} Permanently deletes a conversation and all its messages.

Path Parameters

Parameter	Type	Required	Description
conversation_id	string	Yes	The ID of the conversation to delete

curl -X DELETE "https://api.4minds.ai/api/v1/user/conversations/conversation_id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get All Messages from a Conversation

GET /api/v1/user/conversations/{conversation_id}/messages Retrieves all messages from a specific conversation thread.

Path Parameters

Parameter	Type	Required	Description
conversation_id	string	Yes	The ID of the conversation

curl -X GET "https://api.4minds.ai/api/v1/user/conversations/conversation_id/messages" \
  -H "Authorization: Bearer YOUR_API_KEY"

Datasets

List All Datasets

GET /api/v1/user/dataset Retrieves a list of all available datasets.

curl -X GET "https://api.4minds.ai/api/v1/user/dataset" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Dataset Details

GET /api/v1/user/dataset/{id} Retrieves detailed information about a specific dataset.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The unique identifier of the dataset

curl -X GET "https://api.4minds.ai/api/v1/user/dataset/dataset_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a New Dataset

POST /api/v1/user/dataset Creates a new dataset by uploading files or providing URLs to scrape.

Request Body

Parameter	Type	Required	Description
name	string	Yes	Name of the dataset
description	string	No	Description of the dataset
files	array	No	Array of files to upload
urls	array	No	Array of URLs to scrape for data

curl -X POST  https://api.4minds.ai/api/v1/user/dataset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@training_data.jsonl" \
  -F "files=@additional_data.csv" \
  -F "dataset_name=Customer Support Dataset" \
  -F "description=Training data for customer support bot" \
  -F "tags=support,training,chatbot"

Upload Files to Dataset

POST /api/v1/user/dataset/upload Adds files to an existing dataset.

Request Body

Multipart form data with the following fields:

Parameter	Type	Required	Description
dataset_id	string	Yes	The ID of the dataset
file	file	Yes	The file to upload

curl -X POST  https://api.4minds.ai/api/v1/user/dataset/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "dataset_id=123" \
  -F "files=@training_data.jsonl" \
  -F "files=@additional_data.csv"

Delete a Dataset

DELETE /api/v1/user/dataset/{id} Deletes a dataset. This can be a soft delete (by default), or a permanent delete.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The unique identifier of the dataset

Query Parameters

Parameter	Type	Required	Description
permanent	boolean	No	Set to `true` for permanent deletion. Default is `false` (soft delete)

curl -X DELETE  https://api.4minds.ai/api/v1/user/dataset/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Evaluations

List All Evaluations

GET /api/v1/evaluations List all evaluations with pagination and filtering.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number for pagination
per_page	integer	No	Number of results per page (default: 20)

curl -X GET " https://api.4minds.ai/api/v1/evaluations?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a New Evaluation

POST /api/v1/evaluations Create a new evaluation for a model.

Request Body

Parameter	Type	Required	Description
model_id	string	Yes	The ID of the model to evaluate
name	string	Yes	Name of the evaluation
config	object	No	Model-specific configuration for evaluation

curl -X POST  https://api.4minds.ai/api/v1/evaluations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GPT-4 RAGAS Evaluation",
    "description": "Evaluate GPT-4 on BEIR dataset",
    "type": "ragas",
    "model_id": 123,
    "benchmark_type": "beir",
    "question_count": 700
  }'

Get Evaluation Details

GET /api/v1/evaluations/{evaluation_id} Get details about a specific evaluation.

Path Parameters

Parameter	Type	Required	Description
evaluation_id	string	Yes	The unique identifier of the evaluation

curl -X GET  https://api.4minds.ai/api/v1/evaluations/456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Start Running an Evaluation

POST /api/v1/evaluations/{evaluation_id}/start Start running an evaluation.

Path Parameters

Parameter	Type	Required	Description
evaluation_id	string	Yes	The unique identifier of the evaluation

curl -X POST  https://api.4minds.ai/api/v1/evaluations/456/start \
  -H "Authorization: Bearer YOUR_API_KEY"

Run RAGAS Evaluation

POST /api/v1/evaluations/{evaluation_id}/run-ragas Run RAGAS evaluation with benchmark data.

Path Parameters

Parameter	Type	Required	Description
evaluation_id	string	Yes	The unique identifier of the evaluation

Executes a RAGAS (Retrieval Augmented Generation Assessment) benchmark evaluation on the specified evaluation.

curl -X POST  https://api.4minds.ai/api/v1/evaluations/456/run-ragas \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "samples": [],
    "selected_questions": []
  }'

Update Evaluation Metadata

PUT /api/v1/evaluations/{evaluation_id} Update an evaluation’s metadata.

Path Parameters

Parameter	Type	Required	Description
evaluation_id	string	Yes	The unique identifier of the evaluation

Request Body

Parameter	Type	Required	Description
name	string	No	Updated name for the evaluation
description	string	No	Updated description

curl -X PUT  https://api.4minds.ai/api/v1/evaluations/456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Evaluation Name",
    "description": "Updated description"
  }'

Delete an Evaluation

DELETE /api/v1/evaluations/{evaluation_id} Delete an evaluation (cannot delete running evaluations).

Path Parameters

Parameter	Type	Required	Description
evaluation_id	string	Yes	The unique identifier of the evaluation

Note: You cannot delete evaluations that are currently running.

curl -X DELETE  https://api.4minds.ai/api/v1/evaluations/456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Check Evaluation Name Availability

GET /api/v1/evaluations/check-name Check if an evaluation name is available.

Query Parameters

Parameter	Type	Required	Description
name	string	Yes	The evaluation name to check

curl -X GET " https://api.4minds.ai/api/v1/evaluations/check-name?name=My%20Evaluation" \
  -H "Authorization: Bearer YOUR_API_KEY"

Inference

Perform direct inference queries without streaming, perfect for simple question-answering and batch processing workflows using knowledge graphs.

Run a Single Query

POST /api/v1/user/inference Run a single query with your knowledge graph.

Required Parameters

Parameter	Type	Required	Description
query	string	Yes	The question or query to process
model_id	integer	Yes	The ID of the model to use for inference

Optional Parameters

Parameter	Type	Required	Description
conversation_id	string	No	Continue an existing conversation by providing its ID
thread_id	string	No	Thread identifier for managing conversation history
enable_web_search	boolean	No	Enable web search to enhance responses (default: false)
max_tokens	integer	No	Maximum response length (default: model-specific)
temperature	float	No	Response randomness from 0.0 to 1.0 (default: model-specific)
image_generation	boolean	No	Enable image generation in responses (default: false)
image_parameters	object	No	Image generation config: width, height, steps, guidance
persona	object	No	User persona configuration for customized responses
base_model	boolean	No	Bypass RAG and use base model directly, useful for evaluations (default: false)
session_id	string	No	Session tracking identifier
user_id	string	No	User identifier for tracking and personalization
tenant_id	string	No	Multi-tenancy identifier for organization-level isolation

Advanced sampling overrides

These parameters provide fine-grained control over response generation and are typically used for specialized use cases.

Parameter	Type	Required	Description
top_k	integer	No	Top-K sampling: limits token selection to top K options
top_p	float	No	Nucleus sampling: cumulative probability threshold
response_length_preference	string	No	Response verbosity: “concise”, “balanced”, or “detailed”
creativity_level	float	No	Balance between creative and deterministic outputs
factual_precision	float	No	Preference for factual accuracy in responses

curl -X POST  https://api.4minds.ai/api/v1/user/inference \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is machine learning?",
    "model_id": 1
  }'

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can obtain your API key from your 4Minds dashboard.

Response Format

All responses are returned in JSON format.

Success Response

{
  "status": "success",
  "data": { ... }
}

Error Response

{
  "status": "error",
  "message": "Error description"
}

Intro

Getting Started with 4Minds

4Minds Features

What's New in 4Minds

Key Terms and Concepts in 4Minds

Developer Tools

​Models

​List All Available Models

​Get Model Details

​Parameters

​Create a New Model

​Delete a Model

​Parameters

​Conversations

​List All Conversations

​Query Parameters

​Create a New Conversation

​Rename a Conversation

​Path Parameters

​Delete a Conversation

​Path Parameters

​Get All Messages from a Conversation

​Path Parameters

​Datasets

​List All Datasets

​Get Dataset Details

​Path Parameters

​Create a New Dataset

​Request Body

​Upload Files to Dataset

​Request Body

​Delete a Dataset

​Path Parameters

​Query Parameters

​Evaluations

​List All Evaluations

​Query Parameters

​Create a New Evaluation

​Request Body

​Get Evaluation Details

​Path Parameters

​Start Running an Evaluation

​Path Parameters

​Run RAGAS Evaluation

​Path Parameters

​Update Evaluation Metadata

​Path Parameters

​Request Body

​Delete an Evaluation

​Path Parameters

​Check Evaluation Name Availability

​Query Parameters

​Inference

​Run a Single Query

​Required Parameters

​Optional Parameters

​Advanced sampling overrides

​Authentication

​Response Format

​Success Response

​Error Response

Models

List All Available Models

Get Model Details

Parameters

Create a New Model

Delete a Model

Parameters

Conversations

List All Conversations

Query Parameters

Create a New Conversation

Rename a Conversation

Path Parameters

Delete a Conversation

Path Parameters

Get All Messages from a Conversation

Path Parameters

Datasets

List All Datasets

Get Dataset Details

Path Parameters

Create a New Dataset

Request Body

Upload Files to Dataset

Request Body

Delete a Dataset

Path Parameters

Query Parameters

Evaluations

List All Evaluations

Query Parameters

Create a New Evaluation

Request Body

Get Evaluation Details

Path Parameters

Start Running an Evaluation

Path Parameters

Run RAGAS Evaluation

Path Parameters

Update Evaluation Metadata

Path Parameters

Request Body

Delete an Evaluation

Path Parameters

Check Evaluation Name Availability

Query Parameters

Inference

Run a Single Query

Required Parameters

Optional Parameters

Advanced sampling overrides

Authentication

Response Format

Success Response

Error Response