Simplified API Reference

This page summarizes the main Knowledgator APIs, their endpoints, key parameters, and when to use each one.

Table of Contents

Base URL

https://api.knowledgator.com

Authentication

Most endpoints require an API key in the request headers:

HeaderRequiredDescription
KnowledgatorAPI-KeyYesYour Knowledgator API key.
Content-TypeUsuallyUse application/json for JSON requests and multipart/form-data for file uploads.
KnowledgatorAPI-Model-IDOptionalFine-tuned model or adapter ID for supported inference endpoints.

Use KnowledgatorAPI-Model-ID when you want an inference API to run with a specific fine-tuned model instead of the default model.

Common Concepts

ConceptValuesDescription
Service typener, text-classification, relation-extractionUsed by datasets, raw data, models, and fine-tuning.
Dataset formatjsonl, csv, parquet, jsonSupported upload formats for datasets and raw data.
Paginationoffset, limitUsed by list endpoints. offset starts at 0; limit defaults to 100 in most endpoints and can be up to 10000.
Thresholdfloat, usually 0.0 to 1.0Minimum confidence score for inference results. Default is usually 0.5.

Inference APIs

Use inference APIs when you want to process text or files and receive structured outputs.

The examples below use environment variables so developers can copy and run them without editing the base URL in every request:

For endpoints that support fine-tuned models, add KnowledgatorAPI-Model-ID when you want to use a specific model or adapter:

Comprehend-it

Use Comprehend-it for zero-shot or fine-tuned text classification, such as sentiment analysis, topic detection, routing, intent detection, or assigning documents to custom categories.

POST | /inference/comprehend/

Parameters:

ParameterRequiredDescription
textYesText to classify.
labelsYesCandidate labels or categories to score.
thresholdNoMinimum score required for a returned label.

Expected input:

Full cURL request:

Expected output:

Extract-it: Entity Extraction

Use entity extraction for NER, custom span extraction, document field extraction, knowledge base population, and extracting user-defined concepts from text.

POST | /inference/extract/

Parameters:

ParameterRequiredDescription
textYesText to analyze.
entitiesYesEntity types to extract, such as person, organization, location, or custom labels.
promptNoInstruction that clarifies what should be extracted.
thresholdNoMinimum confidence score for returned spans.

Expected input:

Full cURL request:

Expected output:

Extract-it: Relation Extraction

Use relation extraction for knowledge graph construction, business intelligence, scientific literature mining, legal analysis, and identifying links between extracted entities.

POST | /inference/extract/relations/

Parameters:

ParameterRequiredDescription
textYesText to analyze.
relationsYesCandidate relation names, such as founded_by or headquartered_in.
entitiesNoEntity types to focus on during extraction.
rulesNoOptional post-filters for relation name, allowed entity pairs, and maximum span distance.
promptNoTask-specific instruction.
thresholdNoMinimum confidence score for returned relations.

rules fields:

FieldDescription
relationRelation name the rule applies to.
pairs_filterAllowed [source_entity, target_entity] label pairs.
distanceMaximum character distance between source and target spans.

Expected input:

Full cURL request:

Expected output:

Extract-it: Summarization

Use summarization for extractive summaries, key sentence extraction, meeting notes condensation, research highlights, and legal or policy document review.

POST | /inference/extract/summary/

Parameters:

ParameterRequiredDescription
textYesDocument to summarize.
promptNoInstruction that guides which parts to extract, such as findings, risks, or recommendations.
thresholdNoMinimum confidence score for returned summary spans.

Expected input:

Full cURL request:

Expected output:

Instruct-it

Use Instruct-it for instruction-following extraction, structured JSON generation, document analysis, file-based tasks, and outputs in JSON, string, list, or Markdown format.

POST | /inference/instruct/

Parameters:

ParameterRequiredDescription
textYesMain instruction or prompt.
templateNoJSON string that defines the desired output structure.
filesNoFile references or uploaded files. Use multipart/form-data when uploading content.
output_typeNoDesired output style, such as json, string, list, markdown, code, or another custom hint.

