### Install the PrivateMind SDK

Source: https://docs.privatemind.com/sdk.html

Use pip to install the package in your local environment.

```shell
pip install privatemind
```

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

### Install the PrivateMind CLI

Source: https://docs.privatemind.com/workspaces.html

Run this command to install the helper CLI tool on your local machine.

```shell
curl -fsSL https://privatemind.com/pm/install.sh | sh
```

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

### Mint User Key Request Example

Source: https://docs.privatemind.com/openapi.yaml

Example payload for the key exchange endpoint, requiring an IDP token and optional TTL.

```yaml
mint:
  value:
    idp_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    ttl_seconds: 3600
```

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

### Speech Synthesis Request Example

Source: https://docs.privatemind.com/openapi.yaml

Example JSON payload for the /audio/speech endpoint.

```yaml
model: chatterbox-turbo
voice: default
input: Hello world.
```

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

### List Sources Response Example

Source: https://docs.privatemind.com/openapi.yaml

Successful response structure for the listSources operation.

```json
success: true
total: 1
body:
  - id: 482
    source_type: vectorized
    source_name: quarterly-report.pdf
    source_description: null
    handler: vectorFileHandler
    source_config: { collection_name: pmchat_1207_100 }
    conversation_id: 1207
    is_active: true
    use_in_tasks: false
    is_owner: true
    created_at: "2026-06-20T09:10:00Z"
    updated_at: "2026-06-20T09:10:00Z"
```

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

### Count tokens request examples

Source: https://docs.privatemind.com/count-tokens.html

Examples of how to call the count_tokens endpoint using cURL, Python, and TypeScript.

```bash
curl -s "https://api.privatemind.com/v1/chat/count_tokens" \
  -H "Authorization: Bearer $PMIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fast",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user",   "content": "Hello, how are you today?"}
    ]
  }'
# => { "input_tokens": 23, "context_window": 131072 }
```

```python
import httpx

resp = httpx.post(
    "https://api.privatemind.com/v1/chat/count_tokens",
    headers={"Authorization": f"Bearer {PMIND_KEY}"},
    json={
        "model": "fast",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user",   "content": "Hello, how are you today?"},
        ],
    },
)
print(resp.json()["input_tokens"])
```

```typescript
const resp = await fetch('https://api.privatemind.com/v1/chat/count_tokens', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${PMIND_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'fast',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Hello, how are you today?' },
    ],
  }),
});
const { input_tokens } = await resp.json();
console.log(input_tokens);
```

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

### Chat Completion Request Examples

Source: https://docs.privatemind.com/openapi.yaml

Examples of JSON request bodies for chat completions, including basic usage and reasoning configuration.

```json
model: fast
messages:
  - role: system
    content: You are a concise assistant.
  - role: user
    content: Explain the CAP theorem.
temperature: 0.2
max_tokens: 400
```

```json
model: reasoning
messages:
  - role: user
    content: Plan a four-step proof of Pythagoras.
reasoning_effort: low
```

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

### Retrieve usage summary via cURL

Source: https://docs.privatemind.com/usage.html

Examples of querying usage summaries grouped by project or specific metadata tags.

```bash
# Spend per project
curl -s "https://api.privatemind.com/v1/usage/summary?group_by=metadata.project" \
  -H "Authorization: Bearer $PMIND_KEY"

# Sub-costs within one project
curl -s 'https://api.privatemind.com/v1/usage/summary?group_by=metadata.stage&metadata={"project":"load-company-data"}' \
  -H "Authorization: Bearer $PMIND_KEY"
```

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

### Mint User Key Response Example

Source: https://docs.privatemind.com/openapi.yaml

Successful response containing the minted access key and associated metadata.

```yaml
success: true
data:
  access_key_id: PMIND00000000000000000000000000
  secret: "0000000000000000000000000000000000000000000000000000000000000000"
  full_key: "PMIND00000000000000000000000000:0000000000000000000000000000000000000000000000000000000000000000"
  expires_at: "2026-06-28T13:00:00Z"
  user_id: "100"
  org_id: 1
```

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

### List sources API response

Source: https://docs.privatemind.com/sources.html

Example JSON response structure returned by the GET /v1/sources endpoint.

