openapi: 3.1.0
info:
  title: Adaption Adaptive Data Datasets API
  version: v1
  description: REST API for Adaption's Adaptive Data platform — ingest a dataset (local file upload, Hugging Face, or Kaggle), run an augmentation/adaptation pipeline with brand and quality controls, evaluate quality, and export the processed rows. Reconstructed faithfully from the public Stainless-generated API reference at https://docs.adaptionlabs.ai/api. Field and operation names match the documented surface; this is a derived spec, not the provider's canonical OpenAPI.
  contact:
    name: Adaption Support
    email: support@adaptionlabs.ai
    url: https://docs.adaptionlabs.ai/resources/support/
  x-provenance:
    generated: '2026-07-17'
    method: derived
    source: https://docs.adaptionlabs.ai/api
servers:
- url: https://api.prod.adaptionlabs.ai
  description: Production
security:
- bearerAuth: []
tags:
- name: Datasets
  description: Create, ingest, adapt, evaluate, and export datasets.
paths:
  /api/v1/datasets:
    post:
      operationId: createDataset
      summary: Create a dataset from file upload, HuggingFace, or Kaggle
      description: 'Unified ingest endpoint. Discriminated by source.type: "file" returns upload instructions for a presigned S3 PUT, "huggingface" and "kaggle" start an async import.'
      tags:
      - Datasets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasetRequest'
      responses:
        '200':
          description: Dataset created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDatasetResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      operationId: listDatasets
      summary: List datasets
      description: List datasets with cursor pagination, filtering, and search.
      tags:
      - Datasets
      parameters:
      - name: created_after
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: ISO 8601 datetime — datasets created after this time.
      - name: created_before
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: ISO 8601 datetime — datasets created before this time.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Cursor from the previous response next_cursor field.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 20
        description: Number of results (max 100
        default 20). Used with cursor pagination.: null
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search by dataset name (case-insensitive contains).
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - created_at
          - updated_at
          - name
          default: created_at
        description: Sort field.
      - name: sort_direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        description: Sort direction.
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - running
          - succeeded
          - failed
        description: Filter by status.
      responses:
        '200':
          description: Paginated dataset list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Dataset'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                    description: Cursor for the next page, null when no more results.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/datasets/{dataset_id}:
    get:
      operationId: getDataset
      summary: Get a dataset by ID
      tags:
      - Datasets
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      responses:
        '200':
          description: Dataset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/datasets/{dataset_id}/status:
    get:
      operationId: getDatasetStatus
      summary: Get the processing status of a dataset
      tags:
      - Datasets
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      responses:
        '200':
          description: Dataset status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/datasets/{dataset_id}/evaluation:
    get:
      operationId: getDatasetEvaluation
      summary: Get evaluation results for a dataset
      tags:
      - Datasets
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      responses:
        '200':
          description: Evaluation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetEvaluation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/datasets/{dataset_id}/run:
    post:
      operationId: runDataset
      summary: Start an augmentation run (or estimate cost)
      description: Validates column mapping and recipe configuration, reserves credits, and starts the augmentation pipeline. Set estimate=true to validate and get a cost quote without starting a run.
      tags:
      - Datasets
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunRequest'
      responses:
        '200':
          description: Run started or cost estimate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /api/v1/datasets/{dataset_id}/download:
    get:
      operationId: downloadDataset
      summary: Download the processed dataset
      description: Streams the processed rows in the requested file format. Works on datasets with status ready (full output) and on failed datasets (partial output). Returns 422 only when no run has ever started on this dataset.
      tags:
      - Datasets
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: fileFormat
        in: query
        required: false
        schema:
          type: string
          enum:
          - csv
          - json
          - jsonl
          - parquet
        description: Output file format. Defaults to the original upload format if omitted.
      responses:
        '200':
          description: Streamed processed dataset
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /api/v1/datasets/{dataset_id}/publish:
    post:
      operationId: publishDataset
      summary: Publish a dataset to an external platform
      description: Publishes the processed dataset to Hugging Face or Kaggle. Currently returns 501 — not yet implemented.
      tags:
      - Datasets
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - target
              properties:
                target:
                  type: string
                  enum:
                  - huggingface
                  - kaggle
                  description: Destination platform for publishing the dataset.
                target_spec:
                  type: object
                  additionalProperties: true
                  description: Target-specific configuration (e.g. repo name for HuggingFace
                  slug for Kaggle).: null
      responses:
        '200':
          description: Publish job accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  publish_id:
                    type: string
                    description: Unique identifier for the publish job.
                  status:
                    type: string
                    description: Status of the publish job.
                  message:
                    type: string
                    description: Additional information about the publish request.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '501':
          $ref: '#/components/responses/NotImplemented'
