Vector store connectors

A connector mirrors files from an external location into one or more vector stores. You create it once. It then syncs on an interval or on request: new and changed files are indexed, and files deleted, renamed or moved at the source follow in the same sync. Two kinds of location are supported:

`type`	Location
`s3`	A bucket, and optionally a prefix, on AWS S3 or S3-compatible storage.
`sharepoint`	A document library, and optionally a folder, of a SharePoint Online site.

To answer from a database, connect it at query time instead. See Connect a PostgreSQL database with MCP. API Reference:

Vector store connector endpoints

Before you start

Create with an API key. A connector keeps running in the background, and every sync runs as the key that created it. Creating one with a console session is refused. The other calls also accept a console session.
Scopes. The key needs read:files, write:files, read:vector-stores and write:vector-stores to create, change, sync, link, unlink or delete a connector. Listing, retrieving and browsing connectors, and reading their runs and objects, need read:vector-stores.
No end user. Connector endpoints return 400 when the request carries X-On-Behalf-Of. A connector mirrors team knowledge, not one end user’s files, so leave the header off every call on this page.
Who can manage it. The principal that created the connector, and organization admins.
Who can search it. Mirrored files are governed by the access settings of the vector store they are mirrored into. Permissions set at the source, such as who may open a file in SharePoint, are not copied: everyone who can use a linked vector store can search everything the connector mirrors.
Limits. A file larger than 25 MB, or of a type that cannot be indexed, is skipped and reported with the reason. It does not fail the sync.

The console has the same controls under Files & search → Connectors, with a file browser for choosing what to mirror.

Connect S3-compatible storage

Create an access key that can list the bucket and read its objects, and nothing more. On AWS that is s3:ListBucket on the bucket and s3:GetObject on its objects. The connector validates the location and the credential by listing once, so a wrong bucket, region or key is refused at creation with a message that names the problem. With auto_sync on and at least one store in vector_store_ids, the first sync starts at once.

import { SDK } from '@meetkai/mka1';

const sdk = new SDK({ bearerAuth: 'Bearer <mka1-api-key>' });

// No xOnBehalfOf here: connector endpoints reject it with 400.
const connector = await sdk.llm.vectorStores.connectors.create({
  requestBody: {
    type: 's3',
    name: 'Support manuals',
    location: { bucket: 'acme-support-docs', prefix: 'manuals/', region: 'us-west-2' },
    credentials: { accessKeyId: '<access-key-id>', secretAccessKey: '<secret-access-key>' },
    syncIntervalMinutes: 60,
    vectorStoreIds: ['vs_abc123'],
  },
});

console.log(connector.id, connector.status);

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer <mka1-api-key>")

# No x_on_behalf_of here: connector endpoints reject it with 400.
connector = sdk.llm.vector_stores.connectors.create(
    body={
        "type": "s3",
        "name": "Support manuals",
        "location": {"bucket": "acme-support-docs", "prefix": "manuals/", "region": "us-west-2"},
        "credentials": {
            "access_key_id": "<access-key-id>",
            "secret_access_key": "<secret-access-key>",
        },
        "sync_interval_minutes": 60,
        "vector_store_ids": ["vs_abc123"],
    },
)

print(connector.id, connector.status)

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using MeetKai.MKA1.Types.Requests;

var sdk = new SDK(bearerAuth: "Bearer <mka1-api-key>");

// No xOnBehalfOf here: connector endpoints reject it with 400.
var created = await sdk.Llm.VectorStores.Connectors.CreateAsync(
    CreateVectorStoreConnectorRequestBody.CreateS3(new VectorStoreConnectorCreateS3()
    {
        Name = "Support manuals",
        Location = new VectorStoreConnectorS3Location()
        {
            Bucket = "acme-support-docs",
            Prefix = "manuals/",
            Region = "us-west-2",
        },
        Credentials = new VectorStoreConnectorS3Credentials()
        {
            AccessKeyId = "<access-key-id>",
            SecretAccessKey = "<secret-access-key>",
        },
        SyncIntervalMinutes = 60,
        VectorStoreIds = new List<string>() { "vs_abc123" },
    }));

var connector = created.VectorStoreConnector!;
Console.WriteLine($"{connector.Id} {connector.Status}");