```json
{
  "success": true,
  "total": 3,
  "body": [
    {
      "id": 482,
      "source_type": "vectorized",
      "source_name": "file_quarterly-report.pdf",
      "source_description": "File \"quarterly-report.pdf\"",
      "handler": "vectorFileHandler",
      "source_config": {
        "conversation_id": 1207,
        "collection_name": "vec_482",
        "file_id": 482,
        "file_name": "quarterly-report.pdf",
        "file_type": "application/pdf",
        "file_size": 184302,
        "chunks_count": 47,
        "stored_at": "2026-05-20T14:02:11.482Z"
      },
      "conversation_id": 1207,
      "is_active": true,
      "use_in_tasks": true,
      "created_at": "2026-05-20T14:02:11.482Z",
      "updated_at": "2026-05-20T14:02:11.482Z"
    }
  ]
}
```

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

### GET /v1/models

Source: https://docs.privatemind.com/authentication.html

Verifies that an API key is valid and active.

```APIDOC
## GET /v1/models

### Description
Verifies that the provided API key is valid and active. Returns a 200 status code on success.

### Method
GET

### Endpoint
https://api.privatemind.com/v1/models

### Request Headers
- **Authorization**: Bearer <ACCESS_KEY_ID>:<SECRET> - Required

### Response
#### Success Response (200)
- The key is valid and active.
```

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

### Bearer Token Example

Source: https://docs.privatemind.com/authentication.html

The structure of the full bearer token string.

```text
PMIND...:...
```

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

### Create Embedding Request Example

Source: https://docs.privatemind.com/openapi.yaml

Example payload for generating embeddings from a batch of strings.

```json
model: kalm-embedding-gemma3-12b-2511
input:
  - the quick brown fox
  - jumps over the lazy dog
```

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

### Batch object structure

Source: https://docs.privatemind.com/batch.html

Example of the JSON response returned when querying a batch object.

```json
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "in_progress",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1781481050,
  "expires_at": 1781567450,
  "request_counts": { "total": 2, "completed": 0, "failed": 0 },
  "errors": null,
  "metadata": null
}
```

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

### Example SSE wire format

Source: https://docs.privatemind.com/streaming.html

The stream consists of data lines containing JSON chunks, ending with a [DONE] sentinel.

```text
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Packets"},"index":0}]}

...

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{},"index":0,"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":28,"total_tokens":40}}

data: [DONE]
```

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

### List Conversations Response Example

Source: https://docs.privatemind.com/openapi.yaml

Successful response returning a list of conversation metadata objects.

```yaml
success: true
body:
  - id: 1207
    user_id: 100
    title: Quarterly planning
    project_id: null
    last_message_at: "2026-06-28T11:55:00Z"
    created_at: "2026-06-20T09:00:00Z"
    is_ephemeral: false
    source_count: 2
total:
  types: [chat]
```

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

### List Sources Error Response Example

Source: https://docs.privatemind.com/openapi.yaml

Error response structure for the listSources operation.

```json
{ success: false, message: Failed to fetch sources }
```

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

### Usage summary JSON response structure

Source: https://docs.privatemind.com/usage.html

Example of the JSON response returned by the /v1/usage/summary endpoint.

```json
{
  "success": true,
  "group_by": "metadata.project",
  "data": [
    { "group_value": "load-company-data", "requests": 4120, "prompt_tokens": 5680000, "cached_prompt_tokens": 910000, "completion_tokens": 1240000, "total_tokens": 6920000, "cost_usd": 18.42 },
    { "group_value": "sentiment-batch",   "requests": 1300, "prompt_tokens": 980000,  "cached_prompt_tokens": 0, "completion_tokens": 210000, "total_tokens": 1190000, "cost_usd": 4.10 },
    { "group_value": null,                "requests": 88,   "prompt_tokens": 40000,   "cached_prompt_tokens": 0, "completion_tokens": 9000,   "total_tokens": 49000,   "cost_usd": 0.20 }
  ],
  "pagination": { "limit": 100, "offset": 0, "has_more": false }
}
```

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

### Generate Conversation Reply Request Example

Source: https://docs.privatemind.com/openapi.yaml

Example JSON payload for the generateConversationReply operation.

```json
{
  "conversation_id": 1207,
  "message_id": 88431
}
```

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

### Create Rerank Request Example

Source: https://docs.privatemind.com/openapi.yaml

Example payload for scoring documents against a query using a cross-encoder.

```json
model: qwen3-reranker-4b
query: What is the capital of France?
documents:
  - Paris is the capital of France.
  - London is the capital of England.
  - Berlin is the capital of Germany.
top_n: 3
```

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

### Usage API Success Response Example

Source: https://docs.privatemind.com/openapi.yaml

Provides a sample JSON response for a successful usage data query, including data rows and pagination metadata.

