> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4minds.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 4MINDS API Reference

> Complete reference for 4MINDS REST API endpoints.

## Models

### List All Available Models

**GET** `/api/v1/user/model`

List all available models in your account.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.4minds.ai/api/v1/user/model \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.4minds.ai/api/v1/user/model"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  models = response.json()

  for model in models:
      print(f"Model: {model['name']} - ID: {model['id']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.4minds.ai/api/v1/user/model', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const models = await response.json();
  models.forEach(model => {
    console.log(`Model: ${model.name} - ID: ${model.id}`);
  });
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/user/model',
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const models = JSON.parse(data);
      models.forEach(model => {
        console.log(`Model: ${model.name} - ID: ${model.id}`);
      });
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.4minds.ai/api/v1/user/model/{model_id} \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  model_id = "your_model_id"
  url = f"https://api.4minds.ai/api/v1/user/model/{model_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  model_details = response.json()
  print(model_details)
  ```

  ```javascript JavaScript theme={null}
  const modelId = 'model-123';
  const response = await fetch(`https://api.4minds.ai/api/v1/user/model/${modelId}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const model = await response.json();
  console.log(`Model Name: ${model.name}`);
  console.log(`Status: ${model.status}`);
  console.log(`Created: ${model.created_at}`);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const modelId = 'model-123';

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/user/model/${modelId}`,
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';

    res.on('data', (chunk) => {
      data += chunk;
    });

    res.on('end', () => {
      const model = JSON.parse(data);
      console.log(`Model Name: ${model.name}`);
      console.log(`Status: ${model.status}`);
      console.log(`Created: ${model.created_at}`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### Create a New Model

**POST** `/api/v1/user/model`

Create a new model (optionally with a dataset attached).

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.4minds.ai/api/v1/user/model"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "name": "your-model-name",
      "dataset": "optional-dataset-id"
  }

  response = requests.post(url, headers=headers, json=payload)
  new_model = response.json()
  print(f"Created model: {new_model}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.4minds.ai/api/v1/user/model', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model_name: 'Customer Support Bot',
      description: 'Model trained on customer support conversations',
      base_model_id: 1,
      training_type_id: 'sft',  // Use training type ID from training_types table
      dataset_id: 232,  // Attach dataset to model
      use_case_id: 1,
      persona_id: null
    })
  });

  const model = await response.json();
  console.log(`Model created: ${model.name} (ID: ${model.id})`);
  console.log(`Status: ${model.status}`);
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.4minds.ai/api/v1/user/model/{id} \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  model_id = 123
  url = f"https://api.4minds.ai/api/v1/user/model/{model_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.delete(url, headers=headers)

  if response.status_code == 200:
      result = response.json()
      if result:
          print(f"Model {model_id} deleted successfully")
  else:
      print(f"Error: {response.status_code} - {response.text}")
  ```

  ```javascript JavaScript theme={null}
  const modelId = 123;
  const response = await fetch(`https://api.4minds.ai/api/v1/user/model/${modelId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  if (response.ok) {
    const result = await response.json();
    if (result) {
      console.log(`Model ${modelId} deleted successfully`);
    }
  } else {
    const error = await response.text();
    console.error(`Error: ${response.status} - ${error}`);
  }
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const modelId = 123;

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/user/model/${modelId}`,
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';

    res.on('data', (chunk) => {
      data += chunk;
    });

    res.on('end', () => {
      if (res.statusCode === 200) {
        const result = JSON.parse(data);
        if (result) {
          console.log(`Model ${modelId} deleted successfully`);
        }
      } else {
        console.error(`Error: ${res.statusCode} - ${data}`);
      }
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

## 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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.4minds.ai/api/v1/user/conversations?model_id=1" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.4minds.ai/api/v1/user/conversations"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }
  params = {
      "model_id": 1,
      "limit": 10,
      "offset": 0
  }

  response = requests.get(url, headers=headers, params=params)
  conversations = response.json()

  for conv in conversations['conversations']:
      print(f"Conversation: {conv['title']}")
      print(f"  ID: {conv['id']}")
      print(f"  Messages: {conv['total_messages']}")
      print(f"  Created: {conv['created_at']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.4minds.ai/api/v1/user/conversations?model_id=1&limit=10', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  data.conversations.forEach(conv => {
    console.log(`Conversation: ${conv.title}`);
    console.log(`  ID: ${conv.id}`);
    console.log(`  Messages: ${conv.total_messages}`);
    console.log(`  Created: ${conv.created_at}`);
  });
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/user/conversations?model_id=1&limit=10',
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';

    res.on('data', (chunk) => {
      data += chunk;
    });

    res.on('end', () => {
      const result = JSON.parse(data);
      result.conversations.forEach(conv => {
        console.log(`Conversation: ${conv.title}`);
        console.log(`  ID: ${conv.id}`);
        console.log(`  Messages: ${conv.total_messages}`);
        console.log(`  Created: ${conv.created_at}`);
      });
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### Create a New Conversation

**POST** `/api/v1/user/conversations`

Creates a new conversation thread.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.4minds.ai/api/v1/user/conversations"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  data = {
      "title": "Customer Support Chat",
      "model_id": 1
  }

  response = requests.post(url, headers=headers, json=data)
  conversation = response.json()

  print(f"Conversation created: {conversation['id']}")
  print(f"Title: {conversation['title']}")
  print(f"Model ID: {conversation['model_id']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.4minds.ai/api/v1/user/conversations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Customer Support Chat',
      model_id: 1
    })
  });

  const conversation = await response.json();
  console.log(`Conversation created: ${conversation.id}`);
  console.log(`Title: ${conversation.title}`);
  console.log(`Model ID: ${conversation.model_id}`);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const data = JSON.stringify({
    title: 'Customer Support Chat',
    model_id: 1
  });

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/user/conversations',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Content-Length': data.length
    }
  };

  const req = https.request(options, (res) => {
    let responseData = '';
    
    res.on('data', (chunk) => {
      responseData += chunk;
    });
    
    res.on('end', () => {
      const conversation = JSON.parse(responseData);
      console.log(`Conversation created: ${conversation.id}`);
      console.log(`Title: ${conversation.title}`);
      console.log(`Model ID: ${conversation.model_id}`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.write(data);
  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  conversation_id = "CONVERSATION_ID"
  url = f"https://api.4minds.ai/api/v1/user/conversations/{conversation_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }
  params = {
      "title": "Updated Conversation Title"
  }

  response = requests.patch(url, headers=headers, params=params)
  conversation = response.json()

  print(f"Conversation updated: {conversation['id']}")
  print(f"New title: {conversation['title']}")
  ```

  ```javascript JavaScript theme={null}
  const conversationId = 'CONVERSATION_ID';
  const response = await fetch(`https://api.4minds.ai/api/v1/user/conversations/${conversationId}?title=${encodeURIComponent('Updated Conversation Title')}`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const conversation = await response.json();
  console.log(`Conversation updated: ${conversation.id}`);
  console.log(`New title: ${conversation.title}`);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const conversationId = 'CONVERSATION_ID';
  const title = encodeURIComponent('Updated Conversation Title');

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/user/conversations/${conversationId}?title=${title}`,
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';

    res.on('data', (chunk) => {
      data += chunk;
    });

    res.on('end', () => {
      const conversation = JSON.parse(data);
      console.log(`Conversation updated: ${conversation.id}`);
      console.log(`New title: ${conversation.title}`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.4minds.ai/api/v1/user/conversations/conversation_id" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  conversation_id = "CONVERSATION_ID"
  url = f"https://api.4minds.ai/api/v1/user/conversations/{conversation_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.delete(url, headers=headers)

  if response.status_code == 200:
      print(f"Conversation {conversation_id} deleted successfully")
  else:
      print(f"Error: {response.status_code}")
  ```

  ```javascript JavaScript theme={null}
  const conversationId = 'CONVERSATION_ID';
  const response = await fetch(`https://api.4minds.ai/api/v1/user/conversations/${conversationId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  if (response.ok) {
    console.log(`Conversation ${conversationId} deleted successfully`);
  } else {
    console.error(`Error: ${response.status}`);
  }
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const conversationId = 'CONVERSATION_ID';

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/user/conversations/${conversationId}`,
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    if (res.statusCode === 200) {
      console.log(`Conversation ${conversationId} deleted successfully`);
    } else {
      console.error(`Error: ${res.statusCode}`);
    }
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.4minds.ai/api/v1/user/conversations/conversation_id/messages" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  conversation_id = "CONVERSATION_ID"
  url = f"https://api.4minds.ai/api/v1/user/conversations/{conversation_id}/messages"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }
  params = {
      "limit": 50,
      "offset": 0
  }

  response = requests.get(url, headers=headers, params=params)
  messages = response.json()

  for msg in messages:
      print(f"{msg['sender_type']}: {msg['content']}")
      print(f"  Time: {msg['timestamp']}")
  ```

  ```javascript JavaScript theme={null}
  const conversationId = 'CONVERSATION_ID';
  const response = await fetch(`https://api.4minds.ai/api/v1/user/conversations/${conversationId}/messages?limit=50`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const messages = await response.json();
  messages.forEach(msg => {
    console.log(`${msg.sender_type}: ${msg.content}`);
    console.log(`  Time: ${msg.timestamp}`);
  });
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const conversationId = 'CONVERSATION_ID';

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/user/conversations/${conversationId}/messages?limit=50`,
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';

    res.on('data', (chunk) => {
      data += chunk;
    });

    res.on('end', () => {
      const messages = JSON.parse(data);
      messages.forEach(msg => {
        console.log(`${msg.sender_type}: ${msg.content}`);
        console.log(`  Time: ${msg.timestamp}`);
      });
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

## Datasets

### List All Datasets

**GET** `/api/v1/user/dataset`

Retrieves a list of all available datasets.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.4minds.ai/api/v1/user/dataset" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  url = " https://api.4minds.ai/api/v1/user/dataset"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  datasets = response.json()

  for dataset in datasets:
      print(f"Dataset: {dataset['name']}")
      print(f"  ID: {dataset['id']}")
      print(f"  Size: {dataset['size']} bytes")
      print(f"  Created: {dataset['created_at']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(' https://api.4minds.ai/api/v1/user/dataset', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const datasets = await response.json();
  datasets.forEach(dataset => {
    console.log(`Dataset: ${dataset.name}`);
    console.log(`  ID: ${dataset.id}`);
    console.log(`  Size: ${dataset.size} bytes`);
    console.log(`  Created: ${dataset.created_at}`);
  });
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/user/dataset',
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const datasets = JSON.parse(data);
      datasets.forEach(dataset => {
        console.log(`Dataset: ${dataset.name}`);
        console.log(`  ID: ${dataset.id}`);
        console.log(`  Size: ${dataset.size} bytes`);
        console.log(`  Created: ${dataset.created_at}`);
      });
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.4minds.ai/api/v1/user/dataset/dataset_123" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  dataset_id = "dataset-123"
  url = f" https://api.4minds.ai/api/v1/user/dataset/{dataset_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  dataset = response.json()

  print(f"Dataset Name: {dataset['name']}")
  print(f"ID: {dataset['id']}")
  print(f"Size: {dataset['size']} bytes")
  print(f"Status: {dataset['status']}")
  print(f"Created: {dataset['created_at']}")
  ```

  ```javascript JavaScript theme={null}
  const datasetId = 'dataset-123';
  const response = await fetch(` https://api.4minds.ai/api/v1/user/dataset/${datasetId}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const dataset = await response.json();
  console.log(`Dataset Name: ${dataset.name}`);
  console.log(`ID: ${dataset.id}`);
  console.log(`Size: ${dataset.size} bytes`);
  console.log(`Status: ${dataset.status}`);
  console.log(`Created: ${dataset.created_at}`);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const datasetId = 'dataset-123';

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/user/dataset/${datasetId}`,
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const dataset = JSON.parse(data);
      console.log(`Dataset Name: ${dataset.name}`);
      console.log(`ID: ${dataset.id}`);
      console.log(`Size: ${dataset.size} bytes`);
      console.log(`Status: ${dataset.status}`);
      console.log(`Created: ${dataset.created_at}`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL (Files Only) theme={null}
  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"
  ```

  ```bash cURL (URLs Only) theme={null}
  curl -X POST  https://api.4minds.ai/api/v1/user/dataset \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F 'urls=["https://docs.example.com/page1","https://docs.example.com/page2"]' \
    -F "dataset_name=Documentation Dataset" \
    -F "description=Training data from documentation pages" \
    -F "tags=docs,web,scraping"
  ```

  ```bash cURL (Files + URLs) theme={null}
  curl -X POST  https://api.4minds.ai/api/v1/user/dataset \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "files=@training_data.jsonl" \
    -F 'urls=["https://docs.example.com/api","https://blog.example.com/post"]' \
    -F "dataset_name=Mixed Dataset" \
    -F "description=Training data from files and web sources" \
    -F "tags=mixed,training,web"
  ```

  ```python Python (Files Only) theme={null}
  import requests

  url = " https://api.4minds.ai/api/v1/user/dataset"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  # Upload multiple files with metadata
  files = [
      ('files', ('training_data.jsonl', open('training_data.jsonl', 'rb'), 'application/x-jsonlines')),
      ('files', ('additional_data.csv', open('additional_data.csv', 'rb'), 'text/csv'))
  ]

  data = {
      'dataset_name': 'Customer Support Dataset',
      'description': 'Training data for customer support bot',
      'tags': 'support,training,chatbot'
  }

  response = requests.post(url, headers=headers, files=files, data=data)
  dataset = response.json()

  print(f"Dataset created: {dataset['id']}")
  print(f"Name: {dataset['name']}")
  print(f"Files uploaded: {len(dataset['files'])}")
  print(f"Total size: {dataset['size']} bytes")
  ```

  ```python Python (URLs Only) theme={null}
  import requests
  import json

  url = " https://api.4minds.ai/api/v1/user/dataset"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  # Create dataset from URLs
  urls_to_scrape = [
      "https://docs.example.com/page1",
      "https://docs.example.com/page2",
      "https://blog.example.com/article"
  ]

  data = {
      'urls': json.dumps(urls_to_scrape),
      'dataset_name': 'Documentation Dataset',
      'description': 'Training data from documentation pages',
      'tags': 'docs,web,scraping'
  }

  response = requests.post(url, headers=headers, data=data)
  dataset = response.json()

  print(f"Dataset created: {dataset['id']}")
  print(f"Name: {dataset['name']}")
  print(f"URLs added: {len(dataset.get('urls', []))}")
  print(f"Status: {dataset['status']} (URLs will be scraped in background)")
  ```

  ```python Python (Files + URLs) theme={null}
  import requests
  import json

  url = " https://api.4minds.ai/api/v1/user/dataset"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  # Upload files AND URLs in one dataset
  files = [
      ('files', ('training_data.jsonl', open('training_data.jsonl', 'rb'), 'application/x-jsonlines'))
  ]

  urls_to_scrape = [
      "https://docs.example.com/api",
      "https://blog.example.com/tutorial"
  ]

  data = {
      'urls': json.dumps(urls_to_scrape),
      'dataset_name': 'Mixed Dataset',
      'description': 'Training data from files and web sources',
      'tags': 'mixed,training,web'
  }

  response = requests.post(url, headers=headers, files=files, data=data)
  dataset = response.json()

  print(f"Dataset created: {dataset['id']}")
  print(f"Files uploaded: {len(dataset['files'])}")
  print(f"URLs added: {len(dataset.get('urls', []))}")
  print(f"Status: {dataset['status']}")
  ```

  ```javascript JavaScript (Files Only) theme={null}
  // Browser-based file upload
  const fileInput = document.getElementById('file-input');
  const files = fileInput.files;

  const formData = new FormData();

  // Add all selected files
  for (let i = 0; i < files.length; i++) {
    formData.append('files', files[i]);
  }

  // Add metadata
  formData.append('dataset_name', 'Customer Support Dataset');
  formData.append('description', 'Training data for customer support bot');
  formData.append('tags', 'support,training,chatbot');

  const response = await fetch(' https://api.4minds.ai/api/v1/user/dataset', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: formData
  });

  const dataset = await response.json();
  console.log(`Dataset created: ${dataset.id}`);
  console.log(`Name: ${dataset.name}`);
  console.log(`Files uploaded: ${dataset.files.length}`);
  ```

  ```javascript JavaScript (URLs Only) theme={null}
  // Create dataset from URLs
  const urls = [
    'https://docs.example.com/page1',
    'https://docs.example.com/page2',
    'https://blog.example.com/article'
  ];

  const formData = new FormData();
  formData.append('urls', JSON.stringify(urls));
  formData.append('dataset_name', 'Documentation Dataset');
  formData.append('description', 'Training data from documentation pages');
  formData.append('tags', 'docs,web,scraping');

  const response = await fetch(' https://api.4minds.ai/api/v1/user/dataset', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: formData
  });

  const dataset = await response.json();
  console.log(`Dataset created: ${dataset.id}`);
  console.log(`URLs added: ${dataset.urls?.length || 0}`);
  console.log(`Status: ${dataset.status} (URLs will be scraped in background)`);
  ```

  ```javascript JavaScript (Files + URLs) theme={null}
  // Upload files AND URLs in one dataset
  const fileInput = document.getElementById('file-input');
  const files = fileInput.files;

  const urls = [
    'https://docs.example.com/api',
    'https://blog.example.com/tutorial'
  ];

  const formData = new FormData();

  // Add files
  for (let i = 0; i < files.length; i++) {
    formData.append('files', files[i]);
  }

  // Add URLs
  formData.append('urls', JSON.stringify(urls));
  formData.append('dataset_name', 'Mixed Dataset');
  formData.append('description', 'Training data from files and web sources');
  formData.append('tags', 'mixed,training,web');

  const response = await fetch(' https://api.4minds.ai/api/v1/user/dataset', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: formData
  });

  const dataset = await response.json();
  console.log(`Dataset created: ${dataset.id}`);
  console.log(`Files uploaded: ${dataset.files.length}`);
  console.log(`URLs added: ${dataset.urls?.length || 0}`);
  ```

  ```javascript Node.js (Files Only) theme={null}
  const fs = require('fs');
  const FormData = require('form-data');
  const https = require('https');

  const form = new FormData();

  // Add multiple files
  form.append('files', fs.createReadStream('training_data.jsonl'));
  form.append('files', fs.createReadStream('additional_data.csv'));

  // Add metadata
  form.append('dataset_name', 'Customer Support Dataset');
  form.append('description', 'Training data for customer support bot');
  form.append('tags', 'support,training,chatbot');

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/user/dataset',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      ...form.getHeaders()
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const dataset = JSON.parse(data);
      console.log(`Dataset created: ${dataset.id}`);
      console.log(`Name: ${dataset.name}`);
      console.log(`Files uploaded: ${dataset.files.length}`);
      console.log(`Total size: ${dataset.size} bytes`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  form.pipe(req);
  ```

  ```javascript Node.js (URLs Only) theme={null}
  const FormData = require('form-data');
  const https = require('https');

  const form = new FormData();

  // Add URLs as JSON array
  const urls = [
    'https://docs.example.com/page1',
    'https://docs.example.com/page2',
    'https://blog.example.com/article'
  ];

  form.append('urls', JSON.stringify(urls));
  form.append('dataset_name', 'Documentation Dataset');
  form.append('description', 'Training data from documentation pages');
  form.append('tags', 'docs,web,scraping');

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/user/dataset',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      ...form.getHeaders()
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const dataset = JSON.parse(data);
      console.log(`Dataset created: ${dataset.id}`);
      console.log(`URLs added: ${dataset.urls?.length || 0}`);
      console.log(`Status: ${dataset.status} (URLs will be scraped in background)`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  form.pipe(req);
  ```

  ```javascript Node.js (Files + URLs) theme={null}
  const fs = require('fs');
  const FormData = require('form-data');
  const https = require('https');

  const form = new FormData();

  // Add files
  form.append('files', fs.createReadStream('training_data.jsonl'));

  // Add URLs as JSON array
  const urls = [
    'https://docs.example.com/api',
    'https://blog.example.com/tutorial'
  ];

  form.append('urls', JSON.stringify(urls));
  form.append('dataset_name', 'Mixed Dataset');
  form.append('description', 'Training data from files and web sources');
  form.append('tags', 'mixed,training,web');

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/user/dataset',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      ...form.getHeaders()
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const dataset = JSON.parse(data);
      console.log(`Dataset created: ${dataset.id}`);
      console.log(`Files uploaded: ${dataset.files.length}`);
      console.log(`URLs added: ${dataset.urls?.length || 0}`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  form.pipe(req);
  ```
</CodeGroup>

***

### 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    |

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  import requests

  dataset_id = 123
  url = " https://api.4minds.ai/api/v1/user/dataset/upload"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  # Upload multiple files to existing dataset
  files = [
      ('files', ('training_data.jsonl', open('training_data.jsonl', 'rb'), 'application/x-jsonlines')),
      ('files', ('additional_data.csv', open('additional_data.csv', 'rb'), 'text/csv'))
  ]

  data = {
      'dataset_id': dataset_id
  }

  response = requests.post(url, headers=headers, files=files, data=data)

  if response.status_code == 200:
      result = response.json()
      print(f"Files added successfully to dataset {dataset_id}")
      print(f"Files uploaded: {result['files_uploaded']}")
      print(f"Total files: {result['total_files']}")
  ```

  ```javascript JavaScript theme={null}
  const datasetId = 123;
  const fileInput = document.getElementById('file-input');
  const files = fileInput.files;

  const formData = new FormData();

  // Add dataset ID
  formData.append('dataset_id', datasetId);

  // Add all selected files
  for (let i = 0; i < files.length; i++) {
    formData.append('files', files[i]);
  }

  const response = await fetch(' https://api.4minds.ai/api/v1/user/dataset/upload', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: formData
  });

  if (response.ok) {
    const result = await response.json();
    console.log(`Files added successfully to dataset ${datasetId}`);
    console.log(`Files uploaded: ${result.files_uploaded}`);
    console.log(`Total files: ${result.total_files}`);
  }
  ```

  ```javascript Node.js theme={null}
  const fs = require('fs');
  const FormData = require('form-data');
  const https = require('https');

  const datasetId = 123;
  const form = new FormData();

  // Add dataset ID
  form.append('dataset_id', datasetId);

  // Add multiple files
  form.append('files', fs.createReadStream('training_data.jsonl'));
  form.append('files', fs.createReadStream('additional_data.csv'));

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/user/dataset/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      ...form.getHeaders()
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      if (res.statusCode === 200) {
        const result = JSON.parse(data);
        console.log(`Files added successfully to dataset ${datasetId}`);
        console.log(`Files uploaded: ${result.files_uploaded}`);
        console.log(`Total files: ${result.total_files}`);
      }
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  form.pipe(req);
  ```
</CodeGroup>

***

### 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) |

<CodeGroup>
  ```bash cURL (Soft Delete) theme={null}
  curl -X DELETE  https://api.4minds.ai/api/v1/user/dataset/123 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (Permanent Delete) theme={null}
  curl -X DELETE " https://api.4minds.ai/api/v1/user/dataset/123?permanent=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python (Soft Delete) theme={null}
  import requests

  dataset_id = 123
  url = f" https://api.4minds.ai/api/v1/user/dataset/{dataset_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.delete(url, headers=headers)

  if response.status_code == 200:
      print(f"Dataset {dataset_id} moved to trash")
  else:
      print(f"Error: {response.status_code}")
  ```

  ```python Python (Permanent Delete) theme={null}
  import requests

  dataset_id = 123
  url = f" https://api.4minds.ai/api/v1/user/dataset/{dataset_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }
  params = {
      "permanent": True
  }

  response = requests.delete(url, headers=headers, params=params)

  if response.status_code == 200:
      print(f"Dataset {dataset_id} permanently deleted")
  else:
      print(f"Error: {response.status_code}")
  ```

  ```javascript JavaScript (Soft Delete) theme={null}
  const datasetId = 123;
  const response = await fetch(` https://api.4minds.ai/api/v1/user/dataset/${datasetId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  if (response.ok) {
    console.log(`Dataset ${datasetId} moved to trash`);
  } else {
    console.error(`Error: ${response.status}`);
  }
  ```

  ```javascript JavaScript (Permanent Delete) theme={null}
  const datasetId = 123;
  const response = await fetch(` https://api.4minds.ai/api/v1/user/dataset/${datasetId}?permanent=true`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  if (response.ok) {
    console.log(`Dataset ${datasetId} permanently deleted`);
  } else {
    console.error(`Error: ${response.status}`);
  }
  ```

  ```javascript Node.js (Soft Delete) theme={null}
  const https = require('https');

  const datasetId = 123;

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/user/dataset/${datasetId}`,
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    if (res.statusCode === 200) {
      console.log(`Dataset ${datasetId} moved to trash`);
    } else {
      console.error(`Error: ${res.statusCode}`);
    }
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```

  ```javascript Node.js (Permanent Delete) theme={null}
  const https = require('https');

  const datasetId = 123;

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/user/dataset/${datasetId}?permanent=true`,
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    if (res.statusCode === 200) {
      console.log(`Dataset ${datasetId} permanently deleted`);
    } else {
      console.error(`Error: ${res.statusCode}`);
    }
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

## 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) |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET " https://api.4minds.ai/api/v1/evaluations?page=1&per_page=20" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  url = " https://api.4minds.ai/api/v1/evaluations"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }
  params = {
      "page": 1,
      "per_page": 20,
      "status": "completed"  # Optional: pending, running, completed, failed
  }

  response = requests.get(url, headers=headers, params=params)
  evaluations = response.json()

  for eval in evaluations['evaluations']:
      print(f"Evaluation: {eval['name']} - Score: {eval['score']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(' https://api.4minds.ai/api/v1/evaluations?page=1&per_page=20', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  data.evaluations.forEach(eval => {
    console.log(`Evaluation: ${eval.name} - Score: ${eval.score}`);
  });
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/evaluations?page=1&per_page=20',
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const result = JSON.parse(data);
      result.evaluations.forEach(eval => {
        console.log(`Evaluation: ${eval.name} - Score: ${eval.score}`);
      });
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  import requests

  url = " https://api.4minds.ai/api/v1/evaluations"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  data = {
      "name": "GPT-4 RAGAS Evaluation",
      "description": "Evaluate GPT-4 on BEIR dataset",
      "type": "ragas",
      "model_id": 123,
      "benchmark_type": "beir",
      "question_count": 700
  }

  response = requests.post(url, headers=headers, json=data)
  evaluation = response.json()

  print(f"Created evaluation: {evaluation['name']}")
  print(f"Evaluation ID: {evaluation['id']}")
  print(f"Status: {evaluation['status']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(' https://api.4minds.ai/api/v1/evaluations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'GPT-4 RAGAS Evaluation',
      description: 'Evaluate GPT-4 on BEIR dataset',
      type: 'ragas',
      model_id: 123,
      benchmark_type: 'beir',
      question_count: 700
    })
  });

  const evaluation = await response.json();
  console.log(`Created evaluation: ${evaluation.name}`);
  console.log(`Evaluation ID: ${evaluation.id}`);
  console.log(`Status: ${evaluation.status}`);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const data = JSON.stringify({
    name: 'GPT-4 RAGAS Evaluation',
    description: 'Evaluate GPT-4 on BEIR dataset',
    type: 'ragas',
    model_id: 123,
    benchmark_type: 'beir',
    question_count: 700
  });

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/evaluations',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Content-Length': data.length
    }
  };

  const req = https.request(options, (res) => {
    let responseData = '';
    
    res.on('data', (chunk) => {
      responseData += chunk;
    });
    
    res.on('end', () => {
      const evaluation = JSON.parse(responseData);
      console.log(`Created evaluation: ${evaluation.name}`);
      console.log(`Evaluation ID: ${evaluation.id}`);
      console.log(`Status: ${evaluation.status}`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.write(data);
  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET  https://api.4minds.ai/api/v1/evaluations/456 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  evaluation_id = 456
  url = f" https://api.4minds.ai/api/v1/evaluations/{evaluation_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  evaluation = response.json()

  print(f"Evaluation: {evaluation['name']}")
  print(f"Status: {evaluation['status']}")
  print(f"Score: {evaluation['score']}")
  if evaluation.get('results'):
      print(f"Scores: {evaluation['results']['scores']}")
  ```

  ```javascript JavaScript theme={null}
  const evaluationId = 456;
  const response = await fetch(` https://api.4minds.ai/api/v1/evaluations/${evaluationId}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const evaluation = await response.json();
  console.log(`Evaluation: ${evaluation.name}`);
  console.log(`Status: ${evaluation.status}`);
  console.log(`Score: ${evaluation.score}`);
  if (evaluation.results) {
    console.log('Scores:', evaluation.results.scores);
  }
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const evaluationId = 456;

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/evaluations/${evaluationId}`,
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const evaluation = JSON.parse(data);
      console.log(`Evaluation: ${evaluation.name}`);
      console.log(`Status: ${evaluation.status}`);
      console.log(`Score: ${evaluation.score}`);
      if (evaluation.results) {
        console.log('Scores:', evaluation.results.scores);
      }
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST  https://api.4minds.ai/api/v1/evaluations/456/start \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  evaluation_id = 456
  url = f" https://api.4minds.ai/api/v1/evaluations/{evaluation_id}/start"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.post(url, headers=headers)
  result = response.json()

  print(result['message'])
  ```

  ```javascript JavaScript theme={null}
  const evaluationId = 456;
  const response = await fetch(` https://api.4minds.ai/api/v1/evaluations/${evaluationId}/start`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const result = await response.json();
  console.log(result.message);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const evaluationId = 456;

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/evaluations/${evaluationId}/start`,
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const result = JSON.parse(data);
      console.log(result.message);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### 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.

<CodeGroup>
  ```bash cURL theme={null}
  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": []
    }'
  ```

  ```python Python theme={null}
  import requests

  evaluation_id = 456
  url = f" https://api.4minds.ai/api/v1/evaluations/{evaluation_id}/run-ragas"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  data = {
      "samples": [],
      "selected_questions": []
  }

  response = requests.post(url, headers=headers, json=data)
  evaluation = response.json()

  print(f"Evaluation completed: {evaluation['name']}")
  print(f"Score: {evaluation['score']}")
  print(f"Metrics: {evaluation['results']['scores']}")
  ```

  ```javascript JavaScript theme={null}
  const evaluationId = 456;
  const response = await fetch(` https://api.4minds.ai/api/v1/evaluations/${evaluationId}/run-ragas`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      samples: [],
      selected_questions: []
    })
  });

  const evaluation = await response.json();
  console.log(`Evaluation completed: ${evaluation.name}`);
  console.log(`Score: ${evaluation.score}`);
  console.log('Metrics:', evaluation.results.scores);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const evaluationId = 456;
  const data = JSON.stringify({
    samples: [],
    selected_questions: []
  });

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/evaluations/${evaluationId}/run-ragas`,
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Content-Length': data.length
    }
  };

  const req = https.request(options, (res) => {
    let responseData = '';
    
    res.on('data', (chunk) => {
      responseData += chunk;
    });
    
    res.on('end', () => {
      const evaluation = JSON.parse(responseData);
      console.log(`Evaluation completed: ${evaluation.name}`);
      console.log(`Score: ${evaluation.score}`);
      console.log('Metrics:', evaluation.results.scores);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.write(data);
  req.end();
  ```
</CodeGroup>

***

### 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             |

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  evaluation_id = 456
  url = f" https://api.4minds.ai/api/v1/evaluations/{evaluation_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  data = {
      "name": "Updated Evaluation Name",
      "description": "Updated description"
  }

  response = requests.put(url, headers=headers, json=data)
  evaluation = response.json()

  print(f"Updated evaluation: {evaluation['name']}")
  ```

  ```javascript JavaScript theme={null}
  const evaluationId = 456;
  const response = await fetch(` https://api.4minds.ai/api/v1/evaluations/${evaluationId}`, {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Updated Evaluation Name',
      description: 'Updated description'
    })
  });

  const evaluation = await response.json();
  console.log(`Updated evaluation: ${evaluation.name}`);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const evaluationId = 456;
  const data = JSON.stringify({
    name: 'Updated Evaluation Name',
    description: 'Updated description'
  });

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/evaluations/${evaluationId}`,
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Content-Length': data.length
    }
  };

  const req = https.request(options, (res) => {
    let responseData = '';
    
    res.on('data', (chunk) => {
      responseData += chunk;
    });
    
    res.on('end', () => {
      const evaluation = JSON.parse(responseData);
      console.log(`Updated evaluation: ${evaluation.name}`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.write(data);
  req.end();
  ```