mka1 llm vector-stores connectors create --request '{
  "type": "s3",
  "name": "Support manuals",
  "location": {
    "bucket": "acme-support-docs",
    "prefix": "manuals/",
    "region": "us-west-2"
  },
  "credentials": {
    "access_key_id": "<access-key-id>",
    "secret_access_key": "<secret-access-key>"
  },
  "sync_interval_minutes": 60,
  "vector_store_ids": ["vs_abc123"]
}'

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "type": "s3",
    "name": "Support manuals",
    "location": {
      "bucket": "acme-support-docs",
      "prefix": "manuals/",
      "region": "us-west-2"
    },
    "credentials": {
      "access_key_id": "<access-key-id>",
      "secret_access_key": "<secret-access-key>"
    },
    "sync_interval_minutes": 60,
    "vector_store_ids": ["vs_abc123"]
  }'

The response is the connector, abridged here. Credentials are write-only: the connector reports credentials_configured and never returns them.

Response

{
  "id": "vsc_abc123",
  "object": "vector_store.connector",
  "type": "s3",
  "name": "Support manuals",
  "location": { "bucket": "acme-support-docs", "prefix": "manuals/", "region": "us-west-2", "endpoint": null },
  "credentials_configured": true,
  "include_patterns": [],
  "exclude_patterns": [],
  "auto_sync": true,
  "sync_interval_minutes": 60,
  "status": "syncing",
  "vector_store_ids": ["vs_abc123"]
}

For storage other than AWS S3, add location.endpoint with the service’s https address. The location and the chunking strategy are fixed at creation; to change either, create a new connector.

Connect SharePoint Online

The connector reads SharePoint with an app that your Microsoft administrator registers in your own Microsoft Entra tenant. There is no interactive sign-in.

In the Microsoft Entra admin center, register an app and note its Application (client) ID and Directory (tenant) ID.
Give the app a Microsoft Graph application permission to read sites and grant admin consent. Use Sites.Selected to limit the app to the sites you choose, then grant it the read role on each of those sites. Sites.Read.All also works and lets the app read every site in the tenant.
Create a client secret for the app and note its value and its expiry date.

Then create the connector with the site’s address, the document library’s name as SharePoint shows it, and optionally a folder inside the library.

const connector = await sdk.llm.vectorStores.connectors.create({
  requestBody: {
    type: 'sharepoint',
    name: 'Policy library',
    location: {
      siteUrl: 'https://contoso.sharepoint.com/sites/Support',
      library: 'Documents',
      folder: 'Policies',
    },
    credentials: {
      tenantId: '<tenant-id>',
      clientId: '<client-id>',
      clientSecret: '<client-secret>',
    },
    vectorStoreIds: ['vs_abc123'],
  },
});

connector = sdk.llm.vector_stores.connectors.create(
    body={
        "type": "sharepoint",
        "name": "Policy library",
        "location": {
            "site_url": "https://contoso.sharepoint.com/sites/Support",
            "library": "Documents",
            "folder": "Policies",
        },
        "credentials": {
            "tenant_id": "<tenant-id>",
            "client_id": "<client-id>",
            "client_secret": "<client-secret>",
        },
        "vector_store_ids": ["vs_abc123"],
    },
)

var created = await sdk.Llm.VectorStores.Connectors.CreateAsync(
    CreateVectorStoreConnectorRequestBody.CreateSharepoint(new VectorStoreConnectorCreateSharePoint()
    {
        Name = "Policy library",
        Location = new VectorStoreConnectorSharePointLocation()
        {
            SiteUrl = "https://contoso.sharepoint.com/sites/Support",
            Library = "Documents",
            Folder = "Policies",
        },
        Credentials = new VectorStoreConnectorSharePointCredentials()
        {
            TenantId = "<tenant-id>",
            ClientId = "<client-id>",
            ClientSecret = "<client-secret>",
        },
        VectorStoreIds = new List<string>() { "vs_abc123" },
    }));