```json
success: true
                data:
                  - id: 90432
                    org: options-it
                    deployment: deepseek-v4-pro
                    key_id: PMIND00000000000000000000000000
                    user_id: "100"
                    model: deepseek-v4-pro
                    prompt_tokens: 812
                    cached_prompt_tokens: 0
                    completion_tokens: 240
                    cost_usd: 0.0041
                    latency_ms: 1830
                    status_code: 200
                    created_at: "2026-06-28T12:00:00Z"
                    workspace: chat
                    team_id: null
                    metadata: { project: alpha }
                pagination:
                  limit: 100
                  offset: 0
                  has_more: false
                  from: "2026-05-29T12:00:00Z"
                  to: "2026-06-28T12:00:00Z"
```

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

### Batch-delete conversations request example

Source: https://docs.privatemind.com/openapi.yaml

Example JSON payload for the conversation deletion endpoint.

```json
conversation_ids: [1207, 1208]
```

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

### Generate Embeddings

Source: https://docs.privatemind.com/embeddings.html

Examples of how to request embeddings using cURL, Python, and TypeScript.

```bash
curl -s "https://api.privatemind.com/v1/embeddings" \
  -H "Authorization: Bearer $PMIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kalm-embedding-gemma3-12b-2511",
    "input": ["the quick brown fox", "jumps over the lazy dog"]
  }' | jq '.data[].embedding | length'
```

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.privatemind.com/v1", api_key=PMIND_KEY)
resp = client.embeddings.create(
    model="kalm-embedding-gemma3-12b-2511",
    input=["the quick brown fox", "jumps over the lazy dog"],
)
print(len(resp.data[0].embedding))
```

```typescript
import OpenAI from 'openai';

const client = new OpenAI({ baseURL: `https://api.privatemind.com/v1`, apiKey: PMIND_KEY });
const resp = await client.embeddings.create({
  model: 'kalm-embedding-gemma3-12b-2511',
  input: ['the quick brown fox', 'jumps over the lazy dog'],
});
console.log(resp.data[0].embedding.length);
```

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

### Batch Output JSON Format

Source: https://docs.privatemind.com/batch.html

Example structure of a single line in the JSONL output file.

```json
{"id": "batch_req_...", "custom_id": "req-1", "response": {"status_code": 200, "request_id": "req_...", "body": { "id": "chatcmpl-...", "choices": [ ... ] }}, "error": null}
```

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

### Successful ingestion response

Source: https://docs.privatemind.com/sources.html

Example JSON response returned upon successful file vectorization.

```json
{
  "success": true,
  "message": "File vectorized with 47 chunks successfully",
  "total": {
    "conversation_id": 1207,
    "vectorized_file": {
      "id": 482,
      "file_name": "quarterly-report.pdf",
      "collection_name": "vec_482",
      "file_type": "application/pdf",
      "file_size": 184302,
      "created_at": "2026-05-20T14:02:11.482Z"
    }
  }
}
```

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

### GET /usage

Source: https://docs.privatemind.com/openapi.yaml

Retrieves a paginated list of usage rows based on provided query parameters.

```APIDOC
## GET /usage

### Description
Retrieves a page of usage rows. Filters can be applied to narrow down the results by model, workspace, deployment, metadata, or time range.

### Method
GET

### Endpoint
/usage

### Parameters
#### Query Parameters
- **model** (string) - Optional - Only rows for this model id.
- **workspace** (string) - Optional - Traffic source filter (e.g. chat, embeddings).
- **deployment** (string) - Optional - Only rows for this deployment id.
- **metadata** (string) - Optional - URL-encoded JSON object of string→string matched with containment.
- **from** (string) - Optional - Lower bound (inclusive). RFC 3339 datetime or YYYY-MM-DD (UTC midnight).
- **to** (string) - Optional - Upper bound (exclusive). RFC 3339 datetime or YYYY-MM-DD.
- **limit** (integer) - Optional - Default: 100, Minimum: 1, Maximum: 1000.
- **offset** (integer) - Optional - Default: 0, Minimum: 0, Maximum: 100000.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - A list of usage row objects.
- **pagination** (object) - Pagination metadata including limit, offset, and has_more.

