Skip to main content

Relation Extraction

Extract relationships between entities in text.


Endpoint​

POST https://api.platform.knowledgator.com/inference/extract/


Headers​

NameTypeDescription
KnowledgatorAPI-KeyStringYour API key (required).
Content-TypeStringapplication/json
KnowledgatorAPI-Model-IDStringOptional LoRA adapter ID for fine-tuned models.

Request Body​

{
"input": "Steve Jobs founded Apple Inc. in Cupertino, California.",
"tasks": {
"entities": {
"type": "span",
"labels": ["person", "organization", "location"],
"threshold": 0.5,
"flat": false
},
"relations": {
"type": "relation",
"labels": ["founded", "located_in"],
"flat": false,
"entity_labels": ["person", "organization", "location"],
"threshold": 0.5
}
},
"options": {
"include_usage": true
}
}

Parameters​

  • input (string, required): Input text to analyze.
  • tasks (object, required): Dictionary of analysis tasks:
    • entities: Optional span extraction task defining candidate entity types (labels) and confidence threshold.
    • relations: Relation extraction task defining candidate relation labels (labels), allowed entity types (entity_labels), and confidence threshold.
  • options (object, optional): Inference options such as include_usage or adapter_id.

Response​

{
"outputs": {
"entities": {
"type": "span",
"value": [
{
"label": "person",
"text": "Steve Jobs",
"start": 1,
"end": 11,
"source": "",
"score": 0.9997
},
{
"label": "organization",
"text": "Apple Inc.",
"start": 20,
"end": 30,
"source": "",
"score": 0.9995
},
{
"label": "location",
"text": "Cupertino",
"start": 34,
"end": 43,
"source": "",
"score": 0.8948
},
{
"label": "location",
"text": "California",
"start": 45,
"end": 55,
"source": "",
"score": 0.8948
}
],
"threshold": 0.5
},
"relations": {
"type": "relation",
"value": [
{
"head": {
"label": "person",
"text": "Steve Jobs",
"start": 1,
"end": 11,
"source": ""
},
"relation": "founded",
"tail": {
"label": "organization",
"text": "Apple Inc.",
"start": 20,
"end": 30,
"source": ""
},
"score": 0.9961
},
{
"head": {
"label": "organization",
"text": "Apple Inc.",
"start": 20,
"end": 30,
"source": ""
},
"relation": "located_in",
"tail": {
"label": "location",
"text": "California",
"start": 45,
"end": 55,
"source": ""
},
"score": 0.5938
},
{
"head": {
"label": "location",
"text": "Cupertino",
"start": 34,
"end": 43,
"source": ""
},
"relation": "located_in",
"tail": {
"label": "location",
"text": "California",
"start": 45,
"end": 55,
"source": ""
},
"score": 0.5938
}
],
"threshold": 0.5
}
}
}

Response Fields​

  • outputs: Dictionary of completed tasks keyed by task name
    • relations: Relation extraction task result
      • value: Array of extracted relation objects
        • head: Head entity object (label, text, start, end, source)
        • relation: Predicted relationship type
        • tail: Tail entity object (label, text, start, end, source)
        • score: Model confidence score for this relation

Error Codes​

Status CodeDescription
200OK – Request successful.
400Bad Request – Invalid or incomplete input.
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

TypeScript/JavaScript​

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

const kg = createClient('YOUR_API_KEY');

const result = await kg.extract.it({
text: "Steve Jobs founded Apple Inc. in Cupertino, California.",
tasks: {
entities: {
type: "span",
labels: ["person", "organization", "location"],
threshold: 0.5,
},
relations: {
type: "relation",
labels: ["founded", "located_in"],
entity_labels: ["person", "organization", "location"],
threshold: 0.5,
},
},
adapter_id: "your-lora-adapter-id", // Optional LoRA adapter
});

const relationsTask = result.outputs.relations;
if (Array.isArray(relationsTask.value)) {
for (const rel of relationsTask.value) {
console.log(`${rel.head.text} (${rel.head.label}) --[${rel.relation}]--> ${rel.tail.text} (${rel.tail.label})`);
}
}

Python​

from knowledgator import Knowledgator

kg = Knowledgator(api_key="YOUR_API_KEY")

result = kg.extract.it(
text="Steve Jobs founded Apple Inc. in Cupertino, California.",
tasks={
"entities": {
"type": "span",
"labels": ["person", "organization", "location"],
"threshold": 0.5,
},
"relations": {
"type": "relation",
"labels": ["founded", "located_in"],
"entity_labels": ["person", "organization", "location"],
"threshold": 0.5,
},
},
adapter_id="your-lora-adapter-id", # Optional LoRA adapter
)

for rel in result.outputs["relations"].value:
print(f"{rel.head.text} ({rel.head.label}) --[{rel.relation}]--> {rel.tail.text} ({rel.tail.label})")

Expected SDK Output​

Steve Jobs (person) --[founded]--> Apple Inc. (organization)
Apple Inc. (organization) --[located_in]--> California (location)
Cupertino (location) --[located_in]--> California (location)

Python (requests)​

import requests

url = "https://api.platform.knowledgator.com/inference/extract/"
headers = {
"Content-Type": "application/json",
"KnowledgatorAPI-Key": "YOUR_API_KEY",
"KnowledgatorAPI-Model-ID": "your-model-id" # Optional
}
payload = {
"input": "Steve Jobs founded Apple Inc. in Cupertino, California.",
"tasks": {
"entities": {
"type": "span",
"labels": ["person", "organization", "location"],
"threshold": 0.5,
"flat": False,
},
"relations": {
"type": "relation",
"labels": ["founded", "located_in"],
"flat": False,
"entity_labels": ["person", "organization", "location"],
"threshold": 0.5,
},
},
"options": {
"include_usage": True
}
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

cURL​

curl -X POST https://api.platform.knowledgator.com/inference/extract/ \
-H "Content-Type: application/json" \
-H "KnowledgatorAPI-Key: YOUR_API_KEY" \
-H "KnowledgatorAPI-Model-ID: your-model-id" \
-d '{
"input": "Steve Jobs founded Apple Inc. in Cupertino, California.",
"tasks": {
"entities": {
"type": "span",
"labels": ["person", "organization", "location"],
"threshold": 0.5,
"flat": false
},
"relations": {
"type": "relation",
"labels": ["founded", "located_in"],
"flat": false,
"entity_labels": ["person", "organization", "location"],
"threshold": 0.5
}
},
"options": {
"include_usage": true
}
}'

Additional Information​

  • Rule-based Filtering: Optional constraints on entity type pairs and distance
  • Use Cases:
    • Knowledge graph construction
    • Business intelligence
    • Scientific literature mining
    • Legal document analysis