Create, list, run, evaluate, download, and publish adaptive datasets.
openapi: 3.1.0
info:
title: Adaption Adaptive Data Datasets API
version: 0.4.0
x-adaption-generated: '2026-07-17'
x-adaption-method: derived
x-adaption-source: Derived faithfully from the official first-party Python SDK `adaption` v0.4.0 (PyPI; generated with Stainless from Adaption's OpenAPI spec) — api.md endpoint map + src/adaption/types/* request/response models and src/adaption/_client.py (base URL + auth). Adaption does not publish the source OpenAPI at a public URL; this is a faithful reconstruction of the documented surface, not a fabrication.
description: The Adaptive Data API lets you ingest, adapt, evaluate, and export model-ready training datasets. Upload a dataset (direct file, HuggingFace, or Kaggle), configure column roles and augmentation recipes, run the adaptation pipeline, read the quality evaluation, download the adapted dataset, and publish it back to HuggingFace or Kaggle.
contact:
name: Adaption Labs
email: info@adaptionlabs.ai
url: https://docs.adaptionlabs.ai/
termsOfService: https://adaptionlabs.ai/terms-of-service
servers:
- url: https://api.prod.adaptionlabs.ai
description: Production
security:
- bearerAuth: []
tags:
- name: Datasets
description: Create, list, run, evaluate, download, and publish adaptive datasets.
paths:
/api/v1/datasets:
post:
operationId: createDataset
tags:
- Datasets
summary: Create a dataset
description: Create a dataset from a file, HuggingFace, or Kaggle source. For file sources the response includes pre-signed upload instructions.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetCreateParams'
responses:
'200':
description: Dataset created
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetCreateResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
get:
operationId: listDatasets
tags:
- Datasets
summary: List datasets
description: List datasets with cursor pagination, filtering, and sorting. Returns up to `limit` items plus a `next_cursor` for the following page.
parameters:
- name: cursor
in: query
description: Cursor from the previous response's next_cursor field.
schema:
type: string
- name: limit
in: query
description: Number of results (max 100, default 20). Used with cursor pagination.
schema:
type: number
default: 20
maximum: 100
- name: q
in: query
description: Search by dataset name (case-insensitive contains).
schema:
type: string
- name: status
in: query
description: 'Filter by status: pending | running | succeeded | failed'
schema:
type: string
enum:
- pending
- running
- succeeded
- failed
- name: created_after
in: query
description: ISO 8601 datetime — datasets created after this time.
schema:
type: string
format: date-time
- name: created_before
in: query
description: ISO 8601 datetime — datasets created before this time.
schema:
type: string
format: date-time
- name: sort
in: query
description: 'Sort field: created_at | updated_at | name (default: created_at).'
schema:
type: string
enum:
- created_at
- updated_at
- name
default: created_at
- name: sort_direction
in: query
description: 'Sort direction: asc | desc (default: desc).'
schema:
type: string
enum:
- asc
- desc
default: desc
responses:
'200':
description: Page of datasets
content:
application/json:
schema:
type: object
properties:
datasets:
type: array
items:
$ref: '#/components/schemas/DatasetListItem'
next_cursor:
type:
- string
- 'null'
description: Cursor for the next page; null when there are no more pages.
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/datasets/{dataset_id}:
get:
operationId: getDataset
tags:
- Datasets
summary: Get a dataset
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
tags:
- Datasets
summary: Get dataset processing status
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: Status
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetGetStatusResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v1/datasets/{dataset_id}/evaluation:
get:
operationId: getDatasetEvaluation
tags:
- Datasets
summary: Get dataset quality evaluation
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: Evaluation
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetGetEvaluationResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v1/datasets/{dataset_id}/run:
post:
operationId: runDataset
tags:
- Datasets
summary: Run the adaptation pipeline (or estimate its cost)
description: 'Launch an augmentation run over the dataset. Set `estimate: true` to validate the request and return the estimated credit cost without starting a run. Pass `job_specification.idempotency_key` for safe retries — a launch with an existing key returns the original response.'
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRunParams'
responses:
'200':
description: Run launched or estimate returned
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRunResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/datasets/{dataset_id}/download:
get:
operationId: downloadDataset
tags:
- Datasets
summary: Download the adapted dataset
parameters:
- $ref: '#/components/parameters/DatasetId'
- name: fileFormat
in: query
description: Output file format. Defaults to the original upload format if omitted.
schema:
type: string
enum:
- csv
- json
- jsonl
- parquet
responses:
'200':
description: Dataset file contents (format per fileFormat)
content:
application/octet-stream:
schema:
type: string
format: binary
'404':
$ref: '#/components/responses/NotFound'
/api/v1/datasets/{dataset_id}/publish:
post:
operationId: publishDataset
tags:
- Datasets
summary: Publish the dataset to HuggingFace or Kaggle
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPublishParams'
responses:
'200':
description: Publish job accepted
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPublishResponse'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
DatasetGetEvaluationResponse:
type: object
required:
- dataset_id
properties:
dataset_id:
type: string
quality:
type:
- object
- 'null'
description: Structured quality metrics. Null until evaluation completes.
properties:
grade_after:
type:
- string
- 'null'
grade_before:
type:
- string
- 'null'
improvement_percent:
type:
- number
- 'null'
percentile_after:
type:
- number
- 'null'
score_after:
type:
- number
- 'null'
description: Quality score (0-10) after augmentation
score_before:
type:
- number
- 'null'
description: Quality score (0-10) before augmentation
raw_results:
type:
- object
- 'null'
additionalProperties: true
status:
type:
- string
- 'null'
description: pending | running | succeeded | failed | skipped
DatasetCreateResponse:
type: object
required:
- dataset_id
- status
properties:
dataset_id:
type: string
status:
type: string
description: Current dataset status
upload_instructions:
type:
- object
- 'null'
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
pass back in the complete request if needed: null
url:
type: string
description: Pre-signed URL for uploading the file
Progress:
type: object
description: Processing progress. Null when no run is active.
properties:
percent:
type:
- integer
- 'null'
description: Progress percentage (0-100)
processed_rows:
type:
- integer
- 'null'
description: Number of rows processed so far
total_rows:
type:
- integer
- 'null'
description: Total rows to process
EvaluationSummary:
type: object
description: Compact evaluation summary. Null if evaluation has not completed.
properties:
grade_after:
type:
- string
- 'null'
description: Letter grade (A-E) after augmentation
grade_before:
type:
- string
- 'null'
description: Letter grade (A-E) before augmentation
improvement_percent:
type:
- number
- 'null'
description: Relative improvement percentage
score_after:
type:
- number
- 'null'
description: Quality score after augmentation
score_before:
type:
- number
- 'null'
description: Quality score before augmentation
DatasetCreateParams:
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'
discriminator:
propertyName: type
HuggingfaceSource:
type: object
required:
- files
- type
- url
properties:
type:
type: string
enum:
- huggingface
files:
type: array
items:
type: string
description: File paths to download from the repository
url:
type: string
description: HuggingFace dataset repository URL
DatasetGetStatusResponse:
type: object
required:
- dataset_id
- status
properties:
dataset_id:
type: string
error_data:
$ref: '#/components/schemas/ErrorData'
progress:
$ref: '#/components/schemas/Progress'
row_count:
type:
- integer
- 'null'
status:
type: string
enum:
- pending
- running
- succeeded
- failed
KaggleSource:
type: object
required:
- files
- type
- url
properties:
type:
type: string
enum:
- kaggle
files:
type: array
items:
type: string
description: File paths to download from the dataset
url:
type: string
description: Kaggle dataset URL
DatasetPublishParams:
type: object
required:
- target
properties:
target:
type: string
enum:
- huggingface
- kaggle
description: Destination platform for publishing
target_spec:
type: object
additionalProperties: true
description: Target-specific configuration
ErrorEnvelope:
type: object
description: Structured error payload. `code` is a stable error code (e.g. E0100) when the failure was structured.
properties:
code:
type:
- string
- 'null'
description: Stable error code when the failure was structured (e.g. E0100)
level:
type:
- string
- 'null'
enum:
- error
- warning
- null
description: Severity when known
message:
type:
- string
- 'null'
description: Error message
DatasetRunResponse:
type: object
required:
- estimate
- estimatedCreditsConsumed
- estimatedMinutes
- multimodalPricingApplied
properties:
estimate:
type: boolean
description: Whether this was an estimate-only request
estimatedCreditsConsumed:
type: number
description: Estimated 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 in context
creditMultiplier:
type:
- number
- 'null'
description: 10 credits per 100 output rows when multimodal
run_id:
type:
- string
- 'null'
description: Unique run id. Null for estimate-only requests.
ConfiguredColumnMapping:
type: object
description: User-configured column mapping. Null if not yet configured.
properties:
chat:
type:
- string
- 'null'
completion:
type:
- string
- 'null'
context:
type: array
items:
type: string
image:
type:
- string
- 'null'
prompt:
type:
- string
- 'null'
ErrorData:
type: object
description: Error details if the dataset failed. Null otherwise.
properties:
code:
type:
- string
- 'null'
description: Stable error code when the failure was structured (e.g. E0100)
level:
type:
- string
- 'null'
enum:
- error
- warning
- null
description: Severity when known
message:
type:
- string
- 'null'
description: Error message
DatasetRunParams:
type: object
properties:
brand_controls:
type: object
description: Brand and quality controls for generated completions.
properties:
blueprint:
type: string
description: Freeform brand/style system prompt for every generated completion
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
column_mapping:
type: object
description: Column role assignments for augmentation. Required for real runs, optional for estimate-only.
properties:
chat:
type: string
completion:
type: string
context:
type: array
items:
type: string
image:
type: string
prompt:
type: string
universal_prompt:
type: string
estimate:
type: boolean
description: When true, validates and returns estimated credit cost without starting a run.
job_specification:
type: object
description: Job execution parameters
properties:
idempotency_key:
type: string
description: Client-generated idempotency key for safe retries. If a launch with the same key already exists, the original response is returned.
max_rows:
type: number
description: Maximum number of rows to process in this run
language_expansion:
type:
- object
- 'null'
description: Translation/localization expansion (three-state field).
properties:
type:
type: string
enum:
- translate
- localize
sample_rate:
type: number
description: Fraction (0.01-1) of input rows expanded per target
languages:
type: array
items:
type: string
description: Target ISO 639-1 codes (type=translate)
pairs:
type: array
items:
type: object
required:
- country
- language
properties:
country:
type: string
description: ISO 3166-1 alpha-2 country code
language:
type: string
description: ISO 639-1 language code
recipe_specification:
type: object
description: Augmentation recipe configuration. Omitted recipes use backend defaults.
properties:
recipes:
type: object
properties:
deduplication:
type: boolean
description: Remove near-duplicate rows
prompt_rephrase:
type: boolean
description: Rephrase prompts for variety and clarity
reasoning_traces:
type: boolean
description: Add reasoning traces (chain-of-thought) to completions
version:
type: string
description: Recipe schema version
training_type:
type: string
enum:
- instruction_dataset
- preference_pairs
description: How to adapt the dataset. instruction_dataset (default) produces SFT pairs; preference_pairs generates chosen/rejected pairs for DPO.
DatasetListItem:
type: object
required:
- created_at
- dataset_id
- status
- updated_at
properties:
created_at:
type: string
format: date-time
dataset_id:
type: string
status:
type: string
enum:
- pending
- running
- succeeded
- failed
updated_at:
type: string
format: date-time
description:
type:
- string
- 'null'
description: Auto-generated description of the dataset contents
name:
type:
- string
- 'null'
row_count:
type:
- integer
- 'null'
FileSource:
type: object
required:
- file_format
- name
- type
properties:
type:
type: string
enum:
- file
file_format:
type: string
enum:
- csv
- json
- jsonl
- parquet
name:
type: string
description: Human-readable name for the dataset
DatasetPublishResponse:
type: object
required:
- publish_id
- status
properties:
publish_id:
type: string
description: Unique identifier for the publish job
status:
type: string
description: Status of the publish job
message:
type:
- string
- 'null'
Dataset:
type: object
required:
- created_at
- dataset_id
- status
- updated_at
properties:
configured_column_mapping:
$ref: '#/components/schemas/ConfiguredColumnMapping'
created_at:
type: string
format: date-time
dataset_id:
type: string
description: Unique dataset identifier
error_data:
$ref: '#/components/schemas/ErrorData'
evaluation_summary:
$ref: '#/components/schemas/EvaluationSummary'
image_column_formats:
type:
- object
- 'null'
additionalProperties:
type: string
enum:
- embedded_bytes
- url
- file_reference
description: Per-column export encoding for detected image columns (column name, format).
name:
type:
- string
- 'null'
progress:
$ref: '#/components/schemas/Progress'
row_count:
type:
- integer
- 'null'
run_id:
type:
- string
- 'null'
description: ID of the currently active run
status:
type: string
enum:
- pending
- running
- succeeded
- failed
updated_at:
type: string
format: date-time
responses:
BadRequest:
description: Invalid request. Body carries a structured error with a stable code (e.g. E0100).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
RateLimited:
description: Too many requests. Back off and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
UnprocessableEntity:
description: Request understood but semantically invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
parameters:
DatasetId:
name: dataset_id
in: path
required: true
description: Unique dataset identifier
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Send your Adaption API key as a Bearer token: `Authorization: Bearer <ADAPTION_API_KEY>`. Keys are created in the app (Settings, API keys) and are prefixed `pt_live_`.'