mka1 llm vector-stores connectors create --request '{
  "type": "sharepoint",
  "name": "Policy library",
  "location": {
    "site_url": "https://contoso.sharepoint.com/sites/Support",
    "library": "Documents",
    "folder": "Policies"
  },
  "credentials": {
    "tenant_id": "<tenant-id>",
    "client_id": "<client-id>",
    "client_secret": "<client-secret>"
  },
  "vector_store_ids": ["vs_abc123"]
}'

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "type": "sharepoint",
    "name": "Policy library",
    "location": {
      "site_url": "https://contoso.sharepoint.com/sites/Support",
      "library": "Documents",
      "folder": "Policies"
    },
    "credentials": {
      "tenant_id": "<tenant-id>",
      "client_id": "<client-id>",
      "client_secret": "<client-secret>"
    },
    "vector_store_ids": ["vs_abc123"]
  }'

When the client secret expires, syncs fail with a message that says so. Replace it with an update; files already mirrored stay in place.

Choose what to mirror

A connector mirrors everything under its prefix or folder unless you narrow it with include_patterns and exclude_patterns. A file is mirrored when it matches at least one include pattern, or there are none, and matches no exclude pattern. Exclude always wins. Patterns are paths relative to the connector’s prefix or folder, and they are case-sensitive:

Pattern	Matches
`*`	Any characters within one folder.
`**`	Any characters across folders.
`?`	One character.
`[abc]`	One character from the set.
`drafts/plan.docx`	That one file. A pattern with no wildcard is an exact path.
`notes\[1\].txt`	The file `notes[1].txt`. A backslash makes the next character literal; in JSON, write each backslash twice.

Browse the location to see what the current rules select. Browsing reads the source live, one folder at a time, works before any sync has run, and changes nothing.

const page = await sdk.llm.vectorStores.connectors.browse({
  connectorId: 'vsc_abc123',
  path: '2026/',
});

for (const entry of page.data) {
  if (entry.kind === 'object') console.log(entry.path, entry.selected);
}

page = sdk.llm.vector_stores.connectors.browse(connector_id="vsc_abc123", path="2026/")

for entry in page.data:
    if entry.kind == "object":
        print(entry.path, entry.selected)

var browsed = await sdk.Llm.VectorStores.Connectors.BrowseAsync(new BrowseVectorStoreConnectorRequest()
{
    ConnectorId = "vsc_abc123",
    Path = "2026/",
});

Console.WriteLine(browsed.VectorStoreConnectorBrowseList!.Data.Count);

mka1 llm vector-stores connectors browse --connector-id vsc_abc123 --path '2026/'

curl 'https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123/browse?path=2026/' \
  --header 'Authorization: Bearer <mka1-api-key>'

Each entry is a folder or an object. An object carries selected, which says whether the current rules mirror it. Pass a folder’s path to open it, and next_cursor as cursor for the next page. Set the rules at creation, or change them later. A rule change starts a sync at once while auto_sync is on, and files the rules no longer select are removed from the index.

await sdk.llm.vectorStores.connectors.update({
  connectorId: 'vsc_abc123',
  requestBody: { excludePatterns: ['drafts/**', '**/*.tmp'] },
});

sdk.llm.vector_stores.connectors.update(
    connector_id="vsc_abc123",
    exclude_patterns=["drafts/**", "**/*.tmp"],
)

await sdk.Llm.VectorStores.Connectors.UpdateAsync(
    connectorId: "vsc_abc123",
    body: new UpdateVectorStoreConnectorRequestBody()
    {
        ExcludePatterns = new List<string>() { "drafts/**", "**/*.tmp" },
    });

mka1 llm vector-stores connectors update \
  --connector-id vsc_abc123 \
  --exclude-patterns 'drafts/**' \
  --exclude-patterns '**/*.tmp'

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123 \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{ "exclude_patterns": ["drafts/**", "**/*.tmp"] }'

Sync

With auto_sync on, the connector syncs every sync_interval_minutes, from 15 minutes to 7 days (10080). With auto_sync off it syncs only when you ask, and the files already mirrored stay as they are. Run a sync once at any time. A request made while a sync is running returns that run.

const run = await sdk.llm.vectorStores.connectors.sync({ connectorId: 'vsc_abc123' });

console.log(run.id, run.status);

run = sdk.llm.vector_stores.connectors.sync(connector_id="vsc_abc123")

print(run.id, run.status)

var synced = await sdk.Llm.VectorStores.Connectors.SyncAsync(connectorId: "vsc_abc123");

Console.WriteLine(synced.VectorStoreConnectorRunSummary!.Id);