Expected input:

Full cURL request:

Expected output:

For file-based Instruct-it calls, use multipart/form-data instead of JSON:

Open Models: Generic Prediction

Use generic prediction to call a deployed or custom model directly when the model accepts a model-specific request body.

POST | /inference/{model_id}/

Parameters:

ParameterRequiredDescription
model_idYesModel identifier in the URL path.
request bodyYesModel-specific JSON payload.

Expected input:

Full cURL request:

Expected output:

The response shape depends on the deployed model. A typical response looks like this:

Open Models: Method-Based Inference

Use method-based inference when a model exposes named capabilities, such as generate, summarize, or classify.

POST | /inference/{model_id}/{method}/

Parameters:

ParameterRequiredDescription
model_idYesModel identifier in the URL path.
methodYesModel method to call.
request bodyYesMethod-specific JSON payload.

Expected input:

Full cURL request:

Expected output:

The response shape depends on the model method. A typical classification response looks like this:

Dataset API

Use the Dataset API to create, upload, manage, and monitor datasets for training and evaluation.

Dataset Endpoints

ActionMethodEndpointUse when
List datasetsGET/datasets/Browse datasets, filter by type/status, or monitor processing.
Create datasetPOST/datasets/Create a dataset, optionally with an initial file.
Get datasetGET/datasets/{dataset_id}/Check dataset metadata, file count, total size, or processing status.
Update datasetPATCH/datasets/{dataset_id}/Rename a dataset or update its description.
Delete datasetDELETE/datasets/{dataset_id}/Permanently remove an obsolete dataset.
Upload filePOST/datasets/{dataset_id}/files/upload/Add data files to an existing dataset.
List formatsGET/files/formats/datasets/Discover supported dataset formats. This endpoint does not require authentication.

Dataset Parameters

List datasets:

ParameterRequiredDescription
offsetNoPagination offset.
limitNoMaximum results per page.
nameNoFilter by dataset name.
typeNoFilter by ner, text-classification, or relation-extraction.
formatNoFilter by jsonl, csv, parquet, or json.
statusNoFilter by pending, processing, ready, or failed.

Create dataset:

ParameterRequiredDescription
nameYesDataset name.
typeYesService type.
formatYesDataset format.
descriptionNoDataset description.
fileNoInitial file upload. Requires multipart/form-data.

Update dataset:

ParameterRequiredDescription
dataset_idYesDataset identifier in the URL path.
nameNoNew dataset name.
descriptionNoNew dataset description.

At least one of name or description is required for update.

Upload file:

ParameterRequiredDescription
dataset_idYesDataset identifier in the URL path.
fileYesFile to upload. Must match the dataset format.

Raw Data API

Use the Raw Data API to manage individual data items or files independently of datasets. This is useful for targeted ingestion, ad-hoc processing, or file-level data management.

Raw Data Endpoints

ActionMethodEndpointUse when
List raw dataGET/data/Browse individual data records and filter by type or format.
Create raw dataPOST/data/Create a standalone data item, optionally with a file.
Get raw dataGET/data/{id}/Retrieve metadata and processing status for one data item.
Update raw dataPATCH/data/{id}/Update the name or description of one data item.
Delete raw dataDELETE/data/{id}/Permanently remove a raw data item.
Upload raw data filePOST/data/{id}/files/upload/Attach or replace a physical file for a raw data record.

Raw Data Parameters

List raw data:

ParameterRequiredDescription
offsetNoPagination offset.
limitNoMaximum results per page.
nameNoFilter by name.
typeNoFilter by service type.
formatNoFilter by file format.

Create raw data:

ParameterRequiredDescription
nameYesRaw data record name.
typeYesService type.
formatYesData format.
descriptionNoOptional description.
fileNoInitial file upload. Requires multipart/form-data.

