MindsHub

https://docs.mindshub.ai
Admin
This project provides comprehensive documentation covering API details, setup instructions, use...
Tokens:14,807
Snippets:158
Trust Score:5.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Copy Example Development Environment File

Source: https://docs.mindshub.ai/setup.html

Copy the example development environment file to start configuring your local setup. This is the first step to setting up module branches.

```bash
cp dev.env.example dev.env      # then set REF=feat/my-thing (or per-module API_REF=…)
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://docs.mindshub.ai/setup.html

Clones the Minds Platform repository with all submodules and runs the 'make setup' command to install frontend and backend dependencies. This command synchronizes Python packages using 'uv sync'.

```bash
git clone --recurse-submodules https://github.com/mindsdb/minds-platform.git
cd minds-platform
make setup
```

--------------------------------

### Build and Run Docker Images

Source: https://docs.mindshub.ai/setup.html

Builds both the API and web Docker images and then starts the entire Docker stack. Ensure you have Docker installed and configured.

```bash
make docker-build
make docker-up
```

--------------------------------

### Start Web App Development Environment

Source: https://docs.mindshub.ai/setup.html

Starts the FastAPI backend and the Vite dev server for the web application with BUILD_TARGET set to 'web'. The browser will open automatically. An API key may be required.

```bash
make dev-web
```

--------------------------------

### Start Desktop App Development Environment

Source: https://docs.mindshub.ai/setup.html

Starts the FastAPI backend with hot reload and the Electron renderer with TypeScript watch and Vite HMR. Press Ctrl-C to shut down.

```bash
make dev
```

--------------------------------

### Start Desktop App with DevTools Enabled

Source: https://docs.mindshub.ai/setup.html

Starts the development environment for the desktop app with the Anton DevTools enabled. Set the ANTON_OPEN_DEVTOOLS environment variable before running.

```bash
ANTON_OPEN_DEVTOOLS=1 make dev
```

--------------------------------

### Install uv Package Manager

Source: https://docs.mindshub.ai/setup.html

Installs the 'uv' Python package manager using a curl script. Ensure Node.js, Python 3.12+, and make are installed beforehand.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Create Project using cURL

Source: https://docs.mindshub.ai/api.html

Example of creating a new project using a cURL command. It specifies the project name, description, and connector IDs.

```curl
curl -X POST http://localhost:26866/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"Sales Automation","description":"Weekly reporting flows","connector_ids":["conn_001"]}'
```

--------------------------------

### List All Skills

Source: https://docs.mindshub.ai/api.html

Use this endpoint to retrieve a list of all available skills. No specific setup is required beyond having skills registered.

```curl
curl "http://localhost:26866/api/v1/skills"
```

--------------------------------

### Run Docker Compose with API Key

Source: https://docs.mindshub.ai/setup.html

Starts the Docker stack while passing an Anthropic API key as an environment variable. Replace 'sk-ant-...' with your actual API key.

```bash
ANTON_ANTHROPIC_API_KEY=sk-ant-... docker compose up --build
```

--------------------------------

### Start OAuth Flow

Source: https://docs.mindshub.ai/api.html

Initiates the OAuth 2.0 authorization flow for a given connector spec. Returns a redirect URL.

```APIDOC
## GET /connectors/oauth/{spec}/start Start OAuth 2.0 flow

### Description
Initiates the OAuth 2.0 authorization flow for a given connector spec. Returns a redirect URL. Send the user's browser there; after authorization the platform receives the callback and stores the token automatically.

### Method
GET

### Endpoint
/connectors/oauth/{spec}/start

### Parameters
#### Path Parameters
- **spec** (string) - Required - The connector spec ID (e.g. `google-sheets`, `notion`).
```

--------------------------------

### Start OAuth 2.0 Flow using cURL

Source: https://docs.mindshub.ai/api.html

Initiates the OAuth 2.0 authorization flow for a given connector spec. The response provides a redirect URL for the user to authorize the connection.

```curl
curl "http://localhost:26866/api/v1/connectors/oauth/{spec}/start"
```

--------------------------------

### GET /responses/in-flight-list

Source: https://docs.mindshub.ai/api.html

Lists all currently active, in-flight AI response streams. Can be filtered by conversation ID.

```APIDOC
## GET /responses/in-flight-list

### Description
Lists all currently active, in-flight AI response streams. Can be filtered by conversation ID.

### Method
GET

### Endpoint
/api/v1/responses/in-flight-list

### Parameters
#### Query Parameters
- **conversation_id** (string) - Optional - Filter to a specific conversation.

### Response
#### Success Response (200)
- (Response structure not explicitly defined in source, but implies a list of active streams)

#### Response Example
(No example provided in source)
```

--------------------------------

### Get a scratchpad

Source: https://docs.mindshub.ai/api.html

Retrieves a specific scratchpad, including all of its cells. This is used to display the content of a scratchpad to the user.

```APIDOC
## GET /scratchpads/{scratchpad_id}

### Description
Retrieves a specific scratchpad and all its associated cells.

### Method
GET

### Endpoint
/api/v1/scratchpads/{scratchpad_id}

