Use files and vector stores

Use Files to upload documents once. Use Vector Stores to index those files for semantic search and retrieval. This is the standard pattern for document-backed assistants, retrieval workflows, and grounded responses.

Upload a file

Upload the file with multipart/form-data. The live OpenAPI spec requires file and purpose.

mka1 llm files upload \
  --file ./support-manual.pdf \
  --purpose assistants \
  -H 'X-On-Behalf-Of: <end-user-id>'

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

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

const file = Bun.file('./support-manual.pdf');
const result = await mka1.llm.files.upload({
  xOnBehalfOf: '<end-user-id>', // optional — attribute the request to one of your end users
  requestBody: { file, purpose: 'assistants' },
});

import OpenAI from 'openai';
import fs from 'fs';

const openai = new OpenAI({
  apiKey: '<mka1-api-key>',
  baseURL: 'https://apigw.mka1.com/api/v1/llm',
  defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
});

const file = await openai.files.create({
  file: fs.createReadStream('./support-manual.pdf'),
  purpose: 'assistants',
});

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

var sdk = new SDK(
    bearerAuth: $"Bearer {YOUR_API_KEY}",
    serverUrl: "https://apigw.mka1.com"
);

var res = await sdk.Llm.Files.UploadAsync(new UploadFileRequestBody()
{
    File = new UploadFileFile()
    {
        FileName = "support-manual.pdf",
        Content = System.IO.File.ReadAllBytes("./support-manual.pdf"),
    },
    Purpose = UploadFilePurpose.Assistants,
});

from mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

result = sdk.llm.files.upload(
    file={
        "file_name": "support-manual.pdf",
        "content": open("./support-manual.pdf", "rb"),
    },
    purpose="assistants",
)

curl https://apigw.mka1.com/api/v1/llm/files \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --form 'file=@./support-manual.pdf' \
  --form 'purpose=assistants'

The response returns a file object with an ID such as file-abc123.

Create a vector store

Create a vector store and attach one or more uploaded file IDs.

mka1 llm vector-stores create --body '{
  "name": "Support knowledge base",
  "description": "Indexed support manuals and help center docs",
  "file_ids": ["file-abc123"],
  "expires_after": { "anchor": "last_active_at", "days": 30 }
}'

const vectorStore = await mka1.llm.vectorStores.create({
  xOnBehalfOf: '<end-user-id>',
  createVectorStoreRequest: {
    name: 'Support knowledge base',
    description: 'Indexed support manuals and help center docs',
    fileIds: ['file-abc123'],
    expiresAfter: { anchor: 'last_active_at', days: 30 },
  },
});

const vectorStore = await openai.vectorStores.create({
  name: 'Support knowledge base',
  description: 'Indexed support manuals and help center docs',
  file_ids: ['file-abc123'],
  expires_after: { anchor: 'last_active_at', days: 30 },
});

var vs = await sdk.Llm.VectorStores.CreateAsync(new CreateVectorStoreRequest()
{
    Name = "Support knowledge base",
    Description = "Indexed support manuals and help center docs",
});

vector_store = sdk.llm.vector_stores.create(
    name="Support knowledge base",
    description="Indexed support manuals and help center docs",
)

curl https://apigw.mka1.com/api/v1/llm/vector_stores \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "Support knowledge base",
    "description": "Indexed support manuals and help center docs",
    "file_ids": [
      "file-abc123"
    ],
    "expires_after": {
      "anchor": "last_active_at",
      "days": 30
    }
  }'

This response returns a vector store ID such as vs_abc123.

Add more files later

You can add more files to an existing vector store without recreating it.

mka1 llm vector-stores create-file \
  --vector-store-id vs_abc123 \
  --file-id file-def456 \
  --attributes '{"category":"manual","version":"2.0"}'

const vsFile = await mka1.llm.vectorStores.createFile({
  vectorStoreId: 'vs_abc123',
  xOnBehalfOf: '<end-user-id>',
  createVectorStoreFileRequest: {
    fileId: 'file-def456',
    attributes: { category: 'manual', version: '2.0' },
  },
});

const vsFile = await openai.vectorStores.files.create('vs_abc123', {
  file_id: 'file-def456',
});

// Adding files to an existing vector store is done via the
// VectorStores.CreateFile or VectorStores.Files API methods.
// Refer to the API reference for the full method signature.

vs_file = sdk.llm.vector_stores.create_file(
    vector_store_id="vs_abc123",
    file_id="file-def456",
)

curl https://apigw.mka1.com/api/v1/llm/vector_stores/vs_abc123/files \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "file_id": "file-def456",
    "attributes": {
      "category": "manual",
      "version": "2.0"
    }
  }'

The vector store file can return status: "in_progress" while indexing runs. Check the Files and Vector Stores endpoints in the API Reference if you need to poll for status.

List files with pagination

File listings are sorted by created_at (newest first by default) and return up to limit items per page. When has_more is true, pass the last item’s id as after to fetch the next page.

mka1 llm vector-stores list-files \
  --vector-store-id vs_abc123 \
  --limit 5 \
  --after file-def456

let after: string | undefined;
do {
  const page = await mka1.llm.vectorStores.listFiles({
    vectorStoreId: 'vs_abc123',
    limit: 5,
    after,
    xOnBehalfOf: '<end-user-id>',
  });
  for (const vsFile of page.data) {
    console.log(vsFile.id);
  }
  after = page.hasMore ? page.lastId : undefined;
} while (after);

// The OpenAI SDK auto-paginates: iterate and it follows the cursor for you.
for await (const vsFile of openai.vectorStores.files.list('vs_abc123', {
  limit: 5,
})) {
  console.log(vsFile.id);
}

