Skip to main content

Create Dataset

Create a new dataset entry on the Knowledgator platform with an initial JSON data file.

Endpoint​

POST https://api.platform.knowledgator.com/datasets/


Headers​

NameTypeDescription
KnowledgatorAPI-KeyStringYour API key
Content-TypeStringmultipart/form-data

Request Parameters (multipart/form-data)​

ParameterTypeRequiredDescription
fileBinary FileYesDataset file to upload (must be valid JSON, .json).
typeStringYesService task type: comprehend-it (classification), extract-it (NER / extraction), or instruct-it (instruction tuning / text2json).
formatStringYesDataset format. Strictly json per OpenAPI schema.
nameStringNoDataset name (2-64 characters, regex ^[a-zA-Z0-9- .()]+$).
short_descriptionStringNoShort dataset description or notes (max 1024 characters).

Response​

{
"id": "6babd48a-2256-4466-b16b-9fd45ba59688",
"status": "pending"
}

Response Fields​

  • id: Unique dataset identifier (UUID).
  • status: Initial validation and processing status (pending, valid, or invalid).

Error Codes​

Status CodeDescription
201Created – Dataset created and file queued for processing.
400Bad Request – Invalid format, illegal characters in name, or validation error.
401Unauthorized – Invalid or missing API key.
403Forbidden – Permission denied or subscription plan limit exceeded.
422Unprocessable Entity – Validation failed (e.g. format other than json).
500Internal Server Error – Server-side error.

Example Usage​

SDK Usage​

💡 Dedicated SDK Guides: See Python SDK | TypeScript SDK

TypeScript / JavaScript​

import { createClient } from '@knowledgator/typescript-sdk';
import { readFile } from 'fs/promises';

const kg = createClient('YOUR_API_KEY');

const fileBuffer = await readFile('./products_dataset.json');
const dataset = await kg.datasets.create({
name: "Ecomm Categories v1.1",
type: "comprehend-it",
format: "json",
short_description: "E-commerce product category classification",
file: new File([fileBuffer], 'products_dataset.json')
});

console.log(dataset.id, dataset.status);

Python SDK​

from knowledgator import Knowledgator

kg = Knowledgator(api_key="YOUR_API_KEY")

with open("products_dataset.json", "rb") as f:
dataset = kg.datasets.create(
name="Ecomm Categories v1.1",
type="comprehend-it",
format="json",
short_description="E-commerce product category classification",
file=f
)

print(dataset.id, dataset.status)

Expected SDK Output​

6babd48a-2256-4466-b16b-9fd45ba59688 pending

Python (Requests)​

import requests

url = "https://api.platform.knowledgator.com/datasets/"
headers = {
"KnowledgatorAPI-Key": "YOUR_API_KEY"
}

data = {
"name": "Ecomm Categories v1.1",
"type": "comprehend-it",
"format": "json",
"short_description": "E-commerce product category classification"
}

with open("products_dataset.json", "rb") as f:
files = {"file": ("products_dataset.json", f, "application/json")}
response = requests.post(url, headers=headers, data=data, files=files)

print(response.json())

Expected Response (Python Requests)​

{
"id": "6babd48a-2256-4466-b16b-9fd45ba59688",
"status": "pending"
}

cURL​

curl -X POST "https://api.platform.knowledgator.com/datasets/" \
-H "KnowledgatorAPI-Key: YOUR_API_KEY" \
-F "name=Ecomm Categories v1.1" \
-F "type=comprehend-it" \
-F "format=json" \
-F "short_description=E-commerce product category classification" \
-F "file=@products_dataset.json;type=application/json"

Expected Response (cURL)​

{
"id": "6babd48a-2256-4466-b16b-9fd45ba59688",
"status": "pending"
}

Additional Information​

  • Strict JSON Format: The Knowledgator API strictly enforces json for dataset uploads.
  • Service Type Mapping: Use comprehend-it for classification, extract-it for entity extraction / NER, and instruct-it for JSON instruction generation.
  • Status Lifecycle: A created dataset starts in pending status while the file is validated and converted into platform tensors. Once validated, status transitions to valid.