Vector store

Configure whether a project uses Perchat's platform vector store or a bring-your-own (BYO) cluster for semantic indexing and search. Today the backend uses Qdrant; these endpoints are provider-agnostic. Settings are per project and affect indexer workers and the catalog service.

Console session only — authenticate with Authorization: Bearer <jwt> from login plus X-Workspace-Id and X-Project-Id. Requires workspace role permissions vector_store:read or vector_store:update. Project and workspace API keys cannot call these routes (use the dashboard or mint a session).

Platform default — set useCustom: falseto use Perchat's managed Qdrant for indexer jobs and content search. Custom URL and API key are kept on the project but not used until you switch back.

Custom vector store (BYO) — set useCustom: true with a valid https:// cluster URL. Saving or updating custom settings runs an automatic connection test and cluster sizing check against platform minimums (requiredClusterSpecs in settings). Failed checks return 422 validationError and settings are not saved.

apiKey is required for *.cloud.qdrant.io hosts and when the cluster rejects unauthenticated requests.
The API key is stored encrypted; responses only include apiKeySet: true.
Omit apiKey on PATCH to keep the stored key; send an empty string only when no key is stored yet.
Indexer jobs and catalog search use the live cluster for the project. Vectors are not copied when you switch clusters — re-run indexer jobs on the new cluster.

Get vector store settingsGET/v1/project-vector-store/settingschevron_right
Update vector store settingsPATCH/v1/project-vector-store/settingschevron_right
Test connection and sizingPOST/v1/project-vector-store/testchevron_right
Probe cluster sizingPOST/v1/project-vector-store/specschevron_right
Health check (active cluster)POST/v1/project-vector-store/healthchevron_right
Indexed inventory by connectionGET/v1/project-vector-store/inventorychevron_right

Project vector store settings

useCustomboolean: When true, indexer and search use url with the stored API key. When false, the platform default cluster is used.
urlstring | null, optional: HTTPS (or HTTP) Qdrant base URL without a trailing slash.
apiKeySetboolean: True when an API key is stored for the custom cluster.
requiredClusterSpecsobject: Minimum allocated cluster size (nodes, RAM, disk, vCPU) enforced when saving BYO settings. Values are set in platform admin.

{
  "useCustom": true,
  "url": "https://ef782a16-4525-4c3d-bd0a-9bc34c8b5b19.us-west-2-0.aws.cloud.qdrant.io",
  "apiKeySet": true,
  "requiredClusterSpecs": {
    "nodes": "1",
    "ram": "4.0 GB",
    "disk": "16.0 GB",
    "vcpu": "0.5 vCPU"
  }
}

Get vector store settings

GET/v1/project-vector-store/settings

Returns the saved mode, custom URL, whether an API key is set, and current minimums.

Requires permission

vector_store:read

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-vector-store/settings" \
  -H "Authorization: Bearer sk_..." \
  -H "X-Workspace-Id: wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "X-Project-Id: prj_01HX2K9V3JEK4WYZN6F0XQ2W8M"

