openapi: 3.1.0
info:
  title: Salesforce Einstein Language API
  description: >-
    Natural language processing API for sentiment analysis, intent detection,
    and text classification. Einstein Language allows you to create custom
    text classification models and use pre-built models for sentiment and
    intent analysis.
  version: 2.0.0
  contact:
    name: Salesforce Developer Support
    url: https://developer.salesforce.com/
  license:
    name: Salesforce Master Subscription Agreement
    url: https://www.salesforce.com/company/legal/agreements/
  termsOfService: https://www.salesforce.com/company/legal/agreements/
servers:
  - url: https://api.einstein.ai/v2/language
    description: Einstein Language Production Server
security:
  - bearerAuth: []
tags:
  - name: API Usage
    description: Monitor API usage and limits
  - name: Datasets
    description: Manage text datasets for training models
  - name: Examples
    description: Manage training examples within datasets
  - name: Models
    description: Train and manage text classification models
  - name: Predictions
    description: Analyze text using trained or pre-built models
paths:
  /datasets:
    get:
      operationId: listDatasets
      summary: Salesforce Einstein List datasets
      description: Returns a list of all language datasets associated with the account.
      tags:
        - Datasets
      parameters:
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: count
          in: query
          schema:
            type: integer
            default: 25
            maximum: 100
      responses:
        '200':
          description: Successful response with list of datasets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDataset
      summary: Salesforce Einstein Create a dataset
      description: Creates a new text classification dataset.
      tags:
        - Datasets
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the dataset.
                type:
                  type: string
                  enum:
                    - text-sentiment
                    - text-intent
                  description: Type of the dataset.
                path:
                  type: string
                  description: URL of the .csv file containing training data.
              required:
                - name
                - type
      responses:
        '200':
          description: Dataset created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /datasets/{datasetId}:
    get:
      operationId: getDataset
      summary: Salesforce Einstein Get a dataset
      description: Returns details of a specific language dataset.
      tags:
        - Datasets
      parameters:
        - $ref: '#/components/parameters/DatasetId'
      responses:
        '200':
          description: Successful response with dataset details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDataset
      summary: Salesforce Einstein Delete a dataset
      description: Deletes a dataset and all associated examples and models.
      tags:
        - Datasets
      parameters:
        - $ref: '#/components/parameters/DatasetId'
      responses:
        '200':
          description: Dataset deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /datasets/{datasetId}/examples:
    get:
      operationId: listExamples
      summary: Salesforce Einstein List examples in a dataset
      description: Returns a list of text examples in the specified dataset.
      tags:
        - Examples
      parameters:
        - $ref: '#/components/parameters/DatasetId'
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: count
          in: query
          schema:
            type: integer
            default: 25
            maximum: 100
        - name: source
          in: query
          schema:
            type: string
            enum:
              - all
              - upload
              - feedback
      responses:
        '200':
          description: Successful response with examples list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExampleList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: addExample
      summary: Salesforce Einstein Add an example to a dataset
      description: Adds a labeled text example to an existing dataset.
      tags:
        - Examples
      parameters:
        - $ref: '#/components/parameters/DatasetId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the example.
                labelId:
                  type: integer
                  description: ID of the label to assign.
                document:
                  type: string
                  description: Text content of the example.
              required:
                - name
                - labelId
                - document
      responses:
        '200':
          description: Example added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Example'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /datasets/{datasetId}/models:
    get:
      operationId: listModelsForDataset
      summary: Salesforce Einstein List models for a dataset
      description: Returns all models trained on the specified dataset.
      tags:
        - Models
      parameters:
        - $ref: '#/components/parameters/DatasetId'
      responses:
        '200':
          description: Successful response with models list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Model'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /train:
    post:
      operationId: trainModel
      summary: Salesforce Einstein Train a model
      description: >-
        Trains a text classification model on a dataset. Training is
        asynchronous.
      tags:
        - Models
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name for the trained model.
                datasetId:
                  type: integer
                  description: ID of the dataset to train on.
                trainParams:
                  type: string
                  description: JSON string of optional training parameters.
                epochs:
                  type: integer
                  description: Number of training epochs.
                learningRate:
                  type: number
                  description: Learning rate for training.
              required:
                - name
                - datasetId
      responses:
        '200':
          description: Training job started successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /retrain:
    post:
      operationId: retrainModel
      summary: Salesforce Einstein Retrain a model
      description: Retrains an existing model with additional data.
      tags:
        - Models
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                modelId:
                  type: string
                  description: ID of the model to retrain.
                epochs:
                  type: integer
                learningRate:
                  type: number
              required:
                - modelId
      responses:
        '200':
          description: Retraining job started successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /models/{modelId}:
    get:
      operationId: getModel
      summary: Salesforce Einstein Get model details
      description: Returns the details and metrics of a trained model.
      tags:
        - Models
      parameters:
        - $ref: '#/components/parameters/ModelId'
      responses:
        '200':
          description: Successful response with model details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteModel
      summary: Salesforce Einstein Delete a model
      description: Deletes a trained model.
      tags:
        - Models
      parameters:
        - $ref: '#/components/parameters/ModelId'
      responses:
        '200':
          description: Model deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /sentiment:
    post:
      operationId: analyzeSentiment
      summary: Salesforce Einstein Analyze sentiment
      description: >-
        Analyzes the sentiment of the given text. Use the pre-built
        CommunitySentiment model or a custom-trained sentiment model.
      tags:
        - Predictions
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                modelId:
                  type: string
                  description: >-
                    ID of the model to use. Use 'CommunitySentiment' for the
                    pre-built model.
                document:
                  type: string
                  description: Text to analyze.
                numResults:
                  type: integer
                  description: Maximum number of results to return.
                  default: 3
              required:
                - modelId
                - document
      responses:
        '200':
          description: Successful sentiment analysis response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /intent:
    post:
      operationId: detectIntent
      summary: Salesforce Einstein Detect intent
      description: >-
        Detects the intent of the given text. Requires a custom-trained
        intent model.
      tags:
        - Predictions
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                modelId:
                  type: string
                  description: ID of the custom intent model to use.
                document:
                  type: string
                  description: Text to classify.
                numResults:
                  type: integer
                  description: Maximum number of results to return.
                  default: 3
              required:
                - modelId
                - document
      responses:
        '200':
          description: Successful intent detection response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apiusage:
    get:
      operationId: getApiUsage
      summary: Salesforce Einstein Get API usage
      description: Returns API usage data for the account.
      tags:
        - API Usage
      responses:
        '200':
          description: Successful response with usage data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUsageList'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 Bearer token. Generate a token using your Einstein Platform
        Services private key.
  parameters:
    DatasetId:
      name: datasetId
      in: path
      required: true
      description: Unique identifier for the dataset.
      schema:
        type: integer
    ModelId:
      name: modelId
      in: path
      required: true
      description: Unique identifier for the model.
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad request. Invalid parameters or missing required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized. Invalid or missing bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Dataset:
      type: object
      properties:
        id:
          type: integer
          description: Unique dataset identifier.
        name:
          type: string
          description: Name of the dataset.
        type:
          type: string
          enum:
            - text-sentiment
            - text-intent
          description: Type of the dataset.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        labelSummary:
          $ref: '#/components/schemas/LabelSummary'
        totalExamples:
          type: integer
        totalLabels:
          type: integer
        available:
          type: boolean
        statusMsg:
          type: string
        object:
          type: string
    DatasetList:
      type: object
      properties:
        object:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/Dataset'
    LabelSummary:
      type: object
      properties:
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
    Label:
      type: object
      properties:
        id:
          type: integer
        datasetId:
          type: integer
        name:
          type: string
        numExamples:
          type: integer
    Example:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        label:
          $ref: '#/components/schemas/Label'
        createdAt:
          type: string
          format: date-time
        object:
          type: string
    ExampleList:
      type: object
      properties:
        object:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/Example'
    Model:
      type: object
      properties:
        modelId:
          type: string
        name:
          type: string
        datasetId:
          type: integer
        datasetVersionId:
          type: integer
        status:
          type: string
          enum:
            - QUEUED
            - RUNNING
            - SUCCEEDED
            - FAILED
            - DELETED
        progress:
          type: number
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        learningRate:
          type: number
        epochs:
          type: integer
        object:
          type: string
        modelType:
          type: string
        failureMsg:
          type: string
    TrainResponse:
      type: object
      properties:
        modelId:
          type: string
        datasetId:
          type: integer
        datasetVersionId:
          type: integer
        name:
          type: string
        status:
          type: string
        progress:
          type: number
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        epochs:
          type: integer
        learningRate:
          type: number
        object:
          type: string
    PredictionResponse:
      type: object
      properties:
        probabilities:
          type: array
          items:
            $ref: '#/components/schemas/Probability'
        object:
          type: string
    Probability:
      type: object
      properties:
        label:
          type: string
          description: Predicted label.
        probability:
          type: number
          description: Confidence score (0.0 to 1.0).
    ApiUsageList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApiUsage'
        object:
          type: string
    ApiUsage:
      type: object
      properties:
        id:
          type: string
        startsAt:
          type: string
          format: date-time
        endsAt:
          type: string
          format: date-time
        plan:
          type: object
          properties:
            planId:
              type: string
            source:
              type: string
        predictionsUsed:
          type: integer
        predictionsMax:
          type: integer
        object:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        errorCode:
          type: string
          description: Machine-readable error code.