Skip to main content

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​

NameTypeDescription
KnowledgatorAPI-KeyStringYour API key.
Content-TypeStringmultipart/form-data when uploading files with content, otherwise application/json
KnowledgatorAPI-Model-IDStringOptional 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 name
    • content (Uint8Array, optional): File content for upload
    • When content is provided, the request uses multipart/form-data
    • When only name is provided, it's sent as metadata in filesmetadata field
  • 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, outputs will be a string containing the raw model response

Error Codes​

Status CodeDescription
200OK – Request successful.
400Bad Request – Invalid input or malformed template.
401Unauthorized – Invalid API key.
404Not Found – Invalid endpoint.
413Payload Too Large – Exceeds size limit.
500Internal 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 filesmetadata field as a JSON array
    • When file content is provided, the request uses multipart/form-data with files uploaded in the files field
  • 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