Instruct-it API
The Instruct-it API provides instruction-following capabilities. It accepts text instructions with optional templates, file references, and output type hints, returning structured JSON responses.
Endpoint
POST https://api.platform.knowledgator.com/inference/instruct/
Headers
| Name | Type | Description |
|---|---|---|
KnowledgatorAPI-Key | String | Your API key. |
Content-Type | String | multipart/form-data when uploading files with content, otherwise application/json |
KnowledgatorAPI-Model-ID | String | Optional LoRA adapter ID for fine-tuned models. |
Request Body
{
"text": "Summarize this policy in 3 bullet points.",
"template": "{\"summary\": \"\", \"key_points\": [], \"risk_level\": \"\"}",
"files": ["file-id-1", "file-id-2"],
"output_type": "json"
}
Parameters
text(string, required): The main instruction/prompt for the model.template(string, optional): JSON string representing a structure the model should fill or emulate. Must be valid JSON when parsed.files(array of objects, optional): File references with optional content:name(string, required): File namecontent(Uint8Array, optional): File content for upload- When
contentis provided, the request usesmultipart/form-data - When only
nameis provided, it's sent as metadata infilesmetadatafield
output_type(string, optional): High-level hint for desired output style:"json"– Return strictly valid JSON"string"– Natural language answer"list"– Array/list format"markdown"– Markdown output- Custom labels like
"test_cases","code", etc.
Response
{
"outputs": {
"summary": "This policy outlines data protection requirements.",
"key_points": [
"All data must be encrypted at rest",
"Access requires multi-factor authentication",
"Data retention period is 7 years"
],
"risk_level": "medium"
}
}
Response Fields
outputs: JSON-serializable value (object, array, string, or nested structure)- If the model returns non-JSON content that cannot be parsed,
outputswill be a string containing the raw model response
- If the model returns non-JSON content that cannot be parsed,
Error Codes
| Status Code | Description |
|---|---|
| 200 | OK – Request successful. |
| 400 | Bad Request – Invalid input or malformed template. |
| 401 | Unauthorized – Invalid API key. |
| 404 | Not Found – Invalid endpoint. |
| 413 | Payload Too Large – Exceeds size limit. |
| 500 | Internal Server Error – Server-side issue. |
Example Usage
SDK Usage
💡 Dedicated SDK Guides: See Python SDK | TypeScript SDK
Basic Usage
TypeScript/JavaScript
import { createClient } from '@knowledgator/typescript-sdk';
const kg = createClient('YOUR_API_KEY');
const result = await kg.instruct.it({
text: "Write a professional email declining a meeting invitation.",
output_type: "string",
model_id: "your-model-id" // Optional
});
console.log(result.outputs);
Python
from knowledgator import Knowledgator
kg = Knowledgator(api_key="YOUR_API_KEY")
result = kg.instruct.it(
text="Write a professional email declining a meeting invitation.",
output_type="string",
model_id="your-model-id" # Optional
)
print(result.outputs)
Structured Output with Template
TypeScript/JavaScript
import { createClient } from 'knowledgator-sdk';
const kg = createClient('YOUR_API_KEY');
const template = {
summary: "",
key_points: [],
risk_level: ""
};
const result = await kg.instruct.it({
text: "Analyze this security policy and provide structured feedback.",
template: JSON.stringify(template),
output_type: "json"
});
console.log(result.outputs.summary);
console.log(result.outputs.key_points);
Python
from knowledgator import Knowledgator
import json
kg = Knowledgator(api_key="YOUR_API_KEY")
template = {
"summary": "",
"key_points": [],
"risk_level": ""
}
result = kg.instruct.it(
text="Analyze this security policy and provide structured feedback.",
template=json.dumps(template),
output_type="json"
)
print(result.outputs["summary"])
print(result.outputs["key_points"])
With File Metadata
TypeScript/JavaScript
import { createClient } from 'knowledgator-sdk';
const kg = createClient('YOUR_API_KEY');
const result = await kg.instruct.it({
text: "Compare the methodologies described in these research papers.",
files: [
{ name: "paper-1.pdf" },
{ name: "paper-2.pdf" }
],
output_type: "markdown"
});
console.log(result.outputs);
Python
from knowledgator import Knowledgator
kg = Knowledgator(api_key="YOUR_API_KEY")
result = kg.instruct.it(
text="Compare the methodologies described in these research papers.",
files=[
{"name": "paper-1.pdf"},
{"name": "paper-2.pdf"}
],
output_type="markdown"
)
print(result.outputs)
With File Content (Multipart Upload)
TypeScript/JavaScript
import { createClient } from '@knowledgator/typescript-sdk';
import { readFile } from 'fs/promises';
const kg = createClient('YOUR_API_KEY');
const fileContent = await readFile('./document.pdf');
const result = await kg.instruct.it({
text: "Summarize this document.",
files: [
{
name: "document.pdf",
content: new Uint8Array(fileContent)
}
],
output_type: "json"
});
console.log(result.outputs);
Python
from knowledgator import Knowledgator
kg = Knowledgator(api_key="YOUR_API_KEY")
with open("document.pdf", "rb") as f:
file_content = f.read()
result = kg.instruct.it(
text="Summarize this document.",
files=[
{
"name": "document.pdf",
"content": file_content
}
],
output_type="json"
)
print(result.outputs)
Expected SDK Output
{
"summary": "This document outlines cybersecurity protocols for enterprise data access.",
"key_points": [
"Zero-trust network architecture required for all remote staff",
"Encryption enforced for data at rest and in transit",
"Quarterly access audits mandated"
],
"risk_level": "medium"
}
Python (requests library)
Simple Text-Only Request
import requests
url = "https://api.platform.knowledgator.com/inference/instruct/"
headers = {
"KnowledgatorAPI-Key": "YOUR_API_KEY",
"KnowledgatorAPI-Model-ID": "your-model-id" # Optional
}
# For text-only requests, use multipart/form-data
data = {
"text": "Write a professional email declining a meeting invitation.",
"output_type": "string"
}
response = requests.post(url, headers=headers, data=data)
print(response.json())
Structured Output with Template
import requests
import json
url = "https://api.platform.knowledgator.com/inference/instruct/"
headers = {
"KnowledgatorAPI-Key": "YOUR_API_KEY"
}
template = {
"summary": "",
"key_points": [],
"risk_level": ""
}
data = {
"text": "Analyze this security policy and provide structured feedback.",
"template": json.dumps(template),
"output_type": "json"
}
response = requests.post(url, headers=headers, data=data)
result = response.json()
print(result["outputs"])
With File Metadata
import requests
import json
url = "https://api.platform.knowledgator.com/inference/instruct/"
headers = {
"KnowledgatorAPI-Key": "YOUR_API_KEY"
}
data = {
"text": "Compare the methodologies described in these research papers.",
"filesmetadata": json.dumps(["paper-1.pdf", "paper-2.pdf"]),
"output_type": "markdown"
}
response = requests.post(url, headers=headers, data=data)
print(response.json())
With File Content (Multipart Upload)
import requests
import json
url = "https://api.platform.knowledgator.com/inference/instruct/"
headers = {
"KnowledgatorAPI-Key": "YOUR_API_KEY"
}
# Prepare multipart form data
data = {
"text": "Summarize this document.",
"filesmetadata": json.dumps(["document.pdf"]),
"output_type": "json"
}
files = {
"files": ("document.pdf", open("document.pdf", "rb"), "application/pdf")
}
response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())
cURL
Simple Text-Only Request
curl -X POST https://api.platform.knowledgator.com/inference/instruct/ \
-H "KnowledgatorAPI-Key: YOUR_API_KEY" \
-H "KnowledgatorAPI-Model-ID: your-model-id" \
-F "text=Write a professional email declining a meeting invitation." \
-F "output_type=string"
Structured Output with Template
curl -X POST https://api.platform.knowledgator.com/inference/instruct/ \
-H "KnowledgatorAPI-Key: YOUR_API_KEY" \
-F "text=Analyze this security policy and provide structured feedback." \
-F 'template={"summary":"","key_points":[],"risk_level":""}' \
-F "output_type=json"
With File Metadata
curl -X POST https://api.platform.knowledgator.com/inference/instruct/ \
-H "KnowledgatorAPI-Key: YOUR_API_KEY" \
-F "text=Compare the methodologies described in these research papers." \
-F 'filesmetadata=["paper-1.pdf","paper-2.pdf"]' \
-F "output_type=markdown"
With File Content (Multipart Upload)
curl -X POST https://api.platform.knowledgator.com/inference/instruct/ \
-H "KnowledgatorAPI-Key: YOUR_API_KEY" \
-F "text=Summarize this document." \
-F 'filesmetadata=["document.pdf"]' \
-F "files=@document.pdf" \
-F "output_type=json"
Expected Response (cURL)
{
"outputs": {
"summary": "This document outlines cybersecurity protocols for enterprise data access.",
"key_points": [
"Zero-trust network architecture required for all remote staff",
"Encryption enforced for data at rest and in transit",
"Quarterly access audits mandated"
],
"risk_level": "medium"
}
}
Additional Information
- File Handling:
- When only file names are provided (metadata), they're sent in the
filesmetadatafield as a JSON array - When file content is provided, the request uses
multipart/form-datawith files uploaded in thefilesfield
- When only file names are provided (metadata), they're sent in the
- Output Flexibility: The API attempts to return valid JSON, but falls back to string if model output cannot be parsed
- Use Cases:
- Document analysis and summarization
- Structured data extraction
- Content generation
- Question answering
- Code generation
- Test case creation