Update raw data:

ParameterRequiredDescription
idYesRaw data identifier in the URL path.
nameNoNew record name.
descriptionNoNew record description.

Upload raw data file:

ParameterRequiredDescription
idYesRaw data identifier in the URL path.
fileYesFile to upload. Requires multipart/form-data.

Fine-tuning API

Use the Fine-tuning API to create base models, start training jobs, monitor progress, inspect metrics, and manage completed or failed trainings.

Model Management

ActionMethodEndpointUse when
List model typesGET/trainings/models/types/Discover supported fine-tuning service types.
List modelsGET/trainings/models/Browse base and custom models.
Create base modelPOST/trainings/models/Create a model record to use as the starting point for training.
Get modelGET/trainings/models/{model_id}/Verify model metadata before training or inference.

Model parameters:

ParameterRequiredDescription
nameYes for createModel name.
typeYes for createService type: ner, text-classification, or relation-extraction.
descriptionNoOptional model description.
model_idYes for getModel identifier in the URL path.
offset, limitNo for listPagination controls.
include_baseNo for listWhether list results include base models. Defaults to true.

Training Management

ActionMethodEndpointUse when
List trainingsGET/trainings/Browse training jobs and filter by status or type.
Start trainingPOST/trainings/Fine-tune a model on a dataset.
Get trainingGET/trainings/{training_id}/Check training status, metadata, timestamps, and errors.
Stop trainingPOST/trainings/{training_id}/stop/Cancel a running training job.
Delete trainingDELETE/trainings/{training_id}/Remove an obsolete or failed training job.
List eventsGET/trainings/{training_id}/events/Build progress logs, dashboards, or debug failed trainings.
Get metricsGET/trainings/{training_id}/metrics/{metric}/Retrieve metric series, currently mainly loss.

Start training parameters:

ParameterRequiredDescription
model_idYesBase model ID to fine-tune.
dataset_idYesDataset ID used for training.
hyperparametersNoOptional settings such as learning_rate, batch_size, or epochs.

List trainings parameters:

ParameterRequiredDescription
offsetNoPagination offset.
limitNoMaximum results per page.
statusNoFilter by active, completed, stopped, or failed.
typeNoFilter by service type.

Events and metrics parameters:

ParameterRequiredDescription
training_idYesTraining identifier in the URL path.
metricYes for metricsMetric name. Currently loss is supported.
offsetNoPagination offset.
limitNoMaximum results per page.

Typical Workflows

Classify Text Without Training

  1. Call POST /inference/comprehend/.
  2. Pass text, labels, and optionally threshold.
  3. Use returned label scores in your application.

Extract Entities or Relations

  1. Use POST /inference/extract/ for entities.
  2. Use POST /inference/extract/relations/ for relationships.
  3. Pass custom entity or relation labels directly in the request.
  4. Add a prompt when the extraction task needs more context.

Fine-tune a Model

  1. Create or upload a dataset with /datasets/.
  2. Check that the dataset status is ready.
  3. Create or select a base model with /trainings/models/.
  4. Start training with POST /trainings/.
  5. Monitor status with /trainings/{training_id}/, events, and metrics.
  6. Use the resulting model or adapter ID in inference with KnowledgatorAPI-Model-ID.

Use a Custom Deployed Model

  1. Choose the model_id.
  2. Use POST /inference/{model_id}/ for generic prediction.
  3. Use POST /inference/{model_id}/{method}/ for a specific method exposed by that model.

Common Error Codes

CodeMeaning
200Request successful.
201Resource created successfully.
204Request successful with no response body.
400Invalid input, validation error, or missing required parameter.
401Missing or invalid API key.
403Forbidden, invalid CSRF token, or account limit issue.
404Resource, endpoint, model, method, dataset, data item, or training job not found.
413Payload too large.
500Server-side error.
503Service temporarily unavailable.

We use cookies for analytics to improve your experience. You can accept or reject non-essential cookies.