mka1 llm vector-stores connectors sync --connector-id vsc_abc123

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123/sync \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>'

Each sync compares the source with what is mirrored:

A new file is uploaded and indexed.
A file whose content changed is replaced. Unchanged files are not downloaded again.
A file that was deleted at the source, or that the rules no longer select, is removed from every linked store.
A renamed or moved file is removed under its old path and added under its new one in the same sync.

Check a sync

The connector’s status is syncing while a run is in progress, error when the last run failed, and idle otherwise. last_run summarizes the most recent run. List the runs, then open one to see every file it skipped or failed and why.

const runs = await sdk.llm.vectorStores.connectors.listRuns({ connectorId: 'vsc_abc123' });

const run = await sdk.llm.vectorStores.connectors.getRun({
  connectorId: 'vsc_abc123',
  runId: 'vscr_abc123',
});

for (const item of run.items) console.log(item.sourcePath, item.status, item.reason);

runs = sdk.llm.vector_stores.connectors.list_runs(connector_id="vsc_abc123")

run = sdk.llm.vector_stores.connectors.get_run(connector_id="vsc_abc123", run_id="vscr_abc123")

for item in run.items:
    print(item.source_path, item.status, item.reason)

var runs = await sdk.Llm.VectorStores.Connectors.ListRunsAsync(new ListVectorStoreConnectorRunsRequest()
{
    ConnectorId = "vsc_abc123",
});

var fetched = await sdk.Llm.VectorStores.Connectors.GetRunAsync(new GetVectorStoreConnectorRunRequest()
{
    ConnectorId = "vsc_abc123",
    RunId = "vscr_abc123",
});

foreach (var item in fetched.VectorStoreConnectorRun!.Items)
{
    Console.WriteLine($"{item.SourcePath} {item.Status} {item.Reason}");
}

mka1 llm vector-stores connectors list-runs --connector-id vsc_abc123

mka1 llm vector-stores connectors get-run --connector-id vsc_abc123 --run-id vscr_abc123

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123/runs \
  --header 'Authorization: Bearer <mka1-api-key>'

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123/runs/vscr_abc123 \
  --header 'Authorization: Bearer <mka1-api-key>'

Response

{
  "id": "vscr_abc123",
  "object": "vector_store.connector.run",
  "status": "completed",
  "trigger": "schedule",
  "added": 12,
  "updated": 3,
  "removed": 1,
  "restored": 0,
  "skipped": 1,
  "failed": 0,
  "error": null,
  "items": [
    {
      "id": "cmhw1x2ab0001",
      "source_path": "manuals/archive/video.mp4",
      "status": "skipped",
      "reason": "The object is 48211003 bytes, above the limit of 26214400"
    }
  ],
  "items_has_more": false
}

To see everything the connector tracks, list its objects. Each one has a status of mirrored, skipped or failed, and a mirrored object carries the file_id of its file.

const skipped = await sdk.llm.vectorStores.connectors.listObjects({
  connectorId: 'vsc_abc123',
  status: 'skipped',
});

skipped = sdk.llm.vector_stores.connectors.list_objects(
    connector_id="vsc_abc123",
    status="skipped",
)

var skipped = await sdk.Llm.VectorStores.Connectors.ListObjectsAsync(new ListVectorStoreConnectorObjectsRequest()
{
    ConnectorId = "vsc_abc123",
    Status = VectorStoreConnectorObjectStatus.Skipped,
});

mka1 llm vector-stores connectors list-objects --connector-id vsc_abc123 --status skipped

curl 'https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123/objects?status=skipped' \
  --header 'Authorization: Bearer <mka1-api-key>'

Search mirrored files

Mirrored files are ordinary vector store files, so search and retrieval in a response work unchanged. Each mirrored file carries two attributes: connector_id, and source_path, the file’s full path as the source shows it. Use them to filter search to one connector, or to show where a result came from.

Link and unlink vector stores

One connector can feed several vector stores. Linking a store attaches the connector’s current files to it at once, without downloading them again.

await sdk.llm.vectorStores.connectors.link({
  connectorId: 'vsc_abc123',
  requestBody: { vectorStoreId: 'vs_def456' },
});

sdk.llm.vector_stores.connectors.link(connector_id="vsc_abc123", vector_store_id="vs_def456")