#### Response Example
{
  "success": true,
  "data": [
    {
      "id": 90432,
      "org": "options-it",
      "deployment": "deepseek-v4-pro",
      "key_id": "PMIND00000000000000000000000000",
      "user_id": "100",
      "model": "deepseek-v4-pro",
      "prompt_tokens": 812,
      "cached_prompt_tokens": 0,
      "completion_tokens": 240,
      "cost_usd": 0.0041,
      "latency_ms": 1830,
      "status_code": 200,
      "created_at": "2026-06-28T12:00:00Z",
      "workspace": "chat",
      "team_id": null,
      "metadata": { "project": "alpha" }
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": false,
    "from": "2026-05-29T12:00:00Z",
    "to": "2026-06-28T12:00:00Z"
  }
}
```

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

### GET /models

Source: https://docs.privatemind.com/openapi.yaml

Retrieve a list of models your organization is permitted to use.

```APIDOC
## GET /models

### Description
Return the models your org is permitted to use in this environment. The list is filtered by what is live and what your org is entitled to, so it is exactly the set of model ids you can pass as `model`.

### Method
GET

### Endpoint
/models

### Response
#### Success Response (200)
- **data** (array) - An OpenAI-shaped list of models.
```

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

### Example webhook payload

Source: https://docs.privatemind.com/training-sdk.html

The platform sends a POST request with this JSON structure upon job completion.

```json
{
  "job_id": "tj-abc12",
  "name": "tj-abc12",
  "delivery_id": "9f1c...",
  "status": "Succeeded",
  "started_at": "2026-01-02T10:00:00Z",
  "finished_at": "2026-01-02T10:14:30Z"
}
```

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

### GET /usage

Source: https://docs.privatemind.com/openapi.yaml

Retrieves usage records for the authenticated API key, ordered by newest first.

```APIDOC
## GET /usage

### Description
Return flat usage rows for the authenticated API key. Results are force-scoped to the calling key; rows are ordered newest first.

### Method
GET

### Endpoint
/usage
```

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

### Make an API request to PrivateMind

Source: https://docs.privatemind.com/

Use these examples to perform a chat completion request. Ensure you have your API key set in the environment variable PMIND_KEY.

```bash
curl -s "https://api.privatemind.com/v1/chat/completions" \
  -H "Authorization: Bearer $PMIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fast",
    "messages": [{"role": "user", "content": "Hello, world."}]
  }'
```

```python
from openai import OpenAI
client = OpenAI(base_url="https://api.privatemind.com/v1", api_key=PMIND_KEY)
resp = client.chat.completions.create(
    model="fast",
    messages=[{"role": "user", "content": "Hello, world."}],
)
print(resp.choices[0].message.content)
```

```typescript
import OpenAI from 'openai';
const client = new OpenAI({ baseURL: 'https://api.privatemind.com/v1', apiKey: process.env.PMIND_KEY });
const resp = await client.chat.completions.create({
  model: 'fast',
  messages: [{ role: 'user', content: 'Hello, world.' }],
});
console.log(resp.choices[0].message.content);
```

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

### Handle reasoning model streaming events

Source: https://docs.privatemind.com/streaming.html

Example of server-sent event data structures containing reasoning and content deltas.

```text
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"reasoning":"Let me work through"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"reasoning":" the proof step by step…"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"The answer is 42."},"index":0}]}
```

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

### GET /conversations/{id}/sources

Source: https://docs.privatemind.com/openapi.yaml

Retrieves a list of sources associated with a specific conversation.

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

### Description
Retrieves a list of sources associated with a specific conversation. The response includes detailed information about each source.

### Method
GET

### Endpoint
/conversations/{id}/sources

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the conversation.
```

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

### Token Count Request and Response

Source: https://docs.privatemind.com/openapi.yaml

Example request and response for the count_tokens endpoint to estimate usage without running inference.

```json
model: fast
messages:
  - role: system
    content: You are a helpful assistant.
  - role: user
    content: Hello, how are you today?
```

```json
input_tokens: 23
context_window: 131072
```

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

### Perform Chat Completion Requests

Source: https://docs.privatemind.com/chat-completions.html

Examples of interacting with the chat completions endpoint using cURL, Python, and TypeScript.

```bash
curl -s "https://api.privatemind.com/v1/chat/completions" \
  -H "Authorization: Bearer $PMIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fast",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user",   "content": "Explain the CAP theorem."}
    ],
    "temperature": 0.2,
    "max_tokens": 400
  }'
```

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.privatemind.com/v1",
    api_key="PMIND...:abcdef...",
)

