KV API Documentation

Overview

The Create Context endpoint is an asynchronous endpoint that runs processing in the background. It allows you to upload files and textual information to create a new user context. Contexts can be either a domain_context (which dictates WHAT the agent knows, like rules and terminology) or an agent_context (which dictates HOW the agent behaves, like format, tone, and style).

Upon successful submission, the endpoint returns a context_id. You can use this context_id with the Get Context Data endpoint to retrieve data and check the processing status of the context.

Use this endpoint to:

Upload context files (e.g., guidelines, knowledge documents)
Provide textual context directly
Categorize contexts with tags

Endpoint Details

Method: POST
Endpoint: /api/user_context/create
Base URL: https://api.k-v.ai
Authentication: Access Key (Required)

Request Specification

Headers

Header	Type	Required	Description
access-key	string	Yes	Your unique access-key generated from the platform UI

Form Data (multipart/form-data)

Field	Type	Required	Description
files	array	No	Array of files to attach to this context
context_name	string	Yes	Name of the context
description	string	No	Description of the context
tags	string	No	Comma-separated tags for the context
textual_context	string	No	Direct textual instructions or knowledge
context_type	string	No	Either `domain_context` or `agent_context`

Code Snippets

curl --location 'https://api.k-v.ai/api/user_context/create' \
--header 'access-key: YOUR_ACCESS_KEY' \
--form 'context_name="My Domain Rules"' \
--form 'context_type="domain_context"' \
--form 'textual_context="Always follow the company guidelines."' \
--form 'files=@"/path/to/guidelines.pdf"'

import requests

url = "https://api.k-v.ai/api/user_context/create"

payload = {
  'context_name': 'My Domain Rules',
  'context_type': 'domain_context',
  'textual_context': 'Always follow the company guidelines.'
}
files = [
  ('files', ('guidelines.pdf', open('/path/to/guidelines.pdf', 'rb'), 'application/pdf'))
]
headers = {
  'access-key': 'YOUR_ACCESS_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

let data = new FormData();
data.append('context_name', 'My Domain Rules');
data.append('context_type', 'domain_context');
data.append('textual_context', 'Always follow the company guidelines.');
data.append('files', fs.createReadStream('/path/to/guidelines.pdf'));

let config = {
  method: 'post',
  url: 'https://api.k-v.ai/api/user_context/create',
  headers: { 
    'access-key': 'YOUR_ACCESS_KEY', 
    ...data.getHeaders()
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Specification

Success Response (200 OK)

{
  "data": {
    "context_id": 66,
    "unsupported_files": [],
    "large_files": []
  },
  "message": "Files uploaded successfully"
}

Response Fields

Field	Type	Description
data.large_files	array	List of files that exceeded the size limit
data.unsupported_files	array	List of files with unsupported formats
data.context_id	integer	Unique identifier for the created context, used to get context data and status
message	string	Human-readable response message

Error Responses

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "context_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Cause: Missing required fields or invalid parameters.

Next Steps

After creating a context:

View your context using Get All Contexts
Apply the context ID in Knowledge Search workflows

Explore the full API specifications in the User Context API Reference.

Create Context

On this page