### Parameters
#### Path Parameters
- **scratchpad_id** (string) - Required - The ID of the scratchpad to retrieve.
```

--------------------------------

### GET /responses/in-flight

Source: https://docs.mindshub.ai/api.html

Checks the status of a specific in-flight AI response stream using its conversation ID.

```APIDOC
## GET /responses/in-flight

### Description
Checks the status of a specific in-flight AI response stream using its conversation ID.

### Method
GET

### Endpoint
/api/v1/responses/in-flight

### Parameters
#### Query Parameters
- **conversation_id** (string) - Required - Conversation whose active stream to retrieve.

### Response
#### Success Response (200)
- (Response structure not explicitly defined in source, but implies details of a specific in-flight stream)

#### Response Example
(No example provided in source)
```

--------------------------------

### Get Conversation

Source: https://docs.mindshub.ai/api.html

Retrieves a specific conversation by its ID.

```APIDOC
## GET /conversations/{id}

### Description
Retrieves a specific conversation by its ID.

### Method
GET

### Endpoint
/conversations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Conversation ID.
```

--------------------------------

### Get Conversation Items

Source: https://docs.mindshub.ai/api.html

Retrieves the ordered list of messages within a specific conversation. Supports cursor-based pagination.

```APIDOC
## GET /conversations/{id}/items

### Description
Retrieves the ordered list of messages within a specific conversation. Supports cursor-based pagination.

### Method
GET

### Endpoint
/conversations/{id}/items

### Parameters
#### Path Parameters
- **id** (string) - Required - Conversation ID.

#### Query Parameters
- **limit** (integer) - Optional - Default `100`.
- **before** (string) - Optional - Return items before this item ID (cursor pagination).
```

--------------------------------

### Create Project

Source: https://docs.mindshub.ai/api.html

Creates a new project with specified details. Requires a name and can optionally include a description and connector/skill IDs.

```APIDOC
## POST /projects

### Description
Creates a new project. The `name` is mandatory, while `description`, `connector_ids`, and `skill_ids` are optional.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **name** (string) - Required - Display name for the project.
- **description** (string) - Optional - Short description shown in the UI.
- **connector_ids** (string[]) - Optional - Data source connections available within this project.
- **skill_ids** (string[]) - Optional - Global skills to activate for all conversations in this project.

### Request Example
```json
{
  "name": "Sales Automation",
  "description": "Weekly reporting flows",
  "connector_ids": ["conn_001"]
}
```
```

--------------------------------

### Reset Development Environment to Pre-Install State

Source: https://docs.mindshub.ai/setup.html

Use 'make flush' to uninstall local runtimes and delete all application state, including conversations and provider keys. This command prompts for confirmation unless FORCE=1 is used.

```bash
make flush          # prompts before wiping
```

```bash
make flush FORCE=1  # no prompt (CI / scripts)
```

--------------------------------

### Serve Artifact File

Source: https://docs.mindshub.ai/api.html

Serves a raw file content for a specific artifact within a project.

```APIDOC
## GET /artifacts/serve/{project_id}/{path}

### Description
Serves the raw content of a file belonging to an artifact. This is useful for accessing artifact assets directly.

### Method
GET

### Endpoint
/artifacts/serve/{project_id}/{path}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project containing the artifact.
- **path** (string) - Required - The file path within the artifact (e.g., `index.html` or `assets/chart.js`).
```

--------------------------------

### Open Artifact

Source: https://docs.mindshub.ai/api.html

Opens a specified artifact in the desktop shell environment.

```APIDOC
## POST /artifacts/open

### Description
Opens a given artifact within the desktop application's window.

### Method
POST

### Endpoint
/artifacts/open

### Parameters
#### Request Body
- **artifact_id** (string) - Required - The unique identifier of the artifact to open.
```

--------------------------------

### Create Schedule

Source: https://docs.mindshub.ai/api.html

Creates a new schedule for a project. Requires project ID, cron expression, and a prompt.

```APIDOC
## POST /schedules Create a schedule

### Description
Creates a new schedule for a project. Requires project ID, cron expression, and a prompt.

### Method
POST

### Endpoint
/schedules

### Parameters
#### Request Body
- **project_id** (string) - Required - Project this schedule belongs to.
- **cron** (string) - Required - Standard 5-field cron expression, e.g. "0 9 * * 1" = every Monday at 09:00.
- **prompt** (string) - Required - Task the agent runs at each scheduled time.
- **timezone** (string) - Optional - IANA timezone. Default `UTC`.
- **conversation_id** (string) - Optional - Append each run to an existing conversation. If omitted, a new conversation is created per run.

### Request Example
```json
{
  "project_id": "proj_xyz",
  "cron": "0 9 * * 1",
  "prompt": "Generate weekly sales digest",
  "timezone": "America/New_York"
}
```
```

--------------------------------

### List Available Connector Specs using cURL

Source: https://docs.mindshub.ai/api.html

This cURL command retrieves a list of all available connector specifications that can be used to integrate external data sources.

```curl
curl "http://localhost:26866/api/v1/connectors/specs"
```

--------------------------------

### Create Memory

Source: https://docs.mindshub.ai/api.html

Creates a new memory. You can specify a `project_id` to scope the memory to a particular project, or omit it to create a global memory.

```APIDOC
## POST /memories Create a memory