resp = client.chat.completions.create(
    model="fast",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user",   "content": "Explain the CAP theorem."},
    ],
    temperature=0.2,
    max_tokens=400,
)
print(resp.choices[0].message.content)
```

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.privatemind.com/v1',
  apiKey: process.env.PMIND_KEY,
});

const resp = await client.chat.completions.create({
  model: 'fast',
  messages: [
    { role: 'system', content: 'You are a concise assistant.' },
    { role: 'user',   content: 'Explain the CAP theorem.' },
  ],
  temperature: 0.2,
  max_tokens: 400,
});
console.log(resp.choices[0].message.content);
```

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

### GET /conversations/{id}/sources

Source: https://docs.privatemind.com/openapi.yaml

Lists active, non-deleted source attachments for a specific conversation.

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

### Description
Lists active, non-deleted source attachments for a conversation. Source configuration is redacted unless the caller owns the source.

### Method
GET

### Endpoint
/conversations/{id}/sources

### Parameters
#### Path Parameters
- **id** (string) - Required - The conversation identifier.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success.
- **body** (array) - List of conversation sources.
- **total** (integer) - The total row count.
```

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

### Batch API Input JSONL Format

Source: https://docs.privatemind.com/batch.html

Example of the JSONL file structure required for batch processing, where each line represents a unique request.

```json
{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "glm-5-2-nvfp4", "messages": [{"role": "user", "content": "Summarise: ..."}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "glm-5-2-nvfp4", "messages": [{"role": "user", "content": "Translate to French: ..."}]}}
```

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

### Retrieve conversations response structure

Source: https://docs.privatemind.com/conversations.html

Example JSON response body returned by the GET /v1/conversations endpoint.

```json
{
  "success": true,
  "body": [
    {
      "id": 1234,
      "user_id": 42,
      "title": "Refactor the billing service",
      "project_id": null,
      "cloud_agent_task_id": null,
      "archived_at": null,
      "last_message_at": "2026-05-26T14:21:08.123Z",
      "source_count": 2,
      "messages": [
        {
          "message": "Here's a sketch of the new structure...",
          "role": "assistant",
          "created_at": "2026-05-26T14:21:08.123Z",
          "conversation_id": 1234
        }
      ]
    }
  ],
  "total": { "types": ["chat", "agent"] }
}
```

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

### GET /usage/summary

Source: https://docs.privatemind.com/openapi.yaml

Retrieves an aggregated summary of usage metrics, including requests, tokens, and costs, grouped by a specified dimension.

```APIDOC
## GET /usage/summary

### Description
Server-side rollup over your usage rows: sums requests, tokens, and cost per `group_by` bucket. Groups are ordered by cost descending and capped by `limit`.

### Method
GET

### Endpoint
/usage/summary

### Parameters
#### Query Parameters
- **group_by** (string) - Required - One of `model`, `workspace`, `key_id`, `user_id`, `day`, or `metadata.<key>`.
- **model** (string) - Optional - Filter by model.
- **workspace** (string) - Optional - Filter by workspace.
- **metadata** (string) - Optional - Tag containment filter.
- **from** (string) - Optional - RFC 3339 datetime or YYYY-MM-DD. Default: now - 30d.
- **to** (string) - Optional - RFC 3339 datetime or YYYY-MM-DD. Default: now. Window capped at 366 days.
- **limit** (integer) - Optional - Default: 100. Range: 1-1000.
- **offset** (integer) - Optional - Default: 0. Range: 0-100000.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates request success.
- **group_by** (string) - The grouping dimension used.
- **data** (array) - List of usage totals per group.
- **pagination** (object) - Pagination metadata.

