dataiku-api-node-admin-openapi.yml

openapi: 3.1.0
info:
  title: Dataiku API Node Administration API
  description: >-
    REST API for administering Dataiku API Nodes, managing deployed services,
    service generations, prediction endpoints, and authentication keys for
    real-time API serving of machine learning models and data lookups.
  version: '13.0'
  contact:
    name: Dataiku Support
    url: https://www.dataiku.com/support
    email: support@dataiku.com
  termsOfService: https://www.dataiku.com/terms/
externalDocs:
  description: Dataiku API Node Administration Documentation
  url: https://doc.dataiku.com/dss/latest/apinode/api/admin-api.html
servers:
  - url: https://{apinode-host}:{port}/admin/api
    description: Dataiku API Node Instance
    variables:
      apinode-host:
        default: apinode.example.com
        description: Hostname of the Dataiku API Node
      port:
        default: '12443'
        description: Admin API port
tags:
  - name: Authentication
    description: Manage API keys for service access
  - name: Generations
    description: Manage service generations (versions)
  - name: Metrics
    description: Retrieve metrics and health information
security:
  - apiKeyAuth: []
paths:
  /services:
    get:
      operationId: listServices
      summary: Dataiku List deployed services
      description: >-
        List all services currently deployed on this API node.
      tags: []
      responses:
        '200':
          description: List of deployed services
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceSummary'
        '401':
          description: Unauthorized
  /services/{serviceId}:
    get:
      operationId: getService
      summary: Dataiku Get service details
      description: >-
        Retrieve the details and configuration of a deployed service.
      tags: []
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: Service details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          description: Unauthorized
        '404':
          description: Service not found
    delete:
      operationId: deleteService
      summary: Dataiku Delete a service
      description: >-
        Remove a deployed service and all its generations from the API node.
      tags: []
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '204':
          description: Service deleted
        '401':
          description: Unauthorized
        '404':
          description: Service not found
  /services/{serviceId}/enable:
    post:
      operationId: enableService
      summary: Dataiku Enable a service
      description: Enable a deployed service to accept prediction requests.
      tags: []
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: Service enabled
        '404':
          description: Service not found
  /services/{serviceId}/disable:
    post:
      operationId: disableService
      summary: Dataiku Disable a service
      description: Disable a service to stop accepting prediction requests.
      tags: []
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: Service disabled
        '404':
          description: Service not found
  /services/{serviceId}/generations:
    get:
      operationId: listGenerations
      summary: Dataiku List generations
      description: >-
        List all generations (deployed versions) of a service.
      tags:
        - Generations
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: List of generations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GenerationSummary'
        '404':
          description: Service not found
    post:
      operationId: importGeneration
      summary: Dataiku Import a generation
      description: >-
        Import a new generation (bundle) for a service from a ZIP archive.
      tags:
        - Generations
      parameters:
        - $ref: '#/components/parameters/serviceId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: ZIP archive containing the generation bundle
      responses:
        '200':
          description: Generation imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationSummary'
        '400':
          description: Invalid bundle
        '404':
          description: Service not found
  /services/{serviceId}/generations/{generationId}:
    get:
      operationId: getGeneration
      summary: Dataiku Get generation details
      description: >-
        Get the details of a specific generation.
      tags:
        - Generations
      parameters:
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/generationId'
      responses:
        '200':
          description: Generation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generation'
        '404':
          description: Generation not found
    delete:
      operationId: deleteGeneration
      summary: Dataiku Delete a generation
      description: >-
        Delete a specific generation from a service.
      tags:
        - Generations
      parameters:
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/generationId'
      responses:
        '204':
          description: Generation deleted
        '404':
          description: Generation not found
  /services/{serviceId}/generations/{generationId}/preload:
    post:
      operationId: preloadGeneration
      summary: Dataiku Preload a generation
      description: >-
        Preload a generation into memory to reduce cold-start latency.
      tags:
        - Generations
      parameters:
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/generationId'
      responses:
        '200':
          description: Generation preloaded
        '404':
          description: Generation not found
  /services/{serviceId}/generations/{generationId}/switch:
    post:
      operationId: switchGeneration
      summary: Dataiku Switch to a generation
      description: >-
        Set a generation as the active generation for the service.
      tags:
        - Generations
      parameters:
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/generationId'
      responses:
        '200':
          description: Generation switched
        '404':
          description: Generation not found
  /auth/keys:
    get:
      operationId: listAuthKeys
      summary: Dataiku List authentication keys
      description: >-
        List all API authentication keys configured for accessing services.
      tags:
        - Authentication
      responses:
        '200':
          description: List of authentication keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthKey'
        '401':
          description: Unauthorized
    post:
      operationId: createAuthKey
      summary: Dataiku Create an authentication key
      description: >-
        Create a new authentication key for accessing API node services.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuthKeyRequest'
      responses:
        '200':
          description: Authentication key created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthKey'
        '400':
          description: Invalid request
  /auth/keys/{keyId}:
    get:
      operationId: getAuthKey
      summary: Dataiku Get authentication key details
      description: >-
        Retrieve details of a specific authentication key.
      tags:
        - Authentication
      parameters:
        - $ref: '#/components/parameters/keyId'
      responses:
        '200':
          description: Authentication key details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthKey'
        '404':
          description: Key not found
    delete:
      operationId: deleteAuthKey
      summary: Dataiku Delete an authentication key
      description: >-
        Delete an authentication key.
      tags:
        - Authentication
      parameters:
        - $ref: '#/components/parameters/keyId'
      responses:
        '204':
          description: Key deleted
        '404':
          description: Key not found
  /metrics:
    get:
      operationId: getMetrics
      summary: Dataiku Get API node metrics
      description: >-
        Retrieve metrics about the API node including request counts,
        latencies, and error rates.
      tags:
        - Metrics
      responses:
        '200':
          description: API node metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metrics'
        '401':
          description: Unauthorized
  /health:
    get:
      operationId: getHealth
      summary: Dataiku Get API node health
      description: >-
        Check the health status of the API node.
      tags:
        - Metrics
      responses:
        '200':
          description: API node is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
      security: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Admin API key passed as Bearer token
  parameters:
    serviceId:
      name: serviceId
      in: path
      required: true
      description: Unique service identifier
      schema:
        type: string
    generationId:
      name: generationId
      in: path
      required: true
      description: Generation (version) identifier
      schema:
        type: string
    keyId:
      name: keyId
      in: path
      required: true
      description: Authentication key identifier
      schema:
        type: string
  schemas:
    ServiceSummary:
      type: object
      properties:
        serviceId:
          type: string
          description: Unique service identifier
        enabled:
          type: boolean
          description: Whether the service is enabled
        activeGeneration:
          type: string
          description: Currently active generation identifier
        generationCount:
          type: integer
          description: Number of available generations
    Service:
      type: object
      properties:
        serviceId:
          type: string
          description: Unique service identifier
        enabled:
          type: boolean
          description: Whether the service is enabled
        activeGeneration:
          type: string
          description: Currently active generation identifier
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/Endpoint'
          description: List of endpoints provided by this service
        generationCount:
          type: integer
          description: Number of available generations
    Endpoint:
      type: object
      properties:
        id:
          type: string
          description: Endpoint identifier
        type:
          type: string
          enum:
            - STD_PREDICTION
            - CUSTOM_PREDICTION
            - R_PREDICTION
            - CUSTOM_R_PREDICTION
            - SQL_QUERY
            - DATASET_LOOKUP
            - R_FUNCTION
            - PYTHON_FUNCTION
          description: Endpoint type
        modelRef:
          type: string
          description: Reference to the model used by this endpoint
    GenerationSummary:
      type: object
      properties:
        generationId:
          type: string
          description: Generation identifier
        active:
          type: boolean
          description: Whether this is the active generation
        createdOn:
          type: integer
          format: int64
          description: Creation timestamp
    Generation:
      type: object
      properties:
        generationId:
          type: string
          description: Generation identifier
        active:
          type: boolean
          description: Whether this is the active generation
        createdOn:
          type: integer
          format: int64
          description: Creation timestamp
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/Endpoint'
          description: Endpoints in this generation
        preloaded:
          type: boolean
          description: Whether this generation is preloaded in memory
    AuthKey:
      type: object
      properties:
        id:
          type: string
          description: Key identifier
        key:
          type: string
          description: The API key value
        label:
          type: string
          description: Descriptive label
        createdOn:
          type: integer
          format: int64
          description: Creation timestamp
        allowedServices:
          type: array
          items:
            type: string
          description: List of services this key can access (empty means all)
    CreateAuthKeyRequest:
      type: object
      properties:
        label:
          type: string
          description: Descriptive label for the key
        allowedServices:
          type: array
          items:
            type: string
          description: List of services this key can access
    Metrics:
      type: object
      properties:
        totalRequests:
          type: integer
          format: int64
          description: Total number of requests processed
        activeRequests:
          type: integer
          description: Number of currently active requests
        averageLatencyMs:
          type: number
          format: double
          description: Average request latency in milliseconds
        errorCount:
          type: integer
          format: int64
          description: Total number of error responses
        serviceMetrics:
          type: object
          additionalProperties:
            type: object
            properties:
              requestCount:
                type: integer
                format: int64
              averageLatencyMs:
                type: number
                format: double
              errorCount:
                type: integer
                format: int64
          description: Per-service metrics keyed by service ID
    HealthStatus:
      type: object
      properties:
        status:
          type: string
          enum:
            - HEALTHY
            - DEGRADED
            - UNHEALTHY
          description: Overall health status
        details:
          type: object
          description: Additional health check details