### Description
Creates a new memory. You can specify a `project_id` to scope the memory to a particular project, or omit it to create a global memory.

### Method
POST

### Endpoint
/api/v1/memories

### Parameters
#### Request Body
- **content** (string) - Required - The fact or preference to remember. Plain text.
- **project_id** (string) - Optional - Scope to a project. Omit for a global memory.

### Request Example
```bash
curl -X POST "http://localhost:26866/api/v1/memories" \
  -H "Content-Type: application/json" \
  -d '{"content": "Always use Q3 targets as the baseline.", "project_id": "proj_xyz"}'
```
```

--------------------------------

### Create a Schedule

Source: https://docs.mindshub.ai/api.html

Use this cURL command to create a new schedule. Ensure you provide the project ID, cron expression, and prompt. Timezone is optional and defaults to UTC.

```curl
curl -X POST http://localhost:26866/api/v1/schedules \
  -H "Content-Type: application/json" \
  -d '{"project_id":"proj_xyz","cron":"0 9 * * 1","prompt":"Generate weekly sales digest","timezone":"America/New_York"}'
```

--------------------------------

### Create a Connection using cURL

Source: https://docs.mindshub.ai/api.html

Use this cURL command to create a new connection to an external data source. Provide the spec ID, a name, and the required credentials.

```curl
curl -X POST "http://localhost:26866/api/v1/connectors/connections" \
  -H "Content-Type: application/json" \
  -d '{
    "spec_id": "postgres",
    "name": "prod-db",
    "credentials": {
      "host": "db.example.com",
      "port": 5432,
      "database": "analytics",
      "user": "reader",
      "password": "s3cr3t"
    }
  }'
```

--------------------------------

### List all skills

Source: https://docs.mindshub.ai/api.html

Retrieves a list of all available skills. This is useful for discovering existing capabilities.

```APIDOC
## GET /skills

### Description
Retrieves a list of all available skills.

### Method
GET

### Endpoint
/api/v1/skills

### Response
#### Success Response (200)
- **skills** (array) - A list of skill objects.
```

--------------------------------

### Register a New Skill

Source: https://docs.mindshub.ai/api.html

Register a new skill by sending a POST request with the skill's details. The `name` field is a required kebab-case identifier used for invocation.

```curl
curl -X POST "http://localhost:26866/api/v1/skills" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-report",
    "description": "Generates a weekly performance report.",
    "instructions": "Always start with an executive summary. Limit to 3 charts.",
    "tools": ["sql_query", "send_email"]
  }'
```

--------------------------------

### List Projects

Source: https://docs.mindshub.ai/api.html

Retrieves a list of all projects. Supports filtering and pagination.

```APIDOC
## GET /projects

### Description
Lists all projects available in the system. You can control the number of results returned using `limit` and `offset` query parameters.

### Method
GET

### Endpoint
/projects

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Default `50`. The maximum number of projects to return.
- **offset** (integer) - Optional - Default `0`. The number of projects to skip before starting to collect the result set.
```

--------------------------------

### Create a scratchpad

Source: https://docs.mindshub.ai/api.html

Creates a new scratchpad within a conversation. Scratchpads can be initialized with a title and an empty list of cells.

```APIDOC
## POST /scratchpads

### Description
Creates a new scratchpad for a conversation.

### Method
POST

### Endpoint
/api/v1/scratchpads

### Parameters
#### Request Body
- **conversation_id** (string) - Required - The ID of the conversation this scratchpad belongs to.
- **title** (string) - Required - The title of the new scratchpad.
- **cells** (array) - Optional - An array of initial cell objects. Defaults to an empty array if not provided.
```

--------------------------------

### List Connector Specs

Source: https://docs.mindshub.ai/api.html

Retrieves a list of available connector specifications.

```APIDOC
## GET /connectors/specs List available connector specs

### Description
Retrieves a list of available connector specifications.

### Method
GET

### Endpoint
/connectors/specs

### Request Example
```curl
curl "http://localhost:26866/api/v1/connectors/specs"
```
```

--------------------------------

### Create a Global Memory

Source: https://docs.mindshub.ai/api.html

Use this cURL command to create a new global memory. Omit the `project_id` in the JSON body for global scope.

```bash
curl -X POST "http://localhost:26866/api/v1/memories" \
  -H "Content-Type: application/json" \
  -d '{"content": "Always use Q3 targets as the baseline.", "project_id": "proj_xyz"}'
```

--------------------------------

### Project Object Structure

Source: https://docs.mindshub.ai/api.html

Defines the structure of a project object, including its ID, name, description, associated connector and skill IDs, and creation/update timestamps.

```json
{
  "id":             "proj_abc123",
  "name":           "Sales Automation",
  "description":    "Weekly reporting flows",
  "connector_ids":  ["conn_001", "conn_002"],
  "skill_ids":      ["skill_abc"],
  "created_at":     "2026-06-11T10:00:00Z",
  "updated_at":     "2026-06-11T10:00:00Z"
}
```

--------------------------------

### Create Connection

Source: https://docs.mindshub.ai/api.html

Creates a new connection to an external data source using a specified connector spec and credentials.

```APIDOC
## POST /connectors/connections Create a connection

### Description
Creates a new connection to an external data source using a specified connector spec and credentials.