{
  "data": {
  "useCustom": true,
  "url": "https://ef782a16-4525-4c3d-bd0a-9bc34c8b5b19.us-west-2-0.aws.cloud.qdrant.io",
  "apiKeySet": true,
  "requiredClusterSpecs": {
    "nodes": "1",
    "ram": "4.0 GB",
    "disk": "16.0 GB",
    "vcpu": "0.5 vCPU"
  }
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Update vector store settings

PATCH/v1/project-vector-store/settings

Switch to platform default (useCustom: false) or configure BYO Qdrant (useCustom: true with url and usually apiKey). BYO updates run connection + sizing validation before save.

Requires permission

vector_store:update

Parameters

useCustomboolean, optional: Platform default (false) or project custom cluster (true).
urlstring, optional: Required when enabling or changing custom Qdrant.
apiKeystring, optional: Database API key for Qdrant Cloud / secured clusters. Omit to keep stored key.

curl -X PATCH "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-vector-store/settings" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
-d '{
  "useCustom": true,
  "url": "https://your-cluster.us-east-1-0.aws.cloud.qdrant.io",
  "apiKey": "your-database-api-key"
}' \
  -H "X-Workspace-Id: wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "X-Project-Id: prj_01HX2K9V3JEK4WYZN6F0XQ2W8M"

{
  "data": {
  "useCustom": true,
  "url": "https://ef782a16-4525-4c3d-bd0a-9bc34c8b5b19.us-west-2-0.aws.cloud.qdrant.io",
  "apiKeySet": true,
  "requiredClusterSpecs": {
    "nodes": "1",
    "ram": "4.0 GB",
    "disk": "16.0 GB",
    "vcpu": "0.5 vCPU"
  }
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Test connection and sizing

POST/v1/project-vector-store/test

Probes reachability and (for custom URLs) returns clusterSpecs and clusterSpecsValidation without saving. Use before PATCH …/settings.

Requires permission

vector_store:update

Parameters

urlstring, optional: Custom cluster URL to test. Omit to use the saved project URL.
apiKeystring, optional: API key to test. Omit to use the stored key when the project already has one.

curl -X POST "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-vector-store/test" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
-d '{
  "url": "https://your-cluster.us-east-1-0.aws.cloud.qdrant.io",
  "apiKey": "your-database-api-key"
}' \
  -H "X-Workspace-Id: wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "X-Project-Id: prj_01HX2K9V3JEK4WYZN6F0XQ2W8M"

{
  "data": {
  "connection": {
  "connected": true,
  "url": "https://ef782a16-4525-4c3d-bd0a-9bc34c8b5b19.us-west-2-0.aws.cloud.qdrant.io",
  "collectionsOk": true,
  "apiKeyAccepted": true,
  "statusCode": 200,
  "error": null,
  "hint": null
},
  "clusterSpecs": {
    "required": { "nodes": "1", "ram": "4.0 GB", "disk": "16.0 GB", "vcpu": "0.5 vCPU" },
    "reported": {
      "nodes": 1,
      "ram": "4 GB",
      "disk": "16 GB",
      "vcpu": "1 vCPU",
      "source": "sys_metrics",
      "note": null
    },
    "rows": []
  },
  "clusterSpecsValidation": { "ok": true, "issues": [] }
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Probe cluster sizing

POST/v1/project-vector-store/specs

Reads provisioned RAM, disk, and vCPU from Qdrant Cloud /sys_metrics (Kubernetes limits) for a draft or saved custom URL.

Requires permission

vector_store:read

Parameters

urlstring, optional: Cluster URL.
apiKeystring, optional: API key with metrics access.

curl -X POST "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-vector-store/specs" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
-d '{
  "url": "https://your-cluster.us-east-1-0.aws.cloud.qdrant.io",
  "apiKey": "…"
}' \
  -H "X-Workspace-Id: wsp_01HX..." \
  -H "X-Project-Id: prj_01HX..."

{
  "data": {
  "required": {
    "nodes": "1",
    "ram": "4.0 GB",
    "disk": "16.0 GB",
    "vcpu": "0.5 vCPU"
  },
  "reported": {
    "nodes": 1,
    "ram": "4 GB",
    "disk": "16 GB",
    "vcpu": "1 vCPU",
    "source": "sys_metrics",
    "note": null
  },
  "rows": []
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Health check (active cluster)

POST/v1/project-vector-store/health

Tests the cluster currently in use for the project (platform default or saved custom).

Requires permission

vector_store:read

curl -X POST "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-vector-store/health" \
  -H "Authorization: Bearer sk_..." \
  -H "X-Workspace-Id: wsp_01HX..." \
  -H "X-Project-Id: prj_01HX..."

{
  "data": { "connection": {
  "connected": true,
  "url": "https://ef782a16-4525-4c3d-bd0a-9bc34c8b5b19.us-west-2-0.aws.cloud.qdrant.io",
  "collectionsOk": true,
  "apiKeyAccepted": true,
  "statusCode": 200,
  "error": null,
  "hint": null
}, "clusterSpecs": null },
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Indexed inventory by connection

GET/v1/project-vector-store/inventory

Returns transcript and chunk counts for the active cluster (from a live Qdrant scroll when catalog is available) and historical rows per connection key. Optional query previewUrl compares a draft BYO URL before save.

Requires permission

vector_store:read

Parameters

previewUrlstring, optional: Draft custom Qdrant URL to include as a preview row.

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-vector-store/inventory" \
  -H "Authorization: Bearer sk_..." \
  -H "X-Workspace-Id: wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "X-Project-Id: prj_01HX2K9V3JEK4WYZN6F0XQ2W8M"

{
  "data": {
  "activeConnectionKey": "custom:a1b2c3d4e5f67890",
  "activeCluster": "custom",
  "activeLabel": "ef782a16-4525-4c3d-bd0a-9bc34c8b5b19.us-west-2-0.aws.cloud.qdrant.io",
  "collection": "prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "transcriptionCount": 3,
  "chunkCount": 27,
  "countsFromLiveCluster": true,
  "connections": [
    {
      "connectionKey": "custom:a1b2c3d4e5f67890",
      "kind": "custom",
      "label": "ef782a16-4525-4c3d-bd0a-9bc34c8b5b19.us-west-2-0.aws.cloud.qdrant.io",
      "transcriptionCount": 3,
      "chunkCount": 27,
      "isActive": true,
      "isPreview": false
    }
  ]
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}