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: 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: 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