openapi: 3.0.3
info:
  title: Kata.ai NL Prediction API
  description: >-
    The Kata.ai Natural Language (NL) Prediction API exposes a trained
    Natural Language Understanding model built in NL Studio so it can be
    called from any application. Given an input sentence it returns detected
    entities (trait, dict, phrase) with scores, spans, resolved values, and
    entity relationships. Reconstructed from the published Kata Platform
    documentation (kata-ai/kata-platform-docs, nl-studio/nl-prediction-api);
    an API Evangelist derived specification, not a Kata.ai-published OpenAPI.
  version: '1.0.0'
  contact:
    name: Kata.ai
    email: business@kata.ai
    url: https://docs.kata.ai/nl-studio/nl-prediction-api
  x-provenance:
    generated: '2026-07-19'
    method: generated
    source: https://github.com/kata-ai/kata-platform-docs/blob/master/docs/nl-studio/nl-prediction-api.md
servers:
  - url: https://geist.kata.ai
    description: Kata.ai NL Prediction API host
security:
  - bearerAuth: []
tags:
  - name: Prediction
    description: Run entity prediction against a deployed NLU model.
paths:
  /nlus/{nluId}/predict:
    post:
      tags: [Prediction]
      operationId: predict
      summary: Predict entities for a sentence
      description: >-
        Runs the deployed NLU model identified by nluId against the input
        text and returns detected entities grouped by entity name. Obtain the
        API token from NL Studio > Settings.
      parameters:
        - name: nluId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string, example: ada satu bebek dan lima kucing di sawah }
      responses:
        '200':
          description: Prediction result
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PredictionResult' }
              example:
                result:
                  ner:
                    - { type: phrase, score: 0.9999965645021311, value: sawah, label: LOCATION, start: 34, end: 39 }
                  animal:
                    - { type: dict, score: 0.7501584501364904, value: bebek, start: 9, end: 14, resolved: { dictKey: duck } }
        '403':
          description: You're not authorized to view this page.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token from NL Studio Settings (Authorization: Bearer <token>).'
  schemas:
    PredictionResult:
      type: object
      properties:
        result:
          type: object
          additionalProperties:
            type: array
            items: { $ref: '#/components/schemas/Entity' }
    Entity:
      type: object
      properties:
        type: { type: string, enum: [trait, dict, phrase] }
        start: { type: integer }
        end: { type: integer }
        score: { type: number }
        value: { type: string }
        label: { type: string }
        belongsTo:
          type: object
          properties:
            name: { type: string }
            index: { type: integer }
            score: { type: number }
        resolved: { type: object, additionalProperties: true }