Relation Extraction
Extract relationships between entities in text.
Endpoint
POST https://api.platform.knowledgator.com/inference/extract/
Headers
| Name | Type | Description |
|---|---|---|
KnowledgatorAPI-Key | String | Your API key (required). |
Content-Type | String | application/json |
KnowledgatorAPI-Model-ID | String | Optional 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 confidencethreshold.relations: Relation extraction task defining candidate relation labels (labels), allowed entity types (entity_labels), and confidencethreshold.
options(object, optional): Inference options such asinclude_usageoradapter_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 namerelations: Relation extraction task resultvalue: Array of extracted relation objectshead: Head entity object (label,text,start,end,source)relation: Predicted relationship typetail: Tail entity object (label,text,start,end,source)score: Model confidence score for this relation
Error Codes
| Status Code | Description |
|---|---|
| 200 | OK – Request successful. |
| 400 | Bad Request – Invalid or incomplete input. |
| 401 | Unauthorized – Invalid API key. |
| 404 | Not Found – Invalid endpoint. |
| 413 | Payload Too Large – Exceeds size limit. |
| 500 | Internal 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