4MINDS OpenAI-Compatible API Reference

Note: This API is OpenAI-compatible. You can use the official OpenAI SDK (Python or JavaScript) by pointing base_url / baseURL to https://api.4minds.ai/v1 and providing your 4MINDS API key.

Base URL

https://api.4minds.ai

Models

OpenAI-compatible models API. List, retrieve, and delete your fine-tuned models.

List All Available Models

GET /v1/models List all available models (OpenAI-compatible).

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

Get Model Details

GET /v1/models/{model_id} Get details about a specific model (OpenAI-compatible).

Parameters

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

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

Delete a Model

DELETE /v1/models/{model_id} Delete a fine-tuned model (OpenAI-compatible).

Parameters

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

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

Chat Completions

OpenAI-compatible chat completions with 4minds Constellations extensions. Supports streaming, agent status events, multi-hop planning, and RAG context retrieval. Stored completions can be listed, retrieved, updated, and deleted.

Create a Chat Completion

POST /v1/chat/completions Create a chat completion (OpenAI-compatible with 4minds extensions).

curl -X POST https://api.4minds.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "4minds-model-123",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is machine learning?"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

List Stored Chat Completions

GET /v1/chat/completions List stored chat completions with optional filtering by model.

curl -X GET "https://api.4minds.ai/v1/chat/completions?model=4minds-model-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a Stored Chat Completion

GET /v1/chat/completions/{completion_id} Retrieve a stored chat completion by ID.

Path Parameters

Parameter	Type	Required	Description
completion_id	string	Yes	The unique identifier of the stored completion

curl -X GET https://api.4minds.ai/v1/chat/completions/{completion_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a Stored Chat Completion

POST /v1/chat/completions/{completion_id} Update a stored chat completion (e.g. rename or set metadata).

Path Parameters

Parameter	Type	Required	Description
completion_id	string	Yes	The unique identifier of the stored completion

curl -X POST https://api.4minds.ai/v1/chat/completions/{completion_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title"}'

Delete a Stored Chat Completion

DELETE /v1/chat/completions/{completion_id} Delete a stored chat completion.

Path Parameters

Parameter	Type	Required	Description
completion_id	string	Yes	The unique identifier of the stored completion

curl -X DELETE https://api.4minds.ai/v1/chat/completions/{completion_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

List Messages from a Stored Chat Completion

GET /v1/chat/completions/{completion_id}/messages List messages from a stored chat completion.

Path Parameters

Parameter	Type	Required	Description
completion_id	string	Yes	The unique identifier of the stored completion

curl -X GET https://api.4minds.ai/v1/chat/completions/{completion_id}/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

Files

OpenAI-compatible file management API. Upload, list, retrieve, and delete files for fine-tuning. 4minds extends OpenAI’s single-file upload with multi-file datasets — upload multiple files to a single dataset for training.

Upload a File

POST /v1/files Upload a file for fine-tuning (OpenAI-compatible with multi-file extension). The response includes a dataset_id — use it to upload more files to the same dataset. Optional 4minds form field (JSON string):

Field	Type	Description
dataset_name	string	Custom name for the new dataset
dataset_id	integer	Upload to an existing dataset
training_type	string	`"graph"` (default), `"rl"`, or `"sft"`
model_params	object	Custom hyperparameters, e.g. `{"learning_rate": 0.001}`

Behavior:

Scenario	Result
Omit `4minds` entirely	New dataset with auto-generated name
`dataset_name` only	New dataset with your custom name
`dataset_id` only	Upload to existing dataset
`dataset_id` + `dataset_name`	`dataset_id` takes priority

Note: If the dataset already has a model, training is triggered automatically on upload.

# Standard OpenAI file upload
curl -X POST https://api.4minds.ai/v1/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@training_data.jsonl" \
  -F "purpose=fine-tune"

# With optional 4minds extensions (omit for standard OpenAI behavior)
curl -X POST https://api.4minds.ai/v1/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@training_data.jsonl" \
  -F "purpose=fine-tune" \
  -F '4minds={"dataset_name": "My Training Data", "training_type": "graph"}'

List All Uploaded Files

GET /v1/files List all uploaded files with optional purpose filter (OpenAI-compatible).

curl -X GET "https://api.4minds.ai/v1/files?purpose=fine-tune" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get File Details

GET /v1/files/{file_id} Retrieve details about a specific file (OpenAI-compatible).

Path Parameters

Parameter	Type	Required	Description
file_id	string	Yes	The unique identifier of the file

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

Delete a File

DELETE /v1/files/{file_id} Delete a file (OpenAI-compatible).

Path Parameters

Parameter	Type	Required	Description
file_id	string	Yes	The unique identifier of the file to delete

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

Fine-Tuning

OpenAI-compatible fine-tuning API. Create, monitor, and manage fine-tuning jobs to customize models with your training data.

Note: Training processes ALL files in the dataset, not just the file referenced by training_file. Use external_model_id to deploy to an external model registered via GET /v1/external-models.

Create a Fine-Tuning Job

POST /v1/fine_tuning/jobs Create a fine-tuning job to train a model (OpenAI-compatible). Optionally pass external_model_id to target an external model from a connected integration.

Request Body

Parameter	Type	Required	Description
model	string	Yes	The base model name to fine-tune (e.g. `"Gemma-12B AWQ"`)
training_file	string	Yes	The file ID to use for training
suffix	string	No	Custom suffix for the fine-tuned model name
external_model_id	integer	No	ID of an external model from a connected integration