await sdk.Llm.VectorStores.Connectors.LinkAsync(
    connectorId: "vsc_abc123",
    body: new LinkVectorStoreConnectorRequestBody() { VectorStoreId = "vs_def456" });

mka1 llm vector-stores connectors link --connector-id vsc_abc123 --vector-store-id vs_def456

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123/vector_stores \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{ "vector_store_id": "vs_def456" }'

Unlinking removes the connector’s files from that store. The removal runs in the background. When the last store is unlinked, the connector’s files are deleted, so the next sync after a store is linked downloads everything again.

await sdk.llm.vectorStores.connectors.unlink({
  connectorId: 'vsc_abc123',
  vectorStoreId: 'vs_def456',
});

sdk.llm.vector_stores.connectors.unlink(connector_id="vsc_abc123", vector_store_id="vs_def456")

await sdk.Llm.VectorStores.Connectors.UnlinkAsync(
    connectorId: "vsc_abc123",
    vectorStoreId: "vs_def456");

mka1 llm vector-stores connectors unlink --connector-id vsc_abc123 --vector-store-id vs_def456

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123/vector_stores/vs_def456 \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

To find what feeds a store, list connectors with vector_store_id.

const feeding = await sdk.llm.vectorStores.connectors.list({ vectorStoreId: 'vs_abc123' });

feeding = sdk.llm.vector_stores.connectors.list(vector_store_id="vs_abc123")

var feeding = await sdk.Llm.VectorStores.Connectors.ListAsync(new ListVectorStoreConnectorsRequest()
{
    VectorStoreId = "vs_abc123",
});

mka1 llm vector-stores connectors list --vector-store-id vs_abc123

curl 'https://apigw.mka1.com/api/v1/llm/vector_stores/connectors?vector_store_id=vs_abc123' \
  --header 'Authorization: Bearer <mka1-api-key>'

Change a connector

An update changes the name, the credential, the selection rules or the sync settings. Fields you leave out are unchanged. Rotate the source credential by sending the new one. It takes effect at the next sync.

await sdk.llm.vectorStores.connectors.update({
  connectorId: 'vsc_abc123',
  requestBody: {
    credentials: {
      accessKeyId: '<new-access-key-id>',
      secretAccessKey: '<new-secret-access-key>',
    },
  },
});

sdk.llm.vector_stores.connectors.update(
    connector_id="vsc_abc123",
    credentials={
        "access_key_id": "<new-access-key-id>",
        "secret_access_key": "<new-secret-access-key>",
    },
)

await sdk.Llm.VectorStores.Connectors.UpdateAsync(
    connectorId: "vsc_abc123",
    body: new UpdateVectorStoreConnectorRequestBody()
    {
        Credentials = Credentials.CreateVectorStoreConnectorS3Credentials(
            new VectorStoreConnectorS3Credentials()
            {
                AccessKeyId = "<new-access-key-id>",
                SecretAccessKey = "<new-secret-access-key>",
            }),
    });

mka1 llm vector-stores connectors update \
  --connector-id vsc_abc123 \
  --credentials '{"access_key_id":"<new-access-key-id>","secret_access_key":"<new-secret-access-key>"}'

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123 \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "credentials": {
      "access_key_id": "<new-access-key-id>",
      "secret_access_key": "<new-secret-access-key>"
    }
  }'

Syncs run as the API key that created the connector. If that key is revoked or loses a needed scope, syncs stop and the run reports why; files already mirrored stay in place. To move the connector to a new key, make any update call with another key of the same principal. To stop syncing and keep what is indexed, set auto_sync to false.

Delete a connector

Deleting a connector unlinks it from every store and deletes its files. The removal runs in the background, and the connector shows status: "removing" until it is gone.

await sdk.llm.vectorStores.connectors.delete({ connectorId: 'vsc_abc123' });

sdk.llm.vector_stores.connectors.delete(connector_id="vsc_abc123")

await sdk.Llm.VectorStores.Connectors.DeleteAsync(connectorId: "vsc_abc123");

mka1 llm vector-stores connectors delete --connector-id vsc_abc123

curl https://apigw.mka1.com/api/v1/llm/vector_stores/connectors/vsc_abc123 \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

Get started

SDKs and CLI

Responses

Standalone APIs

Agents

Evals

Compute

Authentication

Production