#### Response Example
{
  "success": true,
  "group_by": "model",
  "data": [
    {
      "group_value": "deepseek-v4-pro",
      "requests": 1280,
      "prompt_tokens": 940233,
      "cached_prompt_tokens": 12000,
      "completion_tokens": 410992,
      "total_tokens": 1351225,
      "cost_usd": 12.84
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": false,
    "from": "2026-05-29T12:00:00Z",
    "to": "2026-06-28T12:00:00Z"
  }
}
```

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

### List conversation sources response

Source: https://docs.privatemind.com/conversations.html

Example JSON response body for the GET /v1/conversations/{id}/sources endpoint.

```json
{
  "success": true,
  "body": [
    {
      "id": 88,
      "source_type": "vectorized",
      "source_name": "billing-spec.pdf",
      "source_config": { },
      "handler": "vectorFileHandler",
      "source_description": null,
      "is_owner": true
    }
  ],
  "total": 1
}
```

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

### Retrieve a single conversation

Source: https://docs.privatemind.com/conversations.html

Example JSON response from the GET /v1/conversations/{id} endpoint, showing the structure of messages, sources, and participants.

```json
{
  "success": true,
  "conversation": {
    "id": 1234,
    "user_id": 42,
    "title": "Refactor the billing service",
    "project_id": null,
    "archived_at": null,
    "last_message_at": "2026-05-26T14:21:08.123Z",
    "sources": [
      {
        "id": 88,
        "source_type": "vectorized",
        "source_name": "billing-spec.pdf",
        "source_config": { },
        "is_active": true,
        "use_in_tasks": true,
        "handler": "vectorFileHandler",
        "source_description": null,
        "is_owner": true
      }
    ],
    "participants": [
      {
        "user_id": 42,
        "role": "owner",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
        "joined_at": "2026-05-20T09:00:00.000Z"
      }
    ],
    "messages": [
      {
        "id": 9001,
        "conversation_id": 1234,
        "user_id": 42,
        "message": "How should we split the invoicing module?",
        "reasoning_content": null,
        "role": "user",
        "created_at": "2026-05-26T14:20:42.000Z",
        "is_read": true,
        "attachments": [],
        "model_name": null,
        "tool_call_id": null,
        "tool_name": null,
        "tool_status": null,
        "finish_reason": null,
        "turn_id": null,
        "parent_message_id": null,
        "active_sibling_message": true,
        "sibling_ids": [9001],
        "metadata": {}
      },
      {
        "id": 9002,
        "conversation_id": 1234,
        "user_id": 42,
        "message": "Here's a sketch of the new structure...",
        "reasoning_content": null,
        "role": "assistant",
        "created_at": "2026-05-26T14:21:08.123Z",
        "is_read": true,
        "attachments": [],
        "model_name": "kimi-k2-6",
        "tool_call_id": null,
        "tool_name": null,
        "tool_status": null,
        "finish_reason": "stop",
        "turn_id": "turn_01HXYZ...",
        "parent_message_id": 9001,
        "active_sibling_message": true,
        "sibling_ids": [9002],
        "metadata": {}
      }
    ]
  }
}
```

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

### Configure OpenAI Go Client

Source: https://docs.privatemind.com/openai-sdk.html

Use the official OpenAI Go SDK with custom base URL and API key options.

```go
import (
  "context"
  "fmt"
  openai "github.com/openai/openai-go"
  "github.com/openai/openai-go/option"
)

client := openai.NewClient(
  option.WithBaseURL("https://api.privatemind.com/v1"),
  option.WithAPIKey("PMIND...:abcdef..."),
)

resp, _ := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
  Model: openai.F("<model-id>"),
  Messages: openai.F([]openai.ChatCompletionMessageParamUnion{
    openai.UserMessage("Hello"),
  }),
})
fmt.Println(resp.Choices[0].Message.Content)
```

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

### GET /conversations/{id}

Source: https://docs.privatemind.com/openapi.yaml

Retrieves a full visible thread including sources and participants for a specific conversation.

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

### Description
Retrieves the full visible thread plus sources and participants for a conversation. Returns 404 if the conversation is not owned by or shared with the caller.

### Method
GET

### Endpoint
/conversations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The conversation identifier.

#### Query Parameters
- **before_id** (integer) - Optional - Scroll up — return the next older page before this message id.
- **from_id** (integer) - Optional - Reconcile anchor for the open conversation.
- **limit** (integer) - Optional - Page size (default 20, capped at 500).

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success.
- **conversation** (object) - The conversation detail object.
```

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

### Construct an explicit Client instance

Source: https://docs.privatemind.com/sdk.html

Uses a context manager to handle client lifecycle and eager configuration validation.

```python
from privatemind import Client

with Client(
    base_url="https://api.privatemind.com",  # optional: this is the default
    app_url="https://privatemind.com",       # optional: this is the default
    token="PMIND...:abcdef...",
) as pm:
    for run in pm.list_jobs():
        print(run.name, run.phase)
```

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

### GET /voices

Source: https://docs.privatemind.com/openapi.yaml

Retrieves a list of available text-to-speech voices. The catalogue is determined by the specified TTS deployment model.

```APIDOC
## GET /voices

### Description
Return the voice ids available for `POST /audio/speech`. The voice catalogue is read from the TTS deployment selected by the `model` query parameter (default `tts`).

### Method
GET

### Endpoint
/voices

### Parameters
#### Query Parameters
- **model** (string) - Optional - TTS deployment id or role alias. Defaults to `tts`.
```

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

### ConversationSource Schema

Source: https://docs.privatemind.com/openapi.yaml