</CodeGroup>

***

### 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE  https://api.4minds.ai/api/v1/evaluations/456 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  evaluation_id = 456
  url = f" https://api.4minds.ai/api/v1/evaluations/{evaluation_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.delete(url, headers=headers)

  if response.status_code == 200:
      result = response.json()
      print(result['message'])
  else:
      print(f"Error: {response.status_code}")
  ```

  ```javascript JavaScript theme={null}
  const evaluationId = 456;
  const response = await fetch(` https://api.4minds.ai/api/v1/evaluations/${evaluationId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  if (response.ok) {
    const result = await response.json();
    console.log(result.message);
  } else {
    console.error(`Error: ${response.status}`);
  }
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const evaluationId = 456;

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/evaluations/${evaluationId}`,
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      if (res.statusCode === 200) {
        const result = JSON.parse(data);
        console.log(result.message);
      } else {
        console.error(`Error: ${res.statusCode}`);
      }
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

### 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 |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET " https://api.4minds.ai/api/v1/evaluations/check-name?name=My%20Evaluation" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  url = " https://api.4minds.ai/api/v1/evaluations/check-name"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }
  params = {
      "name": "My Evaluation"
  }

  response = requests.get(url, headers=headers, params=params)
  result = response.json()

  print(f"Available: {result['available']}")
  print(f"Message: {result['message']}")
  ```

  ```javascript JavaScript theme={null}
  const name = 'My Evaluation';
  const response = await fetch(` https://api.4minds.ai/api/v1/evaluations/check-name?name=${encodeURIComponent(name)}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const result = await response.json();
  console.log(`Available: ${result.available}`);
  console.log(`Message: ${result.message}`);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const name = 'My Evaluation';

  const options = {
    hostname: 'api.4minds.ai',
    path: `/api/v1/evaluations/check-name?name=${encodeURIComponent(name)}`,
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  };

  const req = https.request(options, (res) => {
    let data = '';
    
    res.on('data', (chunk) => {
      data += chunk;
    });
    
    res.on('end', () => {
      const result = JSON.parse(data);
      console.log(`Available: ${result.available}`);
      console.log(`Message: ${result.message}`);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.end();
  ```
</CodeGroup>

***

## 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             |

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  import requests

  url = " https://api.4minds.ai/api/v1/user/inference"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  data = {
      "query": "What is machine learning?",
      "model_id": 1
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()

  print(result)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(' https://api.4minds.ai/api/v1/user/inference', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: 'What is machine learning?',
      model_id: 1
    })
  });

  const result = await response.json();
  console.log(result);
  ```

  ```javascript Node.js theme={null}
  const https = require('https');

  const data = JSON.stringify({
    query: 'What is machine learning?',
    model_id: 1
  });

  const options = {
    hostname: 'api.4minds.ai',
    path: '/api/v1/user/inference',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Content-Length': data.length
    }
  };

  const req = https.request(options, (res) => {
    let responseData = '';
    
    res.on('data', (chunk) => {
      responseData += chunk;
    });
    
    res.on('end', () => {
      const result = JSON.parse(responseData);
      console.log(result);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.write(data);
  req.end();
  ```
</CodeGroup>

***

## 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

```json theme={null}
{
  "status": "success",
  "data": { ... }
}
```

### Error Response

```json theme={null}
{
  "status": "error",
  "message": "Error description"
}
```

***