### Method
POST

### Endpoint
/connectors/connections

### Parameters
#### Request Body
- **spec_id** (string) - Required - The connector spec to use (e.g. `"postgres"`).
- **name** (string) - Required - Human-readable label for this connection.
- **credentials** (object) - Required - Key-value map of credential fields defined by the spec. Secret fields are encrypted at rest and never returned.

### Request Example
```curl
curl -X POST "http://localhost:26866/api/v1/connectors/connections" \
  -H "Content-Type: application/json" \
  -d 
    {
      "spec_id": "postgres",
      "name": "prod-db",
      "credentials": {
        "host": "db.example.com",
        "port": 5432,
        "database": "analytics",
        "user": "reader",
        "password": "s3cr3t"
      }
    }
```
```

--------------------------------

### List Files

Source: https://docs.mindshub.ai/api.html

Retrieves a list of files. Supports filtering by project ID or conversation ID.

```APIDOC
## GET /files List files

### Description
Retrieves a list of files. Supports filtering by project ID or conversation ID.

### Method
GET

### Endpoint
/files

### Parameters
#### Query Parameters
- **project_id** (string) - Optional - Filter to a project.
- **conversation_id** (string) - Optional - Filter to a conversation.
```

--------------------------------

### Preview Artifact

Source: https://docs.mindshub.ai/api.html

Generates a preview for a specific artifact based on its path and project.

```APIDOC
## GET /artifacts/preview

### Description
Provides a preview of an artifact located at a specified path within a given project.

### Method
GET

### Endpoint
/artifacts/preview

### Parameters
#### Query Parameters
- **path** (string) - Required - The relative path to the artifact file (e.g., `sales_dashboard/index.html`).
- **project_id** (string) - Required - The ID of the project that owns the artifact.
```

--------------------------------

### List Global Memories

Source: https://docs.mindshub.ai/api.html

Use this cURL command to retrieve all global memories. Omit the `project_id` query parameter to fetch global memories.

```bash
curl "http://localhost:26866/api/v1/memories"
```

--------------------------------

### Connection Object Structure

Source: https://docs.mindshub.ai/api.html

Represents an instantiated connection to an external data source. Includes its ID, the spec it uses, name, and current status.

```json
{
  "id":         "conn_abc123",
  "spec_id":    "postgres",       // which ConnectorSpec this uses
  "name":       "prod-db",
  "status":     "connected",      // "connected" | "error" | "pending"
  "created_at": "2026-06-11T10:00:00Z"
  // credentials are never returned
}
```

--------------------------------

### File Object Structure

Source: https://docs.mindshub.ai/api.html

Represents a file managed by the system. Includes metadata such as ID, name, type, size, and associated project or conversation.

```json
{
  "id":              "file_abc123",
  "name":            "Q2-report.pdf",
  "mime_type":       "application/pdf",
  "size":            204800,           // bytes
  "project_id":      "proj_xyz",       // null if conversation-scoped only
  "conversation_id": null,             // null if project-scoped only
  "created_at":      "2026-06-11T10:00:00Z"
}
```

--------------------------------

### Upload a File using cURL

Source: https://docs.mindshub.ai/api.html

Use this cURL command to upload a file to the API. Ensure the file path and project ID are correctly specified.

```curl
curl -X POST http://localhost:26866/api/v1/files \
  -F "file=@Q2-report.pdf" \
  -F "project_id=proj_xyz"
```

--------------------------------

### Create a Conversation

Source: https://docs.mindshub.ai/api.html

Use this cURL command to create a new conversation, optionally attaching it to a project and providing a title and goal.

```curl
curl -X POST http://localhost:26866/api/v1/conversations \
  -H "Content-Type: application/json" \
  -d '{"project_id":"proj_xyz","title":"Q2 analysis","goal":"Analyse Q2 revenue by region"}'
```

--------------------------------

### List Project-Scoped Memories

Source: https://docs.mindshub.ai/api.html

Use this cURL command to retrieve memories specific to a project. Include the `project_id` query parameter to filter by project.

```bash
curl "http://localhost:26866/api/v1/memories?project_id=..."
```

--------------------------------

### Skill Object Structure

Source: https://docs.mindshub.ai/api.html

Defines the schema for a skill object, including its ID, name, description, instructions, and associated tools.

```json
{
  "id":            "skill_abc123",
  "name":          "weekly-report",
  "description":   "Generates a weekly performance report from connected data sources.",
  "instructions":  "Always include a one-paragraph executive summary first. Use bullet points for metrics...",
  "tools": [        // external tool integrations this skill may invoke
    "sql_query",
    "send_email"
  ],
  "created_at":    "2026-06-11T10:00:00Z",
  "updated_at":    "2026-06-11T10:00:00Z"
}
```

--------------------------------

### Create Scratchpad API Request

Source: https://docs.mindshub.ai/api.html

Use this endpoint to create a new scratchpad for a conversation. Requires conversation ID, title, and an initial list of cells (can be empty).

```curl
curl -X POST "http://localhost:26866/api/v1/scratchpads" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"...","title":"Sales analysis draft","cells":[]}'
```

--------------------------------

### Search Workspace Resources

Source: https://docs.mindshub.ai/api.html

Performs a full-text and semantic search across conversations, artifacts, files, and memories. Results are ranked by relevance.

```shell
curl "http://localhost:26866/api/v1/search?q=sales+forecast&project_id=proj_xyz&types=conversation,file&limit=10"
```

--------------------------------

### Scratchpad Object Structure

Source: https://docs.mindshub.ai/api.html

Represents a notebook-style workspace for an agent. It contains an ordered list of cells and metadata.

```json
{
  "id":              "sp_abc123",
  "conversation_id": "conv_xyz",
  "title":           "Sales analysis draft",
  "cells":           [ /* ordered array of Cell objects */ ],
  "saved":           false,     // true once promoted / pinned
  "created_at":      "2026-06-11T10:00:00Z",
  "updated_at":      "2026-06-11T10:04:12Z"
}
```

--------------------------------

### Register a skill

Source: https://docs.mindshub.ai/api.html

Registers a new skill, making it available for use across projects. Skills define custom instructions and tools the agent can utilize.

```APIDOC
## POST /skills