Defines the structure of a source row returned by the GET /conversations/{id}/sources endpoint.

```yaml
ConversationSource:
      type: object
      description: A source row returned by `GET /conversations/{id}/sources` (richer than the embedded form).
      required: [id, source_type, source_name, conversation_id, is_owner]
      properties:
        id: { type: integer }
        source_type: { type: string }
        source_name: { type: string }
        source_config:
          type: object
          additionalProperties: true
          description: Redacted unless the caller owns the source.
        handler: { type: [string, "null"] }
        source_description: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        updated_at: { type: [string, "null"], format: date-time }
        metadata: { type: [object, "null"], additionalProperties: true }
        host_identifier: { type: [string, "null"] }
        conversation_id: { type: integer }
        is_active: { type: [boolean, "null"] }
        use_in_tasks: { type: [boolean, "null"] }
        source_origin: { type: [string, "null"] }
        is_owner: { type: boolean }
```

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

### GET /sources

Source: https://docs.privatemind.com/openapi.yaml

Retrieves a list of all sources visible to the authenticated user. This includes files owned by the user, shared sources, and organization-level sources.

```APIDOC
## GET /sources

### Description
Return every source the user can reach: files they own, group-shared sources, and org-level sources surfaced by an admin. A source attached to multiple conversations appears once per conversation.

### Method
GET

### Endpoint
/sources

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **total** (integer) - Total number of sources returned.
- **body** (array) - List of source objects.

#### Response Example
{
  "success": true,
  "total": 1,
  "body": [
    {
      "id": 482,
      "source_type": "vectorized",
      "source_name": "quarterly-report.pdf",
      "source_description": null,
      "handler": "vectorFileHandler",
      "source_config": { "collection_name": "pmchat_1207_100" },
      "conversation_id": 1207,
      "is_active": true,
      "use_in_tasks": false,
      "is_owner": true,
      "created_at": "2026-06-20T09:10:00Z",
      "updated_at": "2026-06-20T09:10:00Z"
    }
  ]
}
```

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

### List Available Models

Source: https://docs.privatemind.com/quickstart.html

Retrieve a list of deployed models and their configurations using the API key.

```bash
curl -s "https://api.privatemind.com/v1/models" \
  -H "Authorization: Bearer $PMIND_KEY" \
  | jq '.data[] | {id, context_length, supported_parameters}'
```

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

### Configure OpenAI Python Client

Source: https://docs.privatemind.com/openai-sdk.html

Initialize the OpenAI client with the PrivateMind base URL and API key to perform chat completions.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.privatemind.com/v1",
    api_key="PMIND...:abcdef...",
)

resp = client.chat.completions.create(
    model="<model-id>",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)