# Create fine-tuning job — trains ALL files in the dataset
curl -X POST https://api.4minds.ai/v1/fine_tuning/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Gemma-12B AWQ",
    "training_file": "file-abc123def456",
    "suffix": "my-custom-model"
  }'

# With an external model (from connected integrations)
curl -X POST https://api.4minds.ai/v1/fine_tuning/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Gemma-12B AWQ",
    "training_file": "file-abc123def456",
    "suffix": "my-custom-model",
    "external_model_id": 42
  }'

List All Fine-Tuning Jobs

GET /v1/fine_tuning/jobs List all fine-tuning jobs (OpenAI-compatible).

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

Get Fine-Tuning Job Details

GET /v1/fine_tuning/jobs/{job_id} Get fine-tuning job details (OpenAI-compatible).

Path Parameters

Parameter	Type	Required	Description
job_id	string	Yes	The unique identifier of the fine-tuning job

curl -X GET https://api.4minds.ai/v1/fine_tuning/jobs/{job_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

List Fine-Tune Categories

GET /v1/fine-tune-categories List available fine-tune categories for domain-specific prompting (4minds extension).

curl -X GET https://api.4minds.ai/v1/fine-tune-categories \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancel a Fine-Tuning Job

POST /v1/fine_tuning/jobs/{job_id}/cancel Cancel a running fine-tuning job (OpenAI-compatible).

Path Parameters

Parameter	Type	Required	Description
job_id	string	Yes	The unique identifier of the fine-tuning job to cancel

curl -X POST https://api.4minds.ai/v1/fine_tuning/jobs/{job_id}/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Datasets (OpenAI-Compatible Extension)

OpenAI-compatible datasets API. Create, list, retrieve, delete, and import datasets. Datasets group training files together for fine-tuning jobs. You can also import datasets directly from connected integrations.

List All Datasets

GET /v1/datasets List all datasets with their file counts and status.

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

# Example response:
# {
#   "object": "list",
#   "data": [
#     {
#       "id": 1234,
#       "name": "Medical Research Data",
#       "file_count": 3,
#       "total_bytes": 524288,
#       "status": "ready",
#       "created_at": "2025-03-01T12:00:00Z"
#     }
#   ]
# }

Create a New Dataset

POST /v1/datasets Create a new empty dataset to group training files.

curl -X POST https://api.4minds.ai/v1/datasets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Dataset"}'

Import a Dataset

POST /v1/datasets/import Import a dataset directly from a connected integration (e.g. Databricks, S3, Azure Blob).

curl -X POST https://api.4minds.ai/v1/datasets/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "your-integration-id",
    "source_path": "s3://your-bucket/your-data/"
  }'

Get Dataset Details

GET /v1/datasets/{id} Get details of a specific dataset including its files.

Path Parameters

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

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

Delete a Dataset

DELETE /v1/datasets/{id} Delete a dataset and optionally its associated files.

Path Parameters

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

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

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.

OpenAI SDK Quick Setup

Since this API is OpenAI-compatible, you can use the official OpenAI SDK by setting the base_url to https://api.4minds.ai/v1:

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.4minds.ai/v1"
)

JavaScript / Node.js

import OpenAI from 'openai'; // or: const OpenAI = require('openai');

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.4minds.ai/v1'
});

Response Format

All responses are returned in JSON format and follow OpenAI-compatible response structures.

Success Response

{
  "object": "list",
  "data": [ ... ]
}

Error Response

{
  "error": {
    "message": "Error description",
    "type": "invalid_request_error",
    "code": "error_code"
  }
}

​Base URL

​Models

​List All Available Models

​Get Model Details

​Parameters

​Delete a Model

​Parameters

​Chat Completions

​Create a Chat Completion

​List Stored Chat Completions

​Get a Stored Chat Completion

​Path Parameters

​Update a Stored Chat Completion

​Path Parameters

​Delete a Stored Chat Completion

​Path Parameters

​List Messages from a Stored Chat Completion

​Path Parameters

​Files

​Upload a File

​List All Uploaded Files

​Get File Details

​Path Parameters

​Delete a File

​Path Parameters

​Fine-Tuning

​Create a Fine-Tuning Job

​Request Body

​List All Fine-Tuning Jobs

​Get Fine-Tuning Job Details

​Path Parameters

​List Fine-Tune Categories

​Cancel a Fine-Tuning Job

​Path Parameters

​Datasets (OpenAI-Compatible Extension)

​List All Datasets

​Create a New Dataset

​Import a Dataset

​Get Dataset Details

​Path Parameters

​Delete a Dataset

​Path Parameters

​Authentication

​OpenAI SDK Quick Setup

​Response Format

​Success Response

​Error Response

Base URL

Models

List All Available Models

Get Model Details

Parameters

Delete a Model

Parameters

Chat Completions

Create a Chat Completion

List Stored Chat Completions

Get a Stored Chat Completion

Path Parameters

Update a Stored Chat Completion

Path Parameters

Delete a Stored Chat Completion

Path Parameters

List Messages from a Stored Chat Completion

Path Parameters

Files

Upload a File

List All Uploaded Files

Get File Details

Path Parameters

Delete a File

Path Parameters

Fine-Tuning

Create a Fine-Tuning Job

Request Body

List All Fine-Tuning Jobs

Get Fine-Tuning Job Details

Path Parameters

List Fine-Tune Categories

Cancel a Fine-Tuning Job

Path Parameters

Datasets (OpenAI-Compatible Extension)

List All Datasets

Create a New Dataset

Import a Dataset

Get Dataset Details

Path Parameters

Delete a Dataset

Path Parameters

Authentication

OpenAI SDK Quick Setup

Response Format

Success Response

Error Response