### Description
Registers a new skill. Skills are reusable capabilities that extend the agent's functionality.

### Method
POST

### Endpoint
/api/v1/skills

### Parameters
#### Request Body
- **name** (string) - Required - Kebab-case identifier. Used to invoke the skill from a conversation.
- **description** (string) - Required - Short summary of what this skill does. Shown in the UI and used by the agent to decide whether to invoke it.
- **instructions** (string) - Optional - Detailed prompt injected whenever this skill is active. Explains how to carry out the task, preferred format, constraints, etc.
- **tools** (string[]) - Optional - List of tool identifiers the agent may call when running this skill (e.g. `"sql_query"`, `"send_email"`).

### Request Example
```json
{
  "name": "weekly-report",
  "description": "Generates a weekly performance report.",
  "instructions": "Always start with an executive summary. Limit to 3 charts.",
  "tools": ["sql_query", "send_email"]
}
```

### Response
#### Success Response (200)
- **skill** (object) - The newly created skill object.
```

--------------------------------

### Create a Streaming Response using cURL

Source: https://docs.mindshub.ai/api.html

Use this cURL command to create a streaming response from the Cowork API. Ensure the Content-Type is set to application/json and provide the conversation ID and user input.

```curl
curl -X POST http://localhost:26866/api/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"conv_xyz","input":"Summarise last week\'s sales data","stream":true}'
```

--------------------------------

### List scratchpads for a conversation

Source: https://docs.mindshub.ai/api.html

Retrieves a list of all scratchpads associated with a specific conversation. This is useful for displaying existing scratchpads to the user.

```APIDOC
## GET /scratchpads

### Description
Lists all scratchpads for a given conversation.

### Method
GET

### Endpoint
/api/v1/scratchpads

### Parameters
#### Query Parameters
- **conversation_id** (string) - Required - The ID of the conversation to list scratchpads for.
```

--------------------------------

### Update a skill

Source: https://docs.mindshub.ai/api.html

Updates an existing skill's properties, such as its name, description, instructions, or associated tools.

```APIDOC
## PATCH /skills/{id}

### Description
Updates an existing skill.

### Method
PATCH

### Endpoint
/api/v1/skills/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the skill to update.

#### Request Body
- **name** (string) - Optional - New identifier.
- **description** (string) - Optional - Updated summary.
- **instructions** (string) - Optional - Revised prompt instructions.
- **tools** (string[]) - Optional - Replace the full list of allowed tools.

### Response
#### Success Response (200)
- **skill** (object) - The updated skill object.
```

--------------------------------

### List Schedules

Source: https://docs.mindshub.ai/api.html

Retrieves a list of schedules, with optional filtering by project ID and status.

```APIDOC
## GET /schedules List schedules

### Description
Retrieves a list of schedules, with optional filtering by project ID and status.

### Method
GET

### Endpoint
/schedules

### Parameters
#### Query Parameters
- **project_id** (string) - Optional - Filter to a project.
- **status** (string) - Optional - `active` or `paused`.
```

--------------------------------

### List Connections

Source: https://docs.mindshub.ai/api.html

Retrieves a list of active connections. Supports filtering by connector type.

```APIDOC
## GET /connectors/connections List active connections

### Description
Retrieves a list of active connections. Supports filtering by connector type.

### Method
GET

### Endpoint
/connectors/connections

### Parameters
#### Query Parameters
- **spec_id** (string) - Optional - Filter by connector type (e.g. `postgres`).
```

--------------------------------

### Upload File

Source: https://docs.mindshub.ai/api.html

Uploads a file to be used by the agent. Accepts various file types and can be associated with a project or conversation.

```APIDOC
## POST /files Upload a file

### Description
Uploads a file to be used by the agent. Accepts various file types and can be associated with a project or conversation.

### Method
POST

### Endpoint
/files

### Parameters
#### Request Body
- **file** (file) - Required - The file binary. Accepted: PDF, DOCX, XLSX, CSV, TXT, PNG, JPG, and more.
- **project_id** (string) - Optional - Attach to a project.
- **conversation_id** (string) - Optional - Attach to a conversation. Can be set alongside `project_id`.