```

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

### Get Conversation Details

Source: https://docs.privatemind.com/openapi.yaml

Retrieves the full thread, sources, and participants for a specific conversation ID. Requires a user-scoped bearer token.

```yaml
/conversations/{id}:
    get:
      operationId: getConversation
      tags: [Conversations]
      summary: Get one conversation
      description: |
        Full visible thread plus sources and participants. Returns `404` if the
        conversation is not owned by, or shared with, the caller. Requires a
        user-scoped key.
      security:
        - userBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, pattern: "^[A-Za-z0-9_-]{1,64}$" }
        - name: before_id
          in: query
          required: false
          schema: { type: integer }
          description: Scroll up — return the next older page before this message id.
        - name: from_id
          in: query
          required: false
          schema: { type: integer }
          description: Reconcile anchor for the open conversation.
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 20, minimum: 1, maximum: 500 }
          description: Page size (default 20, capped at 500).
      responses:
        '200':
          description: Conversation detail.
          content:
            application/json:
              schema:
                type: object
                required: [success, conversation]
                properties:
                  success: { const: true }
                  conversation: { $ref: '#/components/schemas/ConversationDetail' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/AppNotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '502': { $ref: '#/components/responses/AppBadGateway' }
```

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

### Client Configuration and Usage

Source: https://docs.privatemind.com/sdk.html

Demonstrates how to instantiate and use the PrivateMind Client as a context manager for explicit control over API interactions.

```APIDOC
## Client(base_url, app_url, token, timeout, verify)

### Description
Constructs a client instance for interacting with PrivateMind services. Configuration is resolved eagerly, and the client can be used as a context manager to ensure proper resource cleanup.

### Parameters
- **base_url** (str) - Optional - The Platform API base URL. Defaults to https://api.privatemind.com.
- **app_url** (str) - Optional - The App backend base URL. Defaults to https://privatemind.com.
- **token** (str) - Required - The PrivateMind API key (e.g., PMIND...:abcdef...).
- **timeout** (int) - Optional - Per-request timeout in seconds. Defaults to 30.
- **verify** (bool) - Optional - Enable or disable TLS verification. Defaults to True.

### Usage Example
```python
from privatemind import Client

with Client(
    token="PMIND...:abcdef..."
) as pm:
    for run in pm.list_jobs():
        print(run.name, run.phase)
```
```

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

### Promote a notebook function for distributed training

Source: https://docs.privatemind.com/training-sdk.html

Use the @pm.train decorator to define a training function, then call .promote() to submit it as a distributed job. Ensure all imports are inside the function and inputs are passed as arguments.

```python
import privatemind as pm

@pm.train(workers=1, gpus_per_worker=1)
def train(lr=3e-4, epochs=10):
    import mlflow, torch       # re-resolved on the worker, must be in the image
    assert torch.cuda.is_available()
    ...

train(lr=1e-3)                 # runs locally in the notebook (validate)
run = train.promote(lr=1e-3)   # packages + submits to the GPU -> Run
run.wait(); print(run.mlflow_run_id)
```

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

### GET /conversations

Source: https://docs.privatemind.com/openapi.yaml

Retrieves a list of non-archived conversations owned by or shared with the caller. Returns conversation metadata without message bodies.

```APIDOC
## GET /conversations

### Description
Retrieves a list of non-archived conversations owned by or shared with the caller, sorted newest first. Requires a user-scoped key.

### Method
GET

### Endpoint
/conversations

### Parameters
#### Query Parameters
- **project_id** (string) - Optional - Filter to a project id.
- **cloud_agents** (string) - Optional - If 'true', returns only cloud-agent conversations.
- **archived** (string) - Optional - If 'true', returns only archived conversations.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success.
- **body** (array) - List of conversation objects.
- **total** (object) - Metadata about conversation types.

#### Response Example
{
  "success": true,
  "body": [
    {
      "id": 1207,
      "user_id": 100,
      "title": "Quarterly planning",
      "project_id": null,
      "last_message_at": "2026-06-28T11:55:00Z",
      "created_at": "2026-06-20T09:00:00Z",
      "is_ephemeral": false,
      "source_count": 2
    }
  ],
  "total": {
    "types": ["chat"]
  }
}
```

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

### Upload and Create Batch

Source: https://docs.privatemind.com/sdk-batch.html

Uploads the prepared JSONL file and initiates a batch processing job.

```python
from privatemind import Client

client = Client()   # token and base URL from the workspace environment

f = client.create_file(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.create_batch(
    input_file_id=f.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
print(batch.id, batch.status)   # batch_... in_progress
```

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

### Configure Vercel AI SDK

Source: https://docs.privatemind.com/openai-sdk.html

Use createOpenAI from the Vercel AI SDK to interface with PrivateMind.

```typescript
import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const privatemind = createOpenAI({
  baseURL: "https://api.privatemind.com/v1",
  apiKey: "PMIND...:abcdef...",
});

const { text } = await generateText({
  model: privatemind("<model-id>"),
  prompt: "Hello",
});
```

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

### GET /v1/voices

Source: https://docs.privatemind.com/audio.html

Lists available voices for text-to-speech synthesis.

```APIDOC
## GET /v1/voices

### Description
Retrieves a list of available voices.

### Method
GET

### Endpoint
/v1/voices
```

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

### Configure Continue with PrivateMind

Source: https://docs.privatemind.com/coding-agents.html

Add PrivateMind models to the Continue configuration file by specifying the OpenAI provider and the custom API base URL.

```yaml
models:
  - title: PrivateMind Fast
    provider: openai
    model: fast
    apiKey: PMIND...:...
    apiBase: https://api.privatemind.com/v1

  - title: PrivateMind Reasoning
    provider: openai
    model: reasoning
    apiKey: PMIND...:...
    apiBase: https://api.privatemind.com/v1
```

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

### Create and process a batch with Python SDK

Source: https://docs.privatemind.com/batch.html

Uses the PrivateMind Python SDK to upload a file, create a batch, wait for completion, and iterate through results.

```python
from privatemind import Client

client = Client()  # base_url + token from the environment

f = client.create_file(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.create_batch(
    input_file_id=f.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
batch.wait()                     # poll until terminal
for row in batch.results():      # one dict per output line
    print(row["custom_id"], row["response"]["status_code"])
```