Use files and vector stores

Upload files to the MKA1 API, index them in a vector store, and run semantic search over the resulting document chunks.

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.

CLI

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

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.

CLI

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 }
}'

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.

CLI

mka1 llm vector-stores create-file \
  --vector-store-id vs_abc123 \
  --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.

Search the vector store

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

CLI

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

The response returns ranked matches with file_id, filename, score data, and chunk content.

Typical workflow

Use this sequence for most retrieval setups:

1. Upload the source file.
2. Create a vector store with file_ids, or attach the file later.
3. Wait for file processing to complete.
4. 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.