Lang.ai
Lang.ai API

REST API for building and applying custom text classifiers. Create a project from a dataset of customer interactions, list projects and their tags, analyze a document to receive its matched tags and intents, and save documents with metadata into a project for dashboard reporting. Authenticated with a bearer API token issued from the Settings section of your Lang.ai instance.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.3
info:
  title: Lang.ai 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: Projects
    description: Create and inspect classification projects and their tags.
  - name: Documents
    description: Analyze and save documents against a project.
paths:
  /project:
    post:
      operationId: createProject
      tags:
        - Projects
      summary: Create a project
      description: >-
        Create a project by performing a single multipart/related request (RFC 2387)
        containing both the project metadata and the contents of a dataset. The metadata
        part must come first with Content-Type application/json; charset=UTF-8, and the
        media part second with Content-Type text/plain or text/csv.
      requestBody:
        required: true
        content:
          multipart/related:
            schema:
              type: object
              required:
                - metadata
                - media
              properties:
                metadata:
                  $ref: '#/components/schemas/ProjectMetadata'
                media:
                  type: string
                  format: binary
                  description: >-
                    The data from the file to be uploaded. Extra CSV columns may be
                    included to be used as metadata.
      responses:
        '200':
          description: The id of the project that is being created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCreated'
              example:
                id: project_id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /projects:
    get:
      operationId: listProjects
      tags:
        - Projects
      summary: List projects
      description: Returns the list of projects. The request does not require a JSON body.
      responses:
        '200':
          description: A list of zero, one or more projects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
              example:
                - status: Processing
                  id: sWP2ll1v16lLdMxM
                  name: My first project
                  createdAt: '2021-03-22T13:54:55Z'
                - status: Completed
                  id: l3wNMwIXM1S046Sy
                  name: My second project
                  createdAt: '2021-03-23T13:54:55Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /projects/{projectId}:
    get:
      operationId: getProjectTags
      tags:
        - Projects
      summary: List project tags
      description: >-
        Returns the project information as well as the list of zero, one or more tags
        defined on the project. The request does not require a JSON body.
      parameters:
        - name: projectId
          in: path
          required: true
          description: The ID of the project.
          schema:
            type: string
          example: l3wNMwIXM1S046Sy
      responses:
        '200':
          description: The project and its tags.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectWithTags'
              example:
                status: Completed
                id: l3wNMwIXM1S046Sy
                name: My second project
                createdAt: '2021-03-23T13:54:55Z'
                tags:
                  - id: tqGMbCpTBZOJaram
                    name: My first tag
                    createdAt: '2021-04-21T12:40:50.892265Z'
                    updatedAt: '2021-04-25T11:35:43.512464Z'
                    isDraft: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /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:
  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.
  responses:
    BadRequest:
      description: Bad request / Missing fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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
    ProjectMetadata:
      type: object
      required:
        - name
        - csvOptions
        - team_ids
      properties:
        name:
          type: string
          description: The name of the project.
        csvOptions:
          type: object
          required:
            - textColumn
          properties:
            textColumn:
              type: string
              description: >-
                The name of the column from the CSV file containing each document's text.
            dateColumn:
              type: string
              description: >-
                Optional. The name of the column from the CSV file that contains the
                document's date.
        team_ids:
          type: array
          description: The list of team ids that will have access to the project.
          items:
            type: string
    ProjectCreated:
      type: object
      properties:
        id:
          type: string
          description: The id of the project.
    Project:
      type: object
      properties:
        status:
          type: string
          description: 'The project status: Errored, Processing, Completed.'
          enum:
            - Errored
            - Processing
            - Completed
        id:
          type: string
          description: The ID of the project.
        name:
          type: string
          description: The name of the project.
        createdAt:
          type: string
          description: The creation date of the project.
    ProjectWithTags:
      allOf:
        - $ref: '#/components/schemas/Project'
        - type: object
          properties:
            tags:
              type: array
              description: An array of tags.
              items:
                $ref: '#/components/schemas/Tag'
    Tag:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tag.
        name:
          type: string
          description: The name of the tag.
        createdAt:
          type: string
          description: The creation date of the tag.
        updatedAt:
          type: string
          description: The last update date of the tag.
        isDraft:
          type: boolean
          description: Whether or not the tag is draft.
    TagRef:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tag.
        name:
          type: string
          description: The name of the tag.
    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
    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'
    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.
    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.
Lang.ai API

Documentation

Specifications

Other Resources

OpenAPI Specification
