Every API here is available over the APIs.io API and to AI agents over MCP.
{
"swagger": "2.0",
"info": {
"description": "Extracts entities (e.g., people, organizations, locations) and facts (e.g., educated at, founded by) about these entities from natural language text.\n",
"version": "1.0.0",
"title": "Natural Language API",
"termsOfService": "https://www.diffbot.com/terms/",
"contact": {
"email": "support@diffbot.com"
}
},
"host": "nl.diffbot.com",
"basePath": "/",
"schemes": [
"https"
],
"paths": {
"/v1/": {
"post": {
"tags": [
"Natural Language"
],
"summary": "Process Text",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "documents",
"description": "documents to be processed",
"required": true,
"schema": {
"$ref": "#/definitions/DocumentArray"
}
},
{
"name": "fields",
"in": "query",
"description": "Attributes to include in response",
"required": false,
"type": "array",
"items": {
"type": "string",
"enum": [
"entities",
"sentiment",
"facts",
"records",
"categories",
"sentences",
"language",
"summary"
]
},
"default": [
"entities",
"sentiment",
"facts",
"records",
"sentences"
],
"uniqueItems": true
}
],
"responses": {
"200": {
"description": "",
"schema": {
"$ref": "#/definitions/NaturalLanguageResponseArray"
}
},
"400": {
"description": "Invalid input",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
},
"security": [
{
"DiffbotToken": []
}
]
}
}
},
"securityDefinitions": {
"DiffbotToken": {
"type": "apiKey",
"name": "token",
"in": "query"
}
},
"definitions": {
"Document": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"format": "blob",
"description": "The text you'd like Diffbot Natural Language to process. \n",
"minLength": 1,
"maxLength": 100000
},
"lang": {
"type": "string",
"description": "Language of the text specified as an [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). Review our supported languages for more information.\n",
"default": "auto"
},
"format": {
"type": "string",
"description": "`plain text` for free text. `plain text with title` includes a title separated from the body by two line breaks (e.g. \"This is a title\\n\\nThis is the body\").\n",
"default": "plain text",
"enum": [
"plain text",
"plain text with title"
]
},
"documentType": {
"type": "string",
"description": "Optional. Provides context to the model and may produce better results.\n",
"enum": [
"organization bio",
"person bio",
"news article",
"address",
"discussion"
]
},
"customSummary": {
"$ref": "#/definitions/CustomSummary"
}
},
"example": {
"content": "Diffbot is a startup based in Menlo Park."
}
},
"DocumentArray": {
"type": "array",
"items": {
"$ref": "#/definitions/Document"
},
"example": [
{
"content": "Diffbot is a startup based in Menlo Park."
}
]
},
"EntityWithMentions": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"diffbotUri": {
"type": "string"
},
"confidence": {
"type": "number",
"format": "float"
},
"salience": {
"type": "number",
"format": "float"
},
"sentiment": {
"type": "number",
"format": "float"
},
"allUris": {
"type": "array",
"items": {
"type": "string"
}
},
"allTypes": {
"type": "array",
"items": {
"$ref": "#/definitions/EntityType"
}
},
"mentions": {
"type": "array",
"items": {
"$ref": "#/definitions/Mention"
}
},
"location": {
"$ref": "#/definitions/Location"
}
}
},
"Mention": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"beginOffset": {
"type": "integer"
},
"endOffset": {
"type": "integer"
},
"isPronoun": {
"type": "boolean"
},
"confidence": {
"type": "number",
"format": "float"
}
}
},
"Entity": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"diffbotUri": {
"type": "string"
},
"confidence": {
"type": "number",
"format": "float"
},
"allUris": {
"type": "array",
"items": {
"type": "string"
}
},
"allTypes": {
"type": "array",
"items": {
"$ref": "#/definitions/EntityType"
}
},
"isCustom": {
"type": "boolean"
},
"entityIndex": {
"type": "integer",
"description": "Index of this entity in the field \"entities\" (if requested)"
}
}
},
"Span": {
"type": "object",
"properties": {
"beginOffset": {
"type": "integer"
},
"endOffset": {
"type": "integer"
}
}
},
"Fact": {
"type": "object",
"properties": {
"humanReadable": {
"type": "string"
},
"entity": {
"$ref": "#/definitions/Entity"
},
"property": {
"$ref": "#/definitions/Property"
},
"value": {
"$ref": "#/definitions/Entity"
},
"qualifiers": {
"type": "array",
"items": {
"$ref": "#/definitions/Qualifier"
}
},
"confidence": {
"type": "number",
"format": "float"
},
"evidence": {
"type": "array",
"items": {
"$ref": "#/definitions/Evidence"
}
}
}
},
"Qualifier": {
"type": "object",
"properties": {
"property": {
"$ref": "#/definitions/Property"
},
"value": {
"$ref": "#/definitions/Qualifier_value"
},
"confidence": {
"type": "number",
"format": "float"
}
},
"description": "https://demo.nl.diffbot.com/schema/#qualifiers"
},
"Property": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"diffbotUri": {
"type": "string"
},
"description": {
"type": "string"
}
},
"description": "https://demo.nl.diffbot.com/schema/#properties"
},
"EntityType": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"diffbotUri": {
"type": "string"
},
"dbpediaUri": {
"type": "string"
}
},
"description": "https://demo.nl.diffbot.com/schema/#types"
},
"Evidence": {
"type": "object",
"properties": {
"passage": {
"type": "string",
"description": "One or more sentences where the fact was extracted from"
},
"entityMentions": {
"type": "array",
"items": {
"$ref": "#/definitions/Mention"
}
},
"valueMentions": {
"type": "array",
"items": {
"$ref": "#/definitions/Mention"
}
}
}
},
"Location": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"format": "float"
},
"longitude": {
"type": "number",
"format": "float"
},
"precision": {
"type": "number",
"format": "float"
}
}
},
"Category": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"confidence": {
"type": "number",
"format": "float"
},
"isPrimary": {
"type": "boolean"
}
}
},
"Categorization": {
"type": "object",
"properties": {
"iabv1": {
"type": "array",
"items": {
"$ref": "#/definitions/Category"
}
},
"iabv2": {
"type": "array",
"items": {
"$ref": "#/definitions/Category"
}
},
"diffbot": {
"type": "array",
"items": {
"$ref": "#/definitions/Category"
}
}
},
"description": "https://demo.nl.diffbot.com/schema/#categories"
},
"CustomSummary": {
"type": "object",
"properties": {
"maxNumberOfSentences": {
"type": "integer",
"format": "int32",
"description": "Maximum number of sentences for the generated summary.",
"minimum": 1,
"maximum": 10,
"default": 3
}
},
"description": "Define custom parameters for summary generation."
},
"NaturalLanguageResponse": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
}
},
"entities": {
"type": "array",
"items": {
"$ref": "#/definitions/EntityWithMentions"
}
},
"sentiment": {
"type": "number",
"format": "float"
},
"facts": {
"type": "array",
"items": {
"$ref": "#/definitions/Fact"
}
},
"records": {
"type": "array",
"description": "Array of entities with attributes extracted from inputDocument according to the KG schema (https://docs.diffbot.com/docs/ontology)",
"items": {
"type": "object",
"properties": {}
}
},
"categories": {
"$ref": "#/definitions/Categorization"
},
"sentences": {
"type": "array",
"items": {
"$ref": "#/definitions/Span"
}
},
"language": {
"type": "string",
"description": "Language of the text specified as an [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)."
},
"summary": {
"type": "string",
"description": "Generated summary."
}
}
},
"NaturalLanguageResponseArray": {
"type": "array",
"items": {
"$ref": "#/definitions/NaturalLanguageResponse"
},
"example": [
{
"sentiment": 0.0,
"entities": [
{
"name": "Diffbot",
"diffbotUri": "https://diffbot.com/entity/EYX1i02YVPsuT7fPLUYgRhQ",
"confidence": 0.99898225,
"salience": 0.95394653,
"sentiment": 0.0,
"isCustom": false,
"allUris": [
"http://www.wikidata.org/entity/Q17052069"
],
"allTypes": [
{
"name": "organization",
"diffbotUri": "https://diffbot.com/entity/EN1ClYEdMMQCxB6AWTkT3mA",
"dbpediaUri": "http://dbpedia.org/ontology/Organisation"
}
],
"mentions": [
{
"text": "Diffbot",
"beginOffset": 0,
"endOffset": 7,
"confidence": 0.99898225
}
],
"location": {
"latitude": 37.456104,
"longitude": -122.1763,
"precision": 0.1
}
},
{
"name": "Menlo Park",
"diffbotUri": "https://diffbot.com/entity/EQiAUr370NpW1gvx-V4fTrQ",
"confidence": 0.9996269,
"salience": 0.9082091,
"sentiment": 0.0,
"isCustom": false,
"allUris": [
"http://www.wikidata.org/entity/Q74195"
],
"allTypes": [
{
"name": "location",
"diffbotUri": "https://diffbot.com/entity/EiCyWUm4lNziqgLHx47iAIQ",
"dbpediaUri": "http://dbpedia.org/ontology/Place"
},
{
"name": "administrative area",
"diffbotUri": "https://diffbot.com/entity/EcTIu1tWKPouIa6qZtSpc4A",
"dbpediaUri": "http://dbpedia.org/ontology/PopulatedPlace"
},
{
"name": "city",
"diffbotUri": "https://diffbot.com/entity/EzdJrGHiyMWu0XbSn101rFA",
"dbpediaUri": "http://dbpedia.org/ontology/City"
}
],
"mentions": [
{
"text": "Menlo Park",
"beginOffset": 30,
"endOffset": 40,
"confidence": 0.9996269
}
],
"location": {
"latitude": 37.454166,
"longitude": -122.17861,
"precision": 6.708204
}
},
{
"name": "startup company",
"diffbotUri": "https://diffbot.com/entity/EfX0EeXroOmaXrLe-SylIuw",
"confidence": 0.81958973,
"salience": 0.6474858,
"sentiment": 0.0,
"isCustom": false,
"allUris": [],
"mentions": [
{
"text": "startup",
"beginOffset": 13,
"endOffset": 20,
"confidence": 0.81958973
}
]
}
],
"facts": [
{
"humanReadable": "[Diffbot] headquarters [Menlo Park]",
"entity": {
"name": "Diffbot",
"diffbotUri": "https://diffbot.com/entity/EYX1i02YVPsuT7fPLUYgRhQ",
"confidence": 0.99898225,
"allUris": [
"http://www.wikidata.org/entity/Q17052069"
],
"allTypes": [
{
"name": "organization",
"diffbotUri": "https://diffbot.com/entity/EN1ClYEdMMQCxB6AWTkT3mA",
"dbpediaUri": "http://dbpedia.org/ontology/Organisation"
}
],
"isCustom": false,
"entityIndex": 1
},
"property": {
"name": "headquarters",
"diffbotUri": "https://docs.diffbot.com/docs/ont-organization#location"
},
"value": {
"name": "Menlo Park",
"diffbotUri": "https://diffbot.com/entity/EQiAUr370NpW1gvx-V4fTrQ",
"confidence": 0.9996269,
"allUris": [
"http://www.wikidata.org/entity/Q74195"
],
"allTypes": [
{
"name": "location",
"diffbotUri": "https://diffbot.com/entity/EiCyWUm4lNziqgLHx47iAIQ",
"dbpediaUri": "http://dbpedia.org/ontology/Place"
},
{
"name": "administrative area",
"diffbotUri": "https://diffbot.com/entity/EcTIu1tWKPouIa6qZtSpc4A",
"dbpediaUri": "http://dbpedia.org/ontology/PopulatedPlace"
},
{
"name": "city",
"diffbotUri": "https://diffbot.com/entity/EzdJrGHiyMWu0XbSn101rFA",
"dbpediaUri": "http://dbpedia.org/ontology/City"
}
],
"isCustom": false,
"entityIndex": 0
},
"qualifiers": [
{
"property": {
"name": "is current"
},
"value": {
"name": "true"
},
"confidence": 0
}
],
"confidence": 0.95,
"evidence": [
{
"passage": "Diffbot is a startup based in Menlo Park.",
"entityMentions": [
{
"text": "Diffbot",
"beginOffset": 0,
"endOffset": 7,
"confidence": 0.99898225
}
],
"valueMentions": [
{
"text": "Menlo Park",
"beginOffset": 30,
"endOffset": 40,
"confidence": 0.9996269
}
]
}
]
}
]
}
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"Qualifier_value": {
"properties": {
"name": {
"type": "string"
},
"diffbotUri": {
"type": "string"
}
}
}
}
}