components:
  schemas:
    FileSource:
      type: object
      required:
      - type
      - file_format
      - name
      properties:
        type:
          type: string
          enum:
          - file
        file_format:
          type: string
          enum:
          - csv
          - json
          - jsonl
          - parquet
          description: Format of the file being uploaded.
        name:
          type: string
          description: Human-readable name for the dataset.
    DatasetEvaluation:
      type: object
      properties:
        dataset_id:
          type: string
          description: Dataset ID.
        quality:
          type: object
          description: Structured quality metrics. Null until evaluation completes.
          properties:
            grade_before:
              type: string
              description: Letter grade (A-E) before augmentation.
            grade_after:
              type: string
              description: Letter grade (A-E) after augmentation.
            improvement_percent:
              type: number
              description: Relative quality improvement as a percentage.
            percentile_after:
              type: number
              description: Percentile rank (0-100) after augmentation.
            score_after:
              type: number
              description: Quality score (0-10) after augmentation.
    RunRequest:
      type: object
      properties:
        estimate:
          type: boolean
          description: Validate and quote cost without starting a run.
        training_type:
          type: string
          description: Adaptation training type (e.g. instruction_dataset).
        column_mapping:
          $ref: '#/components/schemas/ColumnMapping'
        brand_controls:
          type: object
          description: Brand and quality controls for generated completions.
          properties:
            blueprint:
              type: string
              description: Freeform brand/style instructions injected as a system prompt.
            hallucination_mitigation:
              type: boolean
              description: Enable web-search grounding to reduce hallucinations.
            length:
              type: string
              enum:
              - minimal
              - concise
              - detailed
              - extensive
              description: Target response length.
            safety_categories:
              type: array
              items:
                type: string
              description: Content safety categories to enforce.
        recipe_specification:
          type: object
          additionalProperties: true
          description: Recipe configuration (e.g. reasoning_traces).
    Error:
      type: object
      description: Error envelope carrying a stable code, severity, and message.
      properties:
        code:
          type: string
          description: Stable error code (e.g. E0100).
        level:
          type: string
          enum:
          - error
          - warning
        message:
          type: string
    CreateDatasetRequest:
      type: object
      required:
      - source
      properties:
        source:
          description: 'Dataset source configuration. Discriminated by type: file, huggingface, or kaggle.'
          oneOf:
          - $ref: '#/components/schemas/FileSource'
          - $ref: '#/components/schemas/HuggingfaceSource'
          - $ref: '#/components/schemas/KaggleSource'
    DatasetStatus:
      type: object
      properties:
        dataset_id:
          type: string
          description: Dataset ID.
        error_data:
          $ref: '#/components/schemas/ErrorData'
        progress:
          type: object
          description: Processing progress. Null when no run is active.
          properties:
            percent:
              type: number
            processed_rows:
              type: integer
            total_rows:
              type: integer
    KaggleSource:
      type: object
      required:
      - type
      - url
      - files
      properties:
        type:
          type: string
          enum:
          - kaggle
        url:
          type: string
          description: Kaggle dataset page URL.
        files:
          type: array
          items:
            type: string
    HuggingfaceSource:
      type: object
      required:
      - type
      - url
      - files
      properties:
        type:
          type: string
          enum:
          - huggingface
        url:
          type: string
          description: Hugging Face dataset URL.
        files:
          type: array
          items:
            type: string
    ColumnMapping:
      type: object
      description: User-configured column mapping. Null if not yet configured.
      properties:
        chat:
          type: string
        completion:
          type: string
        context:
          type: array
          items:
            type: string
        image:
          type: string
        prompt:
          type: string
    ErrorData:
      type: object
      description: Error details if the dataset failed. Null otherwise.
      properties:
        code:
          type: string
          description: Stable error code when the failure was structured (e.g. E0100).
        level:
          type: string
          enum:
          - error
          - warning
          description: Severity when known.
        message:
          type: string
          description: Error message.
    CreateDatasetResponse:
      type: object
      properties:
        dataset_id:
          type: string
          description: ID of the newly created dataset.
        status:
          type: string
          description: Current dataset status.
        upload_instructions:
          type: object
          description: Upload instructions for file sources. PUT your file to the provided URL.
          properties:
            method:
              type: string
              description: HTTP method to use.
            s3_key:
              type: string
              description: S3 object key.
            url:
              type: string
              description: Pre-signed URL for uploading the file.
    Dataset:
      type: object
      properties:
        dataset_id:
          type: string
          description: Unique dataset identifier.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the dataset was created.
        status:
          type: string
          enum:
          - pending
          - running
          - succeeded
          - failed
          description: Current dataset status.
        configured_column_mapping:
          $ref: '#/components/schemas/ColumnMapping'
        error_data:
          $ref: '#/components/schemas/ErrorData'
    RunResponse:
      type: object
      properties:
        estimate:
          type: boolean
          description: Whether this was an estimate-only request.
        estimatedCreditsConsumed:
          type: number
          description: Estimated number of credits consumed by this run.
        estimatedMinutes:
          type: number
          description: Estimated processing time in minutes.
        multimodalPricingApplied:
          type: boolean
          description: True when an image column is mapped and also listed in context_columns.
        creditMultiplier:
          type: number
          description: 10 credits per 100 output rows when multimodalPricingApplied is true.
        run_id:
          type:
          - string
          - 'null'
          description: Unique identifier for this pipeline run. Null for estimate-only requests.
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotImplemented:
      description: Endpoint not yet implemented
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Request could not be processed (e.g. no run has started on the dataset)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    DatasetId:
      name: dataset_id
      in: path
      required: true
      schema:
        type: string
      description: Unique dataset identifier.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key issued in the Adaption app (Settings → API keys). Format pt_live_... . Send as `Authorization: Bearer <key>` or set the ADAPTION_API_KEY environment variable for the SDK.'