### Request Example
```curl
curl -X POST http://localhost:26866/api/v1/files \
  -F "file=@Q2-report.pdf" \
  -F "project_id=proj_xyz"
```
```

--------------------------------

### List Artifacts

Source: https://docs.mindshub.ai/api.html

Retrieves a list of artifacts. Can be filtered by project ID and artifact type.

```APIDOC
## GET /artifacts

### Description
Lists artifacts. You can filter the results by `project_id` and `type`, and control pagination with `limit`.

### Method
GET

### Endpoint
/artifacts

### Parameters
#### Query Parameters
- **project_id** (string) - Optional - Filter artifacts belonging to a specific project.
- **type** (string) - Optional - Filter artifacts by type (`app`, `report`, `doc`, or `dashboard`).
- **limit** (integer) - Optional - Default `50`. The maximum number of artifacts to return.
```

--------------------------------

### List Memories

Source: https://docs.mindshub.ai/api.html

Retrieves a list of memories. You can filter memories by project scope or by the source (user or agent). Omit `project_id` to fetch global memories.

```APIDOC
## GET /memories List memories

### Description
Retrieves a list of memories. You can filter memories by project scope or by the source (user or agent). Omit `project_id` to fetch global memories.

### Method
GET

### Endpoint
/api/v1/memories

### Parameters
#### Query Parameters
- **project_id** (string) - Optional - Return memories scoped to this project. Omit to return global memories.
- **source** (string) - Optional - Filter by who created it: `user` or `agent`.

### Request Example
```bash
curl "http://localhost:26866/api/v1/memories"               # global
curl "http://localhost:26866/api/v1/memories?project_id=..."  # project-scoped
```
```

--------------------------------

### POST /responses

Source: https://docs.mindshub.ai/api.html

Creates a streaming AI response. This endpoint is compatible with the OpenAI Responses API shape and can return server-sent events or a single JSON response.

```APIDOC
## POST /responses

### Description
Creates a streaming AI response. Compatible with the OpenAI Responses API shape. Can return server-sent events or a single JSON response.

### Method
POST

### Endpoint
/api/v1/responses

### Parameters
#### Request Body
- **conversation_id** (string) - Required - ID of the conversation to append the response to.
- **input** (string) - Required - User message text.
- **stream** (boolean) - Optional - Default `true`. Return server-sent events. Set to `false` for a single JSON response.
- **model** (string) - Optional - Override the agent model for this turn. Defaults to the project setting.
- **skill_ids** (string[]) - Optional - Skill IDs to activate for this turn.

### Request Example
```json
{
  "conversation_id": "conv_xyz",
  "input": "Summarise last week's sales data",
  "stream": true
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the response.
- **conversation_id** (string) - The ID of the conversation.
- **input** (string) - The user's input message.
- **output** (array) - The AI's response, can be text or other types.
- **status** (string) - The status of the response generation (e.g., "in_progress", "completed", "failed").
- **model** (string) - The model used for the response.
- **usage** (object) - Token usage details (input_tokens, output_tokens).
- **created_at** (string) - Timestamp of when the response was created.

#### Response Example
```json
{
  "id": "resp_abc123",
  "conversation_id": "conv_xyz",
  "input": "Summarise last week's sales data",
  "output": [{ "type": "text", "text": "Here is the summary..." }],
  "status": "completed",
  "model": "claude-opus-4-8",
  "usage": { "input_tokens": 120, "output_tokens": 340 },
  "created_at": "2026-06-11T10:00:00Z"
}
```
```

--------------------------------

### Artifact Object Structure

Source: https://docs.mindshub.ai/api.html

Defines the structure of an artifact object, including its ID, project ID, title, type, path, and creation/update timestamps.

```json
{
  "id":          "art_abc123",
  "project_id":  "proj_xyz",
  "title":       "Sales Dashboard",
  "type":        "app",      // "app" | "report" | "doc" | "dashboard"
  "path":        "sales_dashboard/index.html",  // relative path within project
  "created_at":  "2026-06-11T10:00:00Z",
  "updated_at":  "2026-06-11T10:00:00Z"
}
```

--------------------------------

### Execute a Code Cell

Source: https://docs.mindshub.ai/api.html

Runs a specified code cell within a scratchpad. Output is streamed via server-sent events, with a terminal event indicating success or error.

```shell
curl -X POST "http://localhost:26866/api/v1/scratchpads/{scratchpad_id}/cells/{cell_id}/run"
```

--------------------------------

### List Scratchpads API Request

Source: https://docs.mindshub.ai/api.html

Use this endpoint to retrieve a list of all scratchpads associated with a specific conversation.

```curl
curl "http://localhost:26866/api/v1/scratchpads?conversation_id=..."
```

--------------------------------

### Search Workspace

Source: https://docs.mindshub.ai/api.html

Performs a full-text and semantic search across conversations, artifacts, files, and memories. Returns ranked results with resource type and excerpt.

