openapi: 3.0.3
info:
contact:
email: api.inquiry@expert.ai
name: expert.ai
url: 'https://expert.ai/'
description: >
Natural Language API provides a comprehensive set of natural language
understanding capabilities based on expert.ai technology:
- Context based document analysis, comprising:
- Deep linguistic analysis, which, in turn, comprises:
- Text subdivision
- Part-of-speech tagging
- Morphological analysis
- Lemmatization
- Syntactic analysis
- Semantic analysis
- Keyphrase extraction
- Named entity recognition
- Relation extraction
- Sentiment analysis
- Taxonomy based document classification
- Information detection performed by detectors
title: expert.ai Natural Language API
version: v2
externalDocs:
description: API documentation
url: 'https://docs.expert.ai/nlapi/v2/'
servers:
- url: 'https://nlapi.expert.ai/v2'
tags:
- description: Document analysis API endpoints
name: Document analysis
- description: Document classification API endpoints
name: Document classification
- description: Information detection API endpoints
name: Information detection
paths:
/analyze/{context}/{language}:
post:
description: Full analysis (i.e., sum of all available partial analyses) of the posted text
parameters:
- description: Context name; use the `contexts` resource to discover available contexts
in: path
name: context
required: true
schema:
type: string
- description: Document language (code)
in: path
name: language
required: true
schema:
type: string
enum:
- de
- en
- es
- fr
- it
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnalysisRequest'
description: The document to be analyzed
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyzeResponse'
description: Resource response
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'413':
description: Request Entity Too Large
'500':
description: Internal Server Error
security:
- bearerAuth: []
summary: Full analysis
tags:
- Document analysis
/analyze/{context}/{language}/{analysis}:
post:
description: |
Specific analysis of the posted text.
Available analyses are:
- disambiguation: linguistic analysis (text subdivision, part-of-speech tagging, morphological analysis, lemmatization, syntactic analysis and semantic analysis)
- relevants: keyphrase extraction
- entities: named entity recognition
- relations: relation extraction
- sentiment: sentiment analysis
parameters:
- description: Context name; use the `contexts` resource to discover available contexts
in: path
name: context
required: true
schema:
type: string
- description: Document language (code)
in: path
name: language
required: true
schema:
type: string
enum:
- de
- en
- es
- fr
- it
- description: Analysis name; use the `contexts` resource to determine if the context provides that analysis for the chosen language
in: path
name: analysis
required: true
schema:
enum:
- disambiguation
- relevants
- entities
- sentiment
- relations
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnalysisRequest'
description: The document to be analyzed
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyzeResponse'
description: Resource response
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'413':
description: Request Entity Too Large
'500':
description: Internal Server Error
security:
- bearerAuth: []
summary: Specific partial analysis
tags:
- Document analysis
/categorize/{taxonomy}/{language}:
post:
description: Classification of the posted text
parameters:
- description: Taxonomy name; use the `taxonomies` resource to discover available taxonomies
in: path
name: taxonomy
required: true
schema:
type: string
- description: Document language (code); use the `taxonomies` resource to discover the languages for which the taxonomy is available
in: path
name: language
required: true
schema:
type: string
enum:
- de
- en
- es
- fr
- it
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnalysisRequest'
description: The document to be classified
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CategorizeResponse'
description: Resource response
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'413':
description: Request Entity Too Large
'500':
description: Internal Server Error
security:
- bearerAuth: []
summary: Classification
tags:
- Document classification
/contexts:
get:
description: Information about available contexts
responses:
'200':
$ref: '#/components/responses/200Contexts'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
security:
- bearerAuth: []
summary: Contexts information
tags:
- Document analysis
/taxonomies:
get:
description: Information about available taxonomies
responses:
'200':
$ref: '#/components/responses/200Taxonomies'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
security:
- bearerAuth: []
summary: Taxonomies information
tags:
- Document classification
/taxonomies/{taxonomy}/{language}:
get:
description: Detailed information about a taxonomy for a given language
parameters:
- description: Taxonomy name
in: path
name: taxonomy
required: true
schema:
type: string
- description: Taxonomy language (code); use the `taxonomies` resource to discover the languages that the taxonomy supports
in: path
name: language
required: true
schema:
type: string
enum:
- de
- en
- es
- fr
- it
responses:
'200':
$ref: '#/components/responses/200Taxonomy'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
security:
- bearerAuth: []
summary: Taxonomy tree
tags:
- Document classification
/detect/{detector}/{language}:
post:
description: Information detection on the posted text
parameters:
- description: Detector name; use the `detectors` resource to discover available detectors
in: path
name: detector
required: true
schema:
type: string
- description: Document language (code); use the `detectors` resource to discover the languages for which the detector is available
in: path
name: language
required: true
schema:
type: string
enum:
- de
- en
- es
- fr
- it
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnalysisRequest'
description: The document on which to perform information detection
responses:
'200':
description: Resource response
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'413':
description: Request Entity Too Large
'500':
description: Internal Server Error
security:
- bearerAuth: []
summary: Information detection
tags:
- Information detection
/detectors:
get:
description: Information about available detectors
responses:
'200':
$ref: '#/components/responses/200Detectors'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Server Error
security:
- bearerAuth: []
summary: Detectors information
tags:
- Information detection
components:
responses:
200Analyze:
description: Resource response
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyzeResponse'
200Contexts:
description: Resource response
content:
application/json:
schema:
$ref: '#/components/schemas/ContextsResponse'
200Categorize:
description: Resource response
content:
application/json:
schema:
$ref: '#/components/schemas/CategorizeResponse'
200Taxonomies:
description: Resource response
content:
application/json:
schema:
$ref: '#/components/schemas/TaxonomiesResponse'
200Taxonomy:
description: Resource response
content:
application/json:
schema:
$ref: '#/components/schemas/TaxonomyResponse'
200Detectors:
description: Resource response
content:
application/json:
schema:
$ref: '#/components/schemas/DetectorsResponse'
schemas:
DocumentPosition:
description: Position
properties:
start:
description: Zero-based position of the first character
format: int64
type: integer
end:
description: Zero-based position of the character after the last
format: int64
type: integer
VirtualSyncon:
description: A concept that does not exist in the Knowledge Graph but heuristics recognized as a type of a known parent concept.
properties:
id:
description: ID used to mark all the occurrences of the virtual concept in the text
format: int64
type: integer
parent:
description: >-
Parent concept; ID is used to look up Knowledge Graph data in the `knowledge`
array
format: int64
type: integer
Atom:
description: Atom info
properties:
start:
description: Zero-based position of the first character of the atom
format: int64
type: integer
end:
description: Zero-based position of the first character after the atom
format: int64
type: integer
type:
description: Expert.ai type
type: string
lemma:
description: Lemma
type: string
Dependency:
description: Dependency info
properties:
id:
description: Zero-based cardinal number of the token
format: int64
type: integer
head:
description: Number of the head token
format: int64
type: integer
label:
description: >-
(Dependency relation between the token and the
head token
type: string
Token:
description: Token info
properties:
start:
description: Zero-based position of the first character of the token
format: int64
type: integer
end:
description: Zero-based position of the first character after the token
format: int64
type: integer
type:
description: Expert.ai type
type: string
pos:
description: >-
Universal
Dependencies part-of-speech tag
type: string
lemma:
description: Lemma
type: string
syncon:
description: ID used to look up Knowledge Graph data in the `knowledge` array
format: int64
type: integer
vsyn:
$ref: '#/components/schemas/VirtualSyncon'
morphology:
description: >-
A semicolon separated list of CoNLL-U
format morphological features
type: string
dependency:
$ref: '#/components/schemas/Dependency'
atoms:
description: Atoms that make up the token
type: array
items:
$ref: '#/components/schemas/Atom'
paragraph:
description: Paragraph index in the `paragraphs` array
format: int64
type: integer
sentence:
description: Sentence index in the `sentences` array
format: int64
type: integer
phrase:
description: Phrase index in the `phrases` array
format: int64
type: integer
Phrase:
description: Phrase info
properties:
start:
description: Zero-based position of the first character of the phrase
format: int64
type: integer
end:
description: Zero-based position of the first character after the phrase
format: int64
type: integer
tokens:
description: >-
Indexes (in the `tokens` array) of the tokens that make up the
phrase
type: array
items:
description: Token index
format: int32
type: integer
uniqueItems: true
type:
description: Phrase type
type: string
Sentence:
description: Sentence info
properties:
start:
description: Zero-based position of the first character of the sentence
format: int64
type: integer
end:
description: Zero-based position of the first character after the sentence
format: int64
type: integer
phrases:
description: >-
Indexes (in the `phrases` array) of the phrases that make up the
sentence
type: array
items:
description: Phrase index
format: int32
type: integer
uniqueItems: true
Paragraph:
description: Paragraph info
properties:
start:
description: Zero-based position of the first character of the paragraph
format: int64
type: integer
end:
description: Zero-based position of the first character after the paragraph
format: int64
type: integer
sentences:
description: >-
Indexes (in the `sentences` array) of the sentences that make up the
paragraph
type: array
items:
description: Sentence index
format: int32
type: integer
uniqueItems: true
MainLemma:
description: Main lemma info
properties:
value:
description: Lemma
type: string
score:
description: Score assigned to the lemma to represent its relevance
format: float
type: number
positions:
description: Positions of lemma occurrences
type: array
items:
$ref: '#/components/schemas/DocumentPosition'
MainSyncon:
description: Main syncon info
properties:
syncon:
description: ID used to look up Knowledge Graph data in the `knowledge` array
format: int64
type: integer
lemma:
description: Lemma
type: string
score:
description: Score assigned to the syncon to represent its relevance
format: float
type: number
positions:
description: Positions of the expressions of the syncon
type: array
items:
$ref: '#/components/schemas/DocumentPosition'
MainPhrase:
description: Main phrase info
properties:
value:
description: Phrase text
type: string
score:
description: Score assigned to the phrase to represent its relevance
format: float
type: number
positions:
description: Positions of phrase occurrences
type: array
items:
$ref: '#/components/schemas/DocumentPosition'
MainSentence:
description: Main sentence
properties:
value:
description: Sentence text
type: string
score:
description: Score assigned to the sentence to represent its relevance
format: float
type: number
start:
description: Zero-based position of the first character of the sentence
format: int64
type: integer
end:
description: Zero-based position of the first character after the sentence
format: int64
type: integer
DocumentTopic:
description: Knowledge Graph topic info
properties:
id:
description: Language-independent topic ID
format: int64
type: integer
label:
description: Topic name
type: string
score:
description: Score assigned to the topic to represent its relevance
format: float
type: number
winner:
description: True if the topic is deemed particularly relevant
type: boolean
InferredAttribute:
description: Inferred attribute
properties:
attribute:
description: Attribute name
type: string
lemma:
description: Lemma
type: string
syncon:
description: ID used to look up Knowledge Graph data in the `knowledge` array
type: integer
format: int64
type:
description: Attribute type
type: string
attributes:
description: Attribute's attributes
type: array
items:
$ref: '#/components/schemas/InferredAttribute'
Entity:
description: Entity info
properties:
type:
description: Entity type
type: string
lemma:
description: Base form (lemma) of the entity name
type: string
syncon:
description: ID used to look up Knowledge Graph data in the `knowledge` array
format: int64
type: integer
positions:
description: Positions of the entity's mentions
type: array
items:
$ref: '#/components/schemas/DocumentPosition'
relevance:
description: Entity relevance
format: int64
type: integer
attributes:
description: Entity attributes inferred from the context or from the Knowledge Graph
type: array
items:
$ref: '#/components/schemas/InferredAttribute'
SentimentItem:
description: Item or chain of items expressing sentiment
properties:
lemma:
description: Lemma
type: string
syncon:
description: ID used to look up Knowledge Graph data in the `knowledge` array
format: int64
type: integer
sentiment:
description: Item/chain sentiment score
type: number
format: float
items:
description: Items expressing sentiment
type: array
items:
$ref: '#/components/schemas/SentimentItem'
RelationVerb:
description: Verb of a relation
properties:
text:
description: Verb text
type: string
lemma:
description: Lemma
type: string
syncon:
description: ID used to look up Knowledge Graph data in the `knowledge` array
format: int64
type: integer
type:
description: Type
type: string
phrase:
description: Phrase index in the `phrases` array
format: int64
type: integer
relevance:
description: Relevance
format: int64
type: integer
AnalysisRequest:
description: Request
properties:
document:
$ref: '#/components/schemas/Document'
Document:
description: Document
properties:
text:
description: The document's text
type: string
Property:
description: Syncon property
properties:
type:
description: Property type
type: string
value:
description: Property value
type: string
KnowledgeEntry:
description: Knowledge Graph data for a syncon
properties:
syncon:
description: Syncon ID
format: int64
type: integer
label:
description: Textual rendering of the general conceptual category for the token in the Knowledge Graph
type: string
properties:
description: Syncon extended properties
type: array
items:
$ref: '#/components/schemas/Property'
RelatedItem:
description: In a relation, a term that's directly or indirectly related to the verb
properties:
relation:
description: Verb-item relation
type: string
text:
description: Item text
type: string
lemma:
description: Lemma
type: string
syncon:
description: ID used to look up Knowledge Graph data in the `knowledge` array
format: int64
type: integer
vsyn:
$ref: '#/components/schemas/VirtualSyncon'
type:
description: Type
type: string
phrase:
description: Phrase index in the `phrases` array
format: int64
type: integer
relevance:
description: Relevance
format: int64
type: integer
related:
description: Related terms
type: array
items:
$ref: '#/components/schemas/RelatedItem'
Relation:
description: Verb-mediated relation
properties:
verb:
$ref: '#/components/schemas/RelationVerb'
related:
description: Related items
type: array
items:
$ref: '#/components/schemas/RelatedItem'
AnalyzeDocument:
description: Analysis data
properties:
version:
description: Service version
type: string
content:
description: Analyzed text
type: string
language:
description: Text language
type: string
paragraphs:
description: Paragraphs
type: array
items:
$ref: '#/components/schemas/Paragraph'
sentences:
description: Sentences
type: array
items:
$ref: '#/components/schemas/Sentence'
phrases:
description: Phrases
type: array
items:
$ref: '#/components/schemas/Phrase'
tokens:
description: Tokens
type: array
items:
$ref: '#/components/schemas/Token'
mainSentences:
description: Main sentences
type: array
items:
$ref: '#/components/schemas/MainSentence'
mainPhrases:
description: Main phrases
type: array
items:
$ref: '#/components/schemas/MainPhrase'
mainLemmas:
description: Main lemmas
type: array
items:
$ref: '#/components/schemas/MainLemma'
mainSyncons:
description: Main syncons
type: array
items:
$ref: '#/components/schemas/MainSyncon'
entities:
description: Entities
type: array
items:
$ref: '#/components/schemas/Entity'
topics:
description: Knowledge Graph topics
type: array
items:
$ref: '#/components/schemas/DocumentTopic'
knowledge:
description: Knowledge Graph syncons data
type: array
items:
$ref: '#/components/schemas/KnowledgeEntry'
sentiment:
description: Sentiment
properties:
overall:
description: Overall text sentiment score
type: number
format: float
negativity:
description: Text negativity
type: number
format: float
positivity:
description: Text positivity
type: number
format: float
items:
description: Items expressing sentiment
type: array
items:
$ref: '#/components/schemas/SentimentItem'
relations:
description: Verb-mediated relations
type: array
items:
$ref: '#/components/schemas/Relation'
ServiceError:
description: Error information
properties:
code:
description: Error code
type: string
message:
description: Error message
type: string
AnalyzeResponse:
description: Analysis resource response
properties:
success:
description: Operation completed successfully (true/false)
type: boolean
errors:
description: Service errors
type: array
items:
$ref: '#/components/schemas/ServiceError'
data:
$ref: '#/components/schemas/AnalyzeDocument'
CategorizeResponse:
description: Classification resource response
properties:
success:
description: Operation completed successfully (true/false)
type: boolean
errors:
description: Service errors
type: array
items:
$ref: '#/components/schemas/ServiceError'
data:
$ref: '#/components/schemas/CategorizeDocument'
CategorizeDocument:
description: Categorization data
properties:
version:
description: Service version
type: string
language:
description: Text language
type: string
categories:
description: Categories
type: array
items:
$ref: '#/components/schemas/Category'
Category:
description: Category
properties:
id:
description: Category ID
type: string
label:
description: Category label
type: string
hierarchy:
description: Hierarchical path
type: array
items:
type: string
score:
description: Score assigned to the category to represent its relevance
format: int32
type: integer
winner:
description: True if the category is deemed particularly relevant
type: boolean
namespace:
description: Name of the software package containing the reference taxonomy
type: string
frequency:
description: >-
Score expressed as a percentage of the sum of the scores of all the
candidate categories, winners and not (see the **score** property)
format: float
type: number
positions:
description: >-
Positions of the portions of text that contributed to the selection
of the category
type: array
items:
$ref: '#/components/schemas/DocumentPosition'
ContextLanguageInfo:
description: Information about a supported language and available analyses
properties:
code:
description: Language code
type: string
name:
description: Language name
type: string
analyses:
description: Available analyses
type: array
items:
type: string
ContextInfo:
description: Information about a context
properties:
name:
description: Context name
type: string
description:
description: Context description
type: string
languages:
description: Information about supported languages and available analyses
type: array
items:
$ref: '#/components/schemas/ContextLanguageInfo'
LanguageInfo:
description: Information about a supported language
properties:
code:
description: Language code
type: string
name:
description: Language name
type: string
TaxonomyInfo:
description: Summary information about a taxonomy
properties:
name:
description: Taxonomy name
type: string
description:
description: Taxonomy description
type: string
contract:
description: OpenAPI document describing extra ways to use the taxonomy and their outputs
type: string
languages:
description: Supported languages
type: array
items:
$ref: '#/components/schemas/LanguageInfo'
TaxonomyCategory:
description: Taxonomy category
properties:
id:
description: Category ID
type: string
label:
description: Category label
type: string
categories:
description: Sub-categories
type: array
items:
$ref: '#/components/schemas/TaxonomyCategory'
Taxonomy:
description: A taxonomy's categories tree
properties:
namespace:
description: Name of the software package containing the reference taxonomy
type: string
taxonomy:
description: Categories tree
type: array
items:
$ref: '#/components/schemas/TaxonomyCategory'
DetectorInfo:
description: Summary information about a detector
properties:
name:
description: Detector name
type: string
description:
description: Detector description
type: string
contract:
description: OpenAPI document describing the use of the detector and its output
type: string
languages:
description: Supported languages
type: array
items:
$ref: '#/components/schemas/LanguageInfo'
ContextsResponse:
description: Available contexts
properties:
contexts:
description: List of contexts' information
type: array
items:
$ref: '#/components/schemas/ContextInfo'
TaxonomiesResponse:
description: Available taxonomies
properties:
texonomies:
description: List of taxonomies' information
type: array
items:
$ref: '#/components/schemas/TaxonomyInfo'
TaxonomyResponse:
description: Taxonomy categories
properties:
success:
description: Operation completed successfully (true/false)
type: boolean
errors:
description: Service errors
type: array
items:
$ref: '#/components/schemas/ServiceError'
data:
type: array
items:
$ref: '#/components/schemas/Taxonomy'
DetectorsResponse:
description: Available detectors
properties:
detectors:
description: List of detectors' information
type: array
items:
$ref: '#/components/schemas/DetectorInfo'
securitySchemes:
bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http