API Reference

Complete reference for all Entity Detector API endpoints.

Base URL

https://api.entitydetector.com/v1

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

POST /v1/analyze

Analyze text to extract entities, relations, and sentiment.

Request Body

json

{
  "text": "Article text to analyze (200-30000 characters)",
  "options": {
    "languageHint": "en",
    "maxEntitiesPerType": 50,
    "includeEvidence": true
  }
}

Parameters

Parameter	Type	Required	Description
text	string	Yes	Text to analyze (200-30,000 characters)
options.languageHint	string	No	ISO 639-1 language code (e.g., "en", "es", "de")
options.maxEntitiesPerType	number	No	Maximum entities per type (default: 50, max: 100)
options.includeEvidence	boolean	No	Include text evidence for relations (default: true)

Response

json

{
  "entities": {
    "persons": ["John Smith", "Jane Doe"],
    "organizations": ["Acme Corp", "TechStartup Inc"],
    "locations": ["New York", "San Francisco"],
    "objects": ["laptop", "contract"]
  },
  "relations": [
    {
      "source": "John Smith",
      "target": "Acme Corp",
      "type": "works_for",
      "evidence": "John Smith, CEO of Acme Corp",
      "sentiment": "neutral",
      "confidence": 0.95
    }
  ],
  "meta": {
    "model": "qwen2.5:1.5b-instruct",
    "language": "en",
    "processingMs": 1523,
    "cached": false
  }
}

Response Fields

Field	Type	Description
entities.persons	string[]	People mentioned in the text
entities.organizations	string[]	Companies, institutions, groups
entities.locations	string[]	Places, cities, countries, addresses
entities.objects	string[]	Physical or conceptual objects
relations[].source	string	Source entity in the relation
relations[].target	string	Target entity in the relation
relations[].type	string	Relation type (e.g., "works_for", "located_in")
relations[].evidence	string	Text excerpt supporting the relation
relations[].sentiment	string	"positive", "negative", or "neutral"
relations[].confidence	number	Confidence score (0.0 - 1.0)
meta.model	string	AI model used for analysis
meta.language	string	Detected language code
meta.processingMs	number	Processing time in milliseconds
meta.cached	boolean	Whether result was served from cache

GET /v1/quota

Check your current API usage quota.

Response

json

{
  "plan": "free",
  "daily": {
    "limit": 100,
    "used": 23,
    "remaining": 77
  },
  "resetAt": "2024-01-16T00:00:00Z"
}

Response Fields

Field	Description
plan	Your current plan (free, starter, pro, business)
daily.limit	Maximum daily requests allowed
daily.used	Requests used today
daily.remaining	Requests remaining today
resetAt	ISO 8601 timestamp when quota resets

HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing token
429	Rate Limited - Quota exceeded
500	Server Error - Something went wrong