```APIDOC
## GET /search

### Description
Searches across the workspace for conversations, artifacts, files, and memories.

### Method
GET

### Endpoint
/api/v1/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query. Supports natural language and keyword matching.
- **project_id** (string) - Optional - Limit results to a single project.
- **types** (string[]) - Optional - Comma-separated list of resource types to include: `conversation`, `artifact`, `file`, `memory`. Defaults to all.
- **limit** (integer) - Optional - Maximum results to return. Defaults to `20`, max `100`.

### Request Example
```
/api/v1/search?q=sales+forecast&project_id=proj_xyz&types=conversation,file&limit=10
```

### Response
#### Success Response (200)
- **results** (array) - A list of search results.
  - **type** (string) - The type of the resource (`conversation`, `artifact`, `file`, `memory`).
  - **id** (string) - The ID of the resource.
  - **title** (string) - The title of the resource.
  - **excerpt** (string) - A short excerpt from the resource.
  - **score** (number) - The relevance score (0-1).
  - **project_id** (string) - The ID of the project the resource belongs to (null for global results).
- **total** (integer) - The total number of results found.
```

--------------------------------

### Connector Spec Object Structure

Source: https://docs.mindshub.ai/api.html

Defines the type and requirements for a connector. Includes authentication type and the fields needed for establishing a connection.

```json
{
  "id":           "postgres",
  "name":         "PostgreSQL",
  "description":  "Connect to any PostgreSQL-compatible database.",
  "auth_type":    "credentials",  // "credentials" | "oauth2"
  "fields": [
    { "key": "host",     "label": "Host",     "secret": false },
    { "key": "port",     "label": "Port",     "secret": false },
    { "key": "database", "label": "Database", "secret": false },
    { "key": "user",     "label": "User",     "secret": false },
    { "key": "password", "label": "Password", "secret": true  }
  ]
}
```

--------------------------------

### Update Project

Source: https://docs.mindshub.ai/api.html

Updates an existing project identified by its ID. Allows modification of name, description, and associated connector/skill IDs.

```APIDOC
## PATCH /projects/{id}

### Description
Updates an existing project. You can modify the project's name, description, and the lists of connector and skill IDs.

### Method
PATCH

### Endpoint
/projects/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project to update.

#### Request Body
- **name** (string) - Optional - The new display name for the project.
- **description** (string) - Optional - The new short description for the project.
- **connector_ids** (string[]) - Optional - Replaces the current list of data source connections.
- **skill_ids** (string[]) - Optional - Replaces the current list of global skills.
```

--------------------------------

### Create Conversation

Source: https://docs.mindshub.ai/api.html

Creates a new conversation. A title can be provided, otherwise it's auto-generated from the first message. A goal can also be specified to frame the conversation for an agent.

```APIDOC
## POST /conversations

### Description
Creates a new conversation. A title can be provided, otherwise it's auto-generated from the first message. A goal can also be specified to frame the conversation for an agent.

### Method
POST

### Endpoint
/conversations

### Parameters
#### Request Body
- **project_id** (string) - Optional - Attach to a project.
- **title** (string) - Optional - Human-readable name. Auto-generated from the first message if omitted.
- **goal** (string) - Optional - Task prompt or goal that frames the conversation for the agent.

### Request Example
```json
{
  "project_id": "proj_xyz",
  "title": "Q2 analysis",
  "goal": "Analyse Q2 revenue by region"
}
```
```

--------------------------------

### Delete Project

Source: https://docs.mindshub.ai/api.html

Deletes a project and all its associated contents.

```APIDOC
## DELETE /projects/{id}

### Description
Deletes a specified project and all of its contents, including conversations, files, and artifacts.

### Method
DELETE

### Endpoint
/projects/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project to delete.
```

--------------------------------

### Append a Cell to Scratchpad

Source: https://docs.mindshub.ai/api.html

Appends a new cell to a specified scratchpad. Supports code cells with specified language and content.

```shell
curl -X POST "http://localhost:26866/api/v1/scratchpads/{scratchpad_id}/cells" \
  -H "Content-Type: application/json" \
  -d '{"type":"code","language":"python","content":"df.head()"}'
```

--------------------------------

### Update an Existing Skill

Source: https://docs.mindshub.ai/api.html

Modify an existing skill using its ID in the URL. You can update the name, description, instructions, or the list of tools.

```curl
curl -X PATCH "http://localhost:26866/api/v1/skills/{id}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated summary of the skill.",
    "tools": ["sql_query"]
  }'
```

--------------------------------

### Schedule Object Structure

Source: https://docs.mindshub.ai/api.html

This JSON object represents the structure of a schedule, including its ID, project association, cron expression, timezone, prompt, conversation handling, status, and timestamps.

```json
{
  "id":              "sched_abc123",
  "project_id":      "proj_xyz",
  "cron":            "0 9 * * 1",       // standard 5-field cron expression
  "timezone":        "America/New_York",
  "prompt":          "Generate weekly sales digest",
  "conversation_id": null,             // null = create new conversation each run
  "status":          "active",         // "active" | "paused"
  "last_run_at":     "2026-06-09T09:00:00Z",
  "next_run_at":     "2026-06-16T09:00:00Z",
  "created_at":      "2026-06-01T00:00:00Z"
}
```

--------------------------------

### Search Result Object Structure

Source: https://docs.mindshub.ai/api.html

Defines the structure of a search result, including resource type, ID, title, excerpt, relevance score, and project ID.