// Listing is available via the VectorStores.ListFiles method; pass the last
// item's id as `after` while `has_more` is true.
// Refer to the API reference for the full method signature.

after = None
while True:
    page = sdk.llm.vector_stores.list_files(
        vector_store_id="vs_abc123",
        limit=5,
        after=after,
    )
    for vs_file in page.data:
        print(vs_file.id)
    if not page.has_more:
        break
    after = page.last_id

curl "https://apigw.mka1.com/api/v1/llm/vector_stores/vs_abc123/files?limit=5&after=file-def456" \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

To page backwards, pass an item’s id as before instead: the response is the page immediately preceding that item in the display order. Files attached in the same batch can share a creation timestamp; the cursor accounts for this, so a full walk returns every file exactly once. If a cursor’s file no longer exists — for example, it was removed from the vector store while you were paging — the API returns 400 Invalid pagination cursor. Restart the walk from the first page.

Search the vector store

Use semantic search to retrieve the most relevant chunks for a user question.

mka1 llm vector-stores search \
  --vector-store-id vs_abc123 \
  --body '{
    "query": "How do I reset my password?",
    "max_num_results": 5
  }'

const results = await mka1.llm.vectorStores.search({
  vectorStoreId: 'vs_abc123',
  xOnBehalfOf: '<end-user-id>',
  searchVectorStoreRequest: {
    query: 'How do I reset my password?',
    maxNumResults: 5,
  },
});

const results = await openai.vectorStores.search('vs_abc123', {
  query: 'How do I reset my password?',
  max_num_results: 5,
});

// Search is available via the VectorStores.Search method.
// Refer to the API reference for the full method signature.

results = sdk.llm.vector_stores.search(
    vector_store_id="vs_abc123",
    query="How do I reset my password?",
)

curl https://apigw.mka1.com/api/v1/llm/vector_stores/vs_abc123/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "query": "How do I reset my password?",
    "max_num_results": 5
  }'

The response returns ranked matches with file_id, filename, score data, chunk content, and the file’s current attributes.

Filter search by file attributes

Attributes are file-level key-value metadata — string, number, or boolean values — set when you attach a file (see Add more files later). You can change them after ingest with the update-file endpoint (POST /vector_stores/{vector_store_id}/files/{file_id}); search always evaluates the current values. Pass filters in the search request to restrict results to files whose attributes match. A filter is either a comparison — eq, ne, gt, gte, lt, lte, in, nin — or an and/or compound of nested filters.

mka1 llm vector-stores search \
  --vector-store-id vs_abc123 \
  --body '{
    "query": "How do I reset my password?",
    "max_num_results": 5,
    "filters": {
      "type": "and",
      "filters": [
        { "type": "eq", "key": "category", "value": "manual" },
        { "type": "ne", "key": "version", "value": "1.0" }
      ]
    }
  }'

const results = await mka1.llm.vectorStores.search({
  vectorStoreId: 'vs_abc123',
  xOnBehalfOf: '<end-user-id>',
  searchVectorStoreRequest: {
    query: 'How do I reset my password?',
    maxNumResults: 5,
    filters: {
      type: 'and',
      filters: [
        { type: 'eq', key: 'category', value: 'manual' },
        { type: 'ne', key: 'version', value: '1.0' },
      ],
    },
  },
});

const results = await openai.vectorStores.search('vs_abc123', {
  query: 'How do I reset my password?',
  max_num_results: 5,
  filters: {
    type: 'and',
    filters: [
      { type: 'eq', key: 'category', value: 'manual' },
      { type: 'ne', key: 'version', value: '1.0' },
    ],
  },
});

// Filtered search is available via the VectorStores.Search method's Filters
// parameter (ComparisonFilter / CompoundFilter).
// Refer to the API reference for the full method signature.

results = sdk.llm.vector_stores.search(
    vector_store_id="vs_abc123",
    query="How do I reset my password?",
    filters={
        "type": "and",
        "filters": [
            {"type": "eq", "key": "category", "value": "manual"},
            {"type": "ne", "key": "version", "value": "1.0"},
        ],
    },
)

curl https://apigw.mka1.com/api/v1/llm/vector_stores/vs_abc123/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "query": "How do I reset my password?",
    "max_num_results": 5,
    "filters": {
      "type": "and",
      "filters": [
        { "type": "eq", "key": "category", "value": "manual" },
        { "type": "ne", "key": "version", "value": "1.0" }
      ]
    }
  }'

Filter evaluation follows these rules:

A file that does not have the filter’s key never matches — including for ne and nin. A filter only opts a file in on evidence, never by absence.
eq and ne are strict equality with no type coercion: the string "2" does not equal the number 2.
gt, gte, lt, and lte compare numbers only; a non-numeric attribute or filter value fails the comparison.
in and nin take an array value and test whether the file’s attribute is (or is not) one of its elements.
and and or compounds nest to any depth.
On graph stores (GraphRAG), filtering is applied after retrieval, so a filtered search can return fewer than max_num_results matches.

Typical workflow

Use this sequence for most retrieval setups:

Upload the source file.
Create a vector store with file_ids, or attach the file later.
Wait for file processing to complete.
Search the vector store when you need relevant context.

You can then feed the returned text into your own application logic or a Responses request.

Getting started

Responses

Features

CLI

Recipes

Benchmarks

Infrastructure

Use files and vector stores

Upload a file

Create a vector store

Add more files later

Search the vector store

Filter search by file attributes

Typical workflow

​Upload a file

​Create a vector store

​Add more files later

​List files with pagination

​Search the vector store

​Filter search by file attributes

​Typical workflow

Upload a file

Create a vector store

Add more files later

List files with pagination

Search the vector store

Filter search by file attributes

Typical workflow