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
- Authentication
- Common Concepts
- Inference APIs
- Dataset API
- Raw Data API
- Fine-tuning API
- Typical Workflows
- Common Error Codes
Base URL
https://api.knowledgator.com
Authentication
Most endpoints require an API key in the request headers:
| Header | Required | Description |
|---|---|---|
KnowledgatorAPI-Key | Yes | Your Knowledgator API key. |
Content-Type | Usually | Use application/json for JSON requests and multipart/form-data for file uploads. |
KnowledgatorAPI-Model-ID | Optional | Fine-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
| Concept | Values | Description |
|---|---|---|
| Service type | ner, text-classification, relation-extraction | Used by datasets, raw data, models, and fine-tuning. |
| Dataset format | jsonl, csv, parquet, json | Supported upload formats for datasets and raw data. |
| Pagination | offset, limit | Used by list endpoints. offset starts at 0; limit defaults to 100 in most endpoints and can be up to 10000. |
| Threshold | float, usually 0.0 to 1.0 | Minimum 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:
| Parameter | Required | Description |
|---|---|---|
text | Yes | Text to classify. |
labels | Yes | Candidate labels or categories to score. |
threshold | No | Minimum 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:
| Parameter | Required | Description |
|---|---|---|
text | Yes | Text to analyze. |
entities | Yes | Entity types to extract, such as person, organization, location, or custom labels. |
prompt | No | Instruction that clarifies what should be extracted. |
threshold | No | Minimum 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:
| Parameter | Required | Description |
|---|---|---|
text | Yes | Text to analyze. |
relations | Yes | Candidate relation names, such as founded_by or headquartered_in. |
entities | No | Entity types to focus on during extraction. |
rules | No | Optional post-filters for relation name, allowed entity pairs, and maximum span distance. |
prompt | No | Task-specific instruction. |
threshold | No | Minimum confidence score for returned relations. |
rules fields:
| Field | Description |
|---|---|
relation | Relation name the rule applies to. |
pairs_filter | Allowed [source_entity, target_entity] label pairs. |
distance | Maximum 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:
| Parameter | Required | Description |
|---|---|---|
text | Yes | Document to summarize. |
prompt | No | Instruction that guides which parts to extract, such as findings, risks, or recommendations. |
threshold | No | Minimum 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:
| Parameter | Required | Description |
|---|---|---|
text | Yes | Main instruction or prompt. |
template | No | JSON string that defines the desired output structure. |
files | No | File references or uploaded files. Use multipart/form-data when uploading content. |
output_type | No | Desired 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:
| Parameter | Required | Description |
|---|---|---|
model_id | Yes | Model identifier in the URL path. |
| request body | Yes | Model-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:
| Parameter | Required | Description |
|---|---|---|
model_id | Yes | Model identifier in the URL path. |
method | Yes | Model method to call. |
| request body | Yes | Method-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
| Action | Method | Endpoint | Use when |
|---|---|---|---|
| List datasets | GET | /datasets/ | Browse datasets, filter by type/status, or monitor processing. |
| Create dataset | POST | /datasets/ | Create a dataset, optionally with an initial file. |
| Get dataset | GET | /datasets/{dataset_id}/ | Check dataset metadata, file count, total size, or processing status. |
| Update dataset | PATCH | /datasets/{dataset_id}/ | Rename a dataset or update its description. |
| Delete dataset | DELETE | /datasets/{dataset_id}/ | Permanently remove an obsolete dataset. |
| Upload file | POST | /datasets/{dataset_id}/files/upload/ | Add data files to an existing dataset. |
| List formats | GET | /files/formats/datasets/ | Discover supported dataset formats. This endpoint does not require authentication. |
Dataset Parameters
List datasets:
| Parameter | Required | Description |
|---|---|---|
offset | No | Pagination offset. |
limit | No | Maximum results per page. |
name | No | Filter by dataset name. |
type | No | Filter by ner, text-classification, or relation-extraction. |
format | No | Filter by jsonl, csv, parquet, or json. |
status | No | Filter by pending, processing, ready, or failed. |
Create dataset:
| Parameter | Required | Description |
|---|---|---|
name | Yes | Dataset name. |
type | Yes | Service type. |
format | Yes | Dataset format. |
description | No | Dataset description. |
file | No | Initial file upload. Requires multipart/form-data. |
Update dataset:
| Parameter | Required | Description |
|---|---|---|
dataset_id | Yes | Dataset identifier in the URL path. |
name | No | New dataset name. |
description | No | New dataset description. |
At least one of name or description is required for update.
Upload file:
| Parameter | Required | Description |
|---|---|---|
dataset_id | Yes | Dataset identifier in the URL path. |
file | Yes | File 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
| Action | Method | Endpoint | Use when |
|---|---|---|---|
| List raw data | GET | /data/ | Browse individual data records and filter by type or format. |
| Create raw data | POST | /data/ | Create a standalone data item, optionally with a file. |
| Get raw data | GET | /data/{id}/ | Retrieve metadata and processing status for one data item. |
| Update raw data | PATCH | /data/{id}/ | Update the name or description of one data item. |
| Delete raw data | DELETE | /data/{id}/ | Permanently remove a raw data item. |
| Upload raw data file | POST | /data/{id}/files/upload/ | Attach or replace a physical file for a raw data record. |
Raw Data Parameters
List raw data:
| Parameter | Required | Description |
|---|---|---|
offset | No | Pagination offset. |
limit | No | Maximum results per page. |
name | No | Filter by name. |
type | No | Filter by service type. |
format | No | Filter by file format. |
Create raw data:
| Parameter | Required | Description |
|---|---|---|
name | Yes | Raw data record name. |
type | Yes | Service type. |
format | Yes | Data format. |
description | No | Optional description. |
file | No | Initial file upload. Requires multipart/form-data. |
Update raw data:
| Parameter | Required | Description |
|---|---|---|
id | Yes | Raw data identifier in the URL path. |
name | No | New record name. |
description | No | New record description. |
Upload raw data file:
| Parameter | Required | Description |
|---|---|---|
id | Yes | Raw data identifier in the URL path. |
file | Yes | File 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
| Action | Method | Endpoint | Use when |
|---|---|---|---|
| List model types | GET | /trainings/models/types/ | Discover supported fine-tuning service types. |
| List models | GET | /trainings/models/ | Browse base and custom models. |
| Create base model | POST | /trainings/models/ | Create a model record to use as the starting point for training. |
| Get model | GET | /trainings/models/{model_id}/ | Verify model metadata before training or inference. |
Model parameters:
| Parameter | Required | Description |
|---|---|---|
name | Yes for create | Model name. |
type | Yes for create | Service type: ner, text-classification, or relation-extraction. |
description | No | Optional model description. |
model_id | Yes for get | Model identifier in the URL path. |
offset, limit | No for list | Pagination controls. |
include_base | No for list | Whether list results include base models. Defaults to true. |
Training Management
| Action | Method | Endpoint | Use when |
|---|---|---|---|
| List trainings | GET | /trainings/ | Browse training jobs and filter by status or type. |
| Start training | POST | /trainings/ | Fine-tune a model on a dataset. |
| Get training | GET | /trainings/{training_id}/ | Check training status, metadata, timestamps, and errors. |
| Stop training | POST | /trainings/{training_id}/stop/ | Cancel a running training job. |
| Delete training | DELETE | /trainings/{training_id}/ | Remove an obsolete or failed training job. |
| List events | GET | /trainings/{training_id}/events/ | Build progress logs, dashboards, or debug failed trainings. |
| Get metrics | GET | /trainings/{training_id}/metrics/{metric}/ | Retrieve metric series, currently mainly loss. |
Start training parameters:
| Parameter | Required | Description |
|---|---|---|
model_id | Yes | Base model ID to fine-tune. |
dataset_id | Yes | Dataset ID used for training. |
hyperparameters | No | Optional settings such as learning_rate, batch_size, or epochs. |
List trainings parameters:
| Parameter | Required | Description |
|---|---|---|
offset | No | Pagination offset. |
limit | No | Maximum results per page. |
status | No | Filter by active, completed, stopped, or failed. |
type | No | Filter by service type. |
Events and metrics parameters:
| Parameter | Required | Description |
|---|---|---|
training_id | Yes | Training identifier in the URL path. |
metric | Yes for metrics | Metric name. Currently loss is supported. |
offset | No | Pagination offset. |
limit | No | Maximum results per page. |
Typical Workflows
Classify Text Without Training
- Call
POST /inference/comprehend/. - Pass
text,labels, and optionallythreshold. - Use returned label scores in your application.
Extract Entities or Relations
- Use
POST /inference/extract/for entities. - Use
POST /inference/extract/relations/for relationships. - Pass custom entity or relation labels directly in the request.
- Add a
promptwhen the extraction task needs more context.
Fine-tune a Model
- Create or upload a dataset with
/datasets/. - Check that the dataset status is
ready. - Create or select a base model with
/trainings/models/. - Start training with
POST /trainings/. - Monitor status with
/trainings/{training_id}/, events, and metrics. - Use the resulting model or adapter ID in inference with
KnowledgatorAPI-Model-ID.
Use a Custom Deployed Model
- Choose the
model_id. - Use
POST /inference/{model_id}/for generic prediction. - Use
POST /inference/{model_id}/{method}/for a specific method exposed by that model.
Common Error Codes
| Code | Meaning |
|---|---|
200 | Request successful. |
201 | Resource created successfully. |
204 | Request successful with no response body. |
400 | Invalid input, validation error, or missing required parameter. |
401 | Missing or invalid API key. |
403 | Forbidden, invalid CSRF token, or account limit issue. |
404 | Resource, endpoint, model, method, dataset, data item, or training job not found. |
413 | Payload too large. |
500 | Server-side error. |
503 | Service temporarily unavailable. |