```json
{
  "type":       "conversation",   // "conversation" | "artifact" | "file" | "memory"
  "id":         "conv_abc123",
  "title":      "Sales forecast Q3",
  "excerpt":    "...the Q3 sales forecast shows a 12% increase over...",
  "score":      0.93,             // relevance score 0–1
  "project_id": "proj_xyz"        // null for global results
}
```

--------------------------------

### List Conversations

Source: https://docs.mindshub.ai/api.html

Retrieves a list of conversations, with optional filtering by project ID and status, and pagination controls.

```APIDOC
## GET /conversations

### Description
Retrieves a list of conversations, with optional filtering by project ID and status, and pagination controls.

### Method
GET

### Endpoint
/conversations

### Parameters
#### Query Parameters
- **project_id** (string) - Optional - Filter to a specific project.
- **status** (string) - Optional - `active` or `archived`. Returns all if omitted.
- **limit** (integer) - Optional - Max results to return. Default `50`, max `200`.
- **offset** (integer) - Optional - Pagination offset. Default `0`.
```

--------------------------------

### Update a scratchpad

Source: https://docs.mindshub.ai/api.html

Updates an existing scratchpad. This endpoint can be used to change the title of a scratchpad or to mark it as saved.

```APIDOC
## PATCH /scratchpads/{scratchpad_id}

### Description
Updates the title or saved state of an existing scratchpad.

### Method
PATCH

### Endpoint
/api/v1/scratchpads/{scratchpad_id}

### Parameters
#### Path Parameters
- **scratchpad_id** (string) - Required - The ID of the scratchpad to update.

#### Request Body
- **title** (string) - Optional - The new title for the scratchpad.
- **saved** (boolean) - Optional - The new saved state for the scratchpad (true to save, false to unsave).
```

--------------------------------

### Cell Object Structure

Source: https://docs.mindshub.ai/api.html

Represents a single unit within a scratchpad, which can be markdown, code, or an output. Code cells include language and status, while output cells contain multi-modal data.

```json
{
  "id":        "cell_001",
  "type":      "code",          // "markdown" | "code" | "output"
  "content":   "df.describe()",
  "language":  "python",        // present when type = "code"
  "status":    "success",       // "pending" | "running" | "success" | "error"
  "outputs":   [                 // present when type = "output"
    {
      "mime":    "text/plain",
      "data":    "count    12.0\nmean     4.2\n..."
    },
    {
      "mime":    "image/png",
      "data":    "data:image/png;base64,..."
    }
  ],
  "error":     null,            // error message when status = "error"
  "index":     0                 // display order within the scratchpad
}
```

--------------------------------

### Update Scratchpad API Request

Source: https://docs.mindshub.ai/api.html

Use this endpoint to update the title or save state of an existing scratchpad. Provide the scratchpad ID in the URL and the fields to update in the request body.

```curl
curl -X PATCH "http://localhost:26866/api/v1/scratchpads/{scratchpad_id}" \
  -H "Content-Type: application/json" \
  -d '{"title":"Final analysis","saved":true}'
```

--------------------------------

### Memory Object Structure

Source: https://docs.mindshub.ai/api.html

This JSON object represents the structure of a memory, including its ID, content, project scope, source, and timestamps.

```json
{
  "id":           "mem_abc123",
  "content":      "Prefers executive summaries under 200 words.",
  "project_id":   null,            // null = global; string = project-scoped
  "source":       "user",          // "user" | "agent" — who created it
  "created_at":   "2026-06-11T10:00:00Z",
  "updated_at":   "2026-06-11T10:00:00Z"
}
```

--------------------------------

### Append Cell

Source: https://docs.mindshub.ai/api.html

Appends a new cell to a scratchpad. Cells can be of type 'code' with specified language and content.

```APIDOC
## POST /scratchpads/{scratchpad_id}/cells

### Description
Appends a new cell to a scratchpad.

### Method
POST

### Endpoint
/api/v1/scratchpads/{scratchpad_id}/cells

### Parameters
#### Path Parameters
- **scratchpad_id** (string) - Required - The ID of the scratchpad to append the cell to.

#### Request Body
- **type** (string) - Required - The type of the cell (e.g., 'code').
- **language** (string) - Required - The programming language of the cell (e.g., 'python').
- **content** (string) - Required - The content of the cell.

### Request Example
```json
{
  "type": "code",
  "language": "python",
  "content": "df.head()"
}
```
```

--------------------------------

### Trigger Schedule

Source: https://docs.mindshub.ai/api.html

Manually triggers a schedule immediately, regardless of its cron settings.

```APIDOC
## POST /schedules/{id}/run Trigger a schedule immediately

### Description
Manually triggers a schedule immediately, regardless of its cron settings.

### Method
POST

### Endpoint
/schedules/{id}/run
```

--------------------------------

### Search API Response Structure

Source: https://docs.mindshub.ai/api.html

Represents the response from the search API, containing a list of search results and the total number of matches.

```json
{
  "results": [
    {
      "type":       "conversation",
      "id":         "conv_abc123",
      "title":      "Sales forecast Q3",
      "excerpt":    "...the Q3 sales forecast shows a 12% increase over...",
      "score":      0.93,
      "project_id": "proj_xyz"
    }
  ],
  "total": 1
}
```
Tokens:
Raw