Lang.ai Documents API

openapi: 3.0.3
info:
  title: Lang.ai Documents API
  version: '1.0'
  description: 'The Lang.ai API is organized around REST, with predictable resource-oriented URLs, HTTP verbs and HTTP response codes. JSON is returned by all API responses, including errors. The API builds and applies custom text classifiers: create a project from a dataset of customer interactions, let the algorithm extract intents and features that are grouped into tags, then analyze and save new documents (support tickets, chatbot messages) against that project in real time. Generated by the API Evangelist enrichment pipeline from the published API reference at https://docs.lang.ai/ — Lang.ai does not publish a machine-readable specification.'
  contact:
    name: Lang.ai Help Center
    url: https://help.lang.ai/
  x-generated-by: api-evangelist-enrichment-pipeline
  x-generated-from: https://docs.lang.ai/
  x-method: generated
servers:
- url: https://{company}.lang.ai/api/v1
  description: Per-tenant Lang.ai instance. Replace the company variable with the subdomain of the Lang.ai instance you are using.
  variables:
    company:
      default: company
      description: The subdomain of your Lang.ai instance.
security:
- bearerAuth: []
tags:
- name: Documents
  description: Analyze and save documents against a project.
paths:
  /analyze:
    post:
      operationId: analyzeDocument
      tags:
      - Documents
      summary: Analyze a document
      description: Returns the classification for a given document and the specified project. The document is not persisted; use the save documents operation to store it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeRequest'
            example:
              text: The text to be analyzed
              projectId: Your project id
      responses:
        '200':
          description: The tags and intents matched for the document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Classification'
              example:
                tags:
                - id: tqGMbCpTBZOJaram
                  name: My first tag
                intents:
                - name: intent
                  features:
                  - feature
                  - feature>feature
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /documents:
    post:
      operationId: saveDocument
      tags:
      - Documents
      summary: Save a document
      description: Saves a given document into the specified project and returns its classification. Supports passing metadata that can later be used in the project dashboard; new metadata values passed via the API become available in the project setup section. Supplying an id that already exists overwrites the stored document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveDocumentRequest'
            example:
              text: The text to be analyzed
              projectId: Your project id
              metadata:
                key: value
                another_key: value
              date: '2019-20-12'
              id: The ID of the document to save.
      responses:
        '200':
          description: The tags and intents matched for the saved document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Classification'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Classification:
      type: object
      properties:
        tags:
          type: array
          description: An array of tags.
          items:
            $ref: '#/components/schemas/TagRef'
        intents:
          type: array
          description: An array of intents.
          items:
            $ref: '#/components/schemas/Intent'
    SaveDocumentRequest:
      type: object
      required:
      - text
      - projectId
      properties:
        text:
          type: string
          description: The text to be classified.
        projectId:
          type: string
          description: The project to be used to classify the text.
        metadata:
          type: object
          description: The metadata information of the document.
          additionalProperties: true
        date:
          type: string
          description: The date of the document. Supports valid ISO 8601 dates. If not passed, the request time is used.
        id:
          type: string
          description: ID of the document to save. If a document with the same ID already exists, it will be overwritten.
    Intent:
      type: object
      properties:
        name:
          type: string
          description: The name of the intent.
        features:
          type: array
          description: An array of features. The sign ">" indicates a second-level feature.
          items:
            type: string
    TagRef:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tag.
        name:
          type: string
          description: The name of the tag.
    AnalyzeRequest:
      type: object
      required:
      - text
      - projectId
      properties:
        text:
          type: string
          description: The text to be classified.
        projectId:
          type: string
          description: The project to be used to classify the text.
    Error:
      type: object
      description: JSON is returned by all API responses, including errors. Lang.ai documents the HTTP status codes but does not publish a field-level error envelope schema.
      additionalProperties: true
  responses:
    NotFound:
      description: Project not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too many requests / Rate limited
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request / Missing fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authenticate your account by including your secret API token in every request as an Authorization: Bearer header. Create a new API token from the Settings section of your Lang.ai instance. Generating a new token invalidates previously issued ones.'