Headless API reference

Getting started

ModAstera Headless API#

Run ModAstera workflows from your own backend: create datasets, launch training and evaluation pipelines, deploy models, call predictors, and retrieve files or artifacts — all with API keys, no browser required.

These docs target server-side clients. Every example works with curl or Python 3.10+ and assumes you have workspace access and a raw API key issued from the authenticated platform frontend. The key authorizes operational API calls only; account-management routes continue to use frontend token authentication.

Quickstart

Make your first authenticated request and create a dataset in five minutes.

Datasets

Create datasets, upload samples, and download annotations.

Pipelines

Train and evaluate models with task queries and async runs.

Deployments

Promote model versions, call predictors, and track metrics.

MCP adapter

Use the local stdio MCP tools for trusted agent-driven workflows.

Coverage status

See which workflow families are covered in the public headless API guide.

API Reference

Browse Redoc-like endpoint cards for the stable public API surface.

Getting started

Quickstart#

Start in the platform frontend. After you create a user account, complete onboarding, and copy the key shown by the frontend, you can verify authentication, create a dataset, upload a sample, and read summary data.

ModAstera platform frontend with Get Started buttons — Open the platform frontend, then use Get Started or Get Started for Free to begin account creation.

Create a platform account
Open the platform frontend, such as http://localhost:2970/en in local development, and choose Get Started. Create an account with first name, last name, email address, password, and the verification challenge. Google signup is available when the environment has Google OAuth configured.
Complete onboarding
After signup or login, finish the onboarding form. Standalone users complete profile details (Role, AI Experience Level, interests, and terms acceptance), then create an organization with name, company type, company size, and optional team invitations.
Create and copy a key
From the workspace, open Settings, select Apps and API Keys, then choose Create API Key. Enter a name and optional expiry, create the key, and copy the raw value from the success dialog. The frontend only shows the raw key at creation time.
Set environment variables
Keep all secrets and resource ids in environment variables — never hardcode keys.
Verify operational access
Call /datasets/datasets/ before starting any workflow.
Run one workflow end to end
Create a dataset, upload a file, and read summary or analysis data.

export MODASTERA_API_BASE_URL="https://api.modastera.com"
export MODASTERA_WS_BASE_URL="wss://api.modastera.com"
export MODASTERA_API_KEY="paste_raw_key_copied_from_platform_frontend"
export DATASET_ID=""
export ML_BACKEND_PROFILE_ID=""
export SAMPLE_ID=""
export ANNOTATION_FILE_ID=""
export TASK_QUERY_ID=""
export TASK_INDEX="0"
export RESOURCE_ID=""
export MODEL_VERSION_ID=""
export EXPERIMENT_ID=""
export ARTIFACT_ID=""
export JOB_ID=""
export IMPORT_JOB_ID=""
export DEPLOYMENT_ID=""
export USAGE_ID=""

# 1. Configure local shell values.
export MODASTERA_API_BASE_URL="https://api.modastera.com"
export MODASTERA_API_KEY="paste_raw_key_copied_from_platform_frontend"

# 2. Verify authentication against an operational API route.
curl "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: application/json"

# 3. Create a dataset.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"headless-smoke-test","format":"image","description":"Created from the Headless API quickstart"}'

# 4. Upload a sample file. Save the returned sample id.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/samples/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "split=training" \
  -F "file=@./sample.png"

# 5. Inspect dataset summaries and samples.
curl "$MODASTERA_API_BASE_URL/datasets/summary/?archived=False&view=list" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/analysis/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

From here, continue to Pipelines to train a model on the dataset you just created, or read Authentication for key handling guidance.

Getting started

First model to prediction#

The fastest way to validate a headless integration is to carry one set of ids through the full workflow. Each response gives you the next id to store in an environment variable or secret-backed job context.

The handoff sequence is DATASET_ID -> TASK_QUERY_ID -> MODEL_VERSION_ID -> DEPLOYMENT_ID -> prediction.

Create data
Create a dataset, upload samples, and save the returned dataset id as DATASET_ID.
Train and evaluate
Create a task query with the dataset id, wait until response_status is completed, start a task run with task_query_id, then poll progress until task_status is completed or ended.
Select a model version
List model versions for the task query, compare candidates if needed, and save the chosen id as MODEL_VERSION_ID.
Deploy and predict
Create a deployment, save DEPLOYMENT_ID, call the predictor from your server, then read metrics and artifacts for auditability.

# 1. Create a dataset and upload at least one training sample.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"first-model-workflow","format":"image","description":"End-to-end headless workflow"}'

curl -X POST "$MODASTERA_API_BASE_URL/datasets/samples/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "split=training" \
  -F "file=@./sample.png"

# 2. Create a task query and wait for pipeline generation to complete.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"first-model-training","instruction":"Train and evaluate an image classifier","dataset_id":"'$DATASET_ID'"}'

curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Train an image classification model and evaluate it on the validation split."}'

curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# 3. Start training/evaluation and poll until task_status is completed or ended.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-runs/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_query_id":"'$TASK_QUERY_ID'"}'

curl "$MODASTERA_API_BASE_URL/agents/task-progress/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# 4. Select a model version, create a deployment, and call the predictor.
curl "$MODASTERA_API_BASE_URL/resources/pipeline-model-versions/?task_query=$TASK_QUERY_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/resources/deployments/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"first-model-predictor","task_query":"'$TASK_QUERY_ID'","selected_model_version":"'$MODEL_VERSION_ID'","selected_checkpoint_stage":"best"}'

curl -X POST "$MODASTERA_API_BASE_URL/executors/predictor/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "deployment=$DEPLOYMENT_ID" \
  -F "file=@./holdout.png"

Getting started

Authentication#

API-key authentication is an operational client credential, not an account-management credential. Account creation, organization or team setup, email confirmation, onboarding, and key creation happen in the platform frontend. After that, machine clients use the raw API key for dataset, pipeline, run, deployment, and result APIs.

REST clients authenticate with an API key in the Authorization header. Prefer the explicit Api-Key scheme for new integrations. The Bearer scheme is also accepted for headless API-key auth when a client only exposes a bearer-token field: Authorization: Bearer <raw_api_key>.

curl "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: application/json"

# Prefer WebSocket Authorization headers when your client supports them.
Authorization: Api-Key <raw_api_key>

# Browser-style WebSocket clients usually cannot set custom headers.
# Use a URL-encoded api_key query parameter only for WebSocket connections.
wss://api.modastera.com/ws/task-runs/<task_query_id>/?api_key=<urlencoded_raw_api_key>

Core concepts

Resources and IDs#

Headless integrations never depend on localStorage, cookies, or other browser-only state. Every response returns the ids, status handles, artifact references, and visualization-ready data needed for the next request.

Resources — datasets, samples, task queries, runs, deployments, artifacts, and reports all use backend ids returned by API responses.
Ownership — keys authenticate as their owning user for operational object scoping. They do not grant access to account setup, organization management, or team invitations.
Availability — these docs only describe endpoints that are stable enough for external use. Surfaces still undergoing schema or permission review are excluded until they graduate. See the API Reference for endpoint-level coverage.

Core concepts

Coverage status#

The public headless guide covers the stable workflow families below. Endpoint families not listed here are outside the current public headless surface and are intentionally omitted until their contracts are stable.

Workflow family	Public routes	Status	Notes
Setup and authentication	Frontend onboarding, `Authorization` header	Covered	API keys are obtained in the platform frontend and used server-side for operational APIs.
Datasets and samples	`/datasets/datasets/`, `/datasets/samples/`, `/datasets/summary/`	Covered	Includes dataset/sample CRUD, local registration, CSV/JSON/COCO and mask ingestion, verification, analysis, sample query, and append-only split rebalance.
Task queries and runs	`/agents/task-queries/`, `/agents/task-runs/`, `/agents/task-progress/`	Covered	Includes ML profile selection, dataset preparation, lifecycle, config/definition edits, diagnostics, summaries, reports, compare, fine-tune, and interruption.
Pipeline outputs	Results, authenticated result-media relay, model-version reports, snapshot export/download, experiment artifact listings	Covered	Generated media URLs are profile-aware authenticated relays; model-card reports can be pipeline- or model-version-scoped.
Deployments and prediction	Model versions, deployments, predictor, usage, explainability, deployment metrics, chart data	Covered	Deployment creation uses a task query, selected model version, and checkpoint stage.
MCP adapter	Local stdio MCP tools backed by public operational APIs	Covered	Hosted MCP transport is not available in v1; tools authenticate through `MODASTERA_MCP_API_KEY`.

Core concepts

Async jobs#

Long-running operations return endpoint-specific handles. Pipeline generation uses the task query id and response_status; task execution uses the same task query id and task_status. Task runs return a task_query payload and may include a websocket_url for live updates, but REST polling through /agents/task-progress/<task_query_id>/ remains the durable source of truth. Dataset analysis, CSV and mask imports, dataset preparation, snapshot exports, model-card streams, and generated reports use endpoint-specific status fields, job ids, progress URLs, event streams, or downloads.

{
  "message": "Tasks execution started",
  "queued": false,
  "task_query": {
    "id": "task_query_id",
    "task_status": "in_progress"
  },
  "websocket_url": "wss://api.modastera.com/ws/task-runs/task_query_id/"
}

Task query terminal statuses include completed, ended, failed, and interrupted; interrupting can appear while cancellation is in flight. Planning terminal statuses are completed and error. Other endpoint families may use endpoint-local job status fields, so branch on the fields returned by the endpoint you started.

Core concepts

Pagination and filtering#

Pagination and filtering are endpoint-specific, not uniform across the API. Sample, annotation-file, artifact, and usage listings use their documented page or filter parameters. The full /agents/task-queries/ list remains a plain array. Dataset summaries with view=list and compact task-query synopses support opt-in cursor pagination when page_size or cursor is supplied; omitting both preserves their legacy raw-array response. Some workflow operations, such as sample query, carry page and page_sizein the request body instead of the query string.

# Page-number pagination remains endpoint-specific.
curl "$MODASTERA_API_BASE_URL/datasets/samples/?dataset=$DATASET_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/experiments/$EXPERIMENT_ID/artifacts/?include_payload=0" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/resources/all-usage/?deployment=$DEPLOYMENT_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Cursor pagination is opt-in for these compact lists.
curl "$MODASTERA_API_BASE_URL/datasets/summary/?view=list&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/task-queries-synopsis/?page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Follow the returned next or previous URL exactly with the same API key.
# Do not decode, edit, or construct the cursor yourself.
NEXT_URL="<opaque next URL returned by the response>"
curl "$NEXT_URL" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

Core concepts

Errors#

Error responses are not yet a single uniform envelope across every route. Some endpoints return {"error":"..." }, some return {"detail":"..." }, and serializer validation returns field maps. Normalize errors in your client before retrying or showing user-facing remediation.

{
  "code": "permission_denied",
  "message": "You do not have access to this dataset.",
  "request_id": "req_01HZY...",
  "details": {
    "dataset": ["Object is not visible to this API key owner."]
  }
}

Code	Meaning
`401`	Missing, malformed, revoked, inactive, or expired API key.
`403`	Key owner is authenticated but lacks object permission.
`404`	Object is missing or intentionally hidden by object scoping.
`409`	Operation conflicts with current resource or job state.
`429`	Rate limited — retry after the returned delay; heavy compute endpoints may have stricter limits.

Guides

Datasets#

Dataset routes are the first public workflow. They cover dataset CRUD, sample CRUD, sample upload and runtime payloads, filtered or explicit-selection cloning, CSV and deployment-execution imports, local no-copy registration, dashboard summaries, verification, analysis, CSV/platform JSON/COCO annotations, binary or color-map masks, sample querying, and split creation.

# Dataset list, detail, update, and delete.
curl "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl -X PATCH "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Updated from a server-side client"}'

# Upload and inspect samples.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/samples/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "split=validation" \
  -F "metadata={\"source\":\"headless-import\"}" \
  -F "file=@./sample.png"

curl "$MODASTERA_API_BASE_URL/datasets/samples/?dataset=$DATASET_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Query samples and create reproducible splits.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/sample-query/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"split":"training","page":1,"page_size":50,"include_ids":true}'

curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/create-random-splits/?response=compact" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset":"'$DATASET_ID'","training":0.7,"validation":0.2,"test":0.1,"splits_seed":42,"lock_splits":true}'

# Generate an annotation export. The response is dataset JSON with output_annotations_file updated.
curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/download-annotations/?file_format=csv" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Clone the source dataset using its current filtered selection.
# sample_ids and sample_query are alternatives; never send both.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/clone/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"approved-training-copy",
    "description":"Private clone created from an approved training selection",
    "sample_query":{
      "split":"training",
      "search":"",
      "filters":{
        "field":"label_value",
        "label":"review_status",
        "cmp":"eq",
        "value":"approved"
      }
    },
    "preserve_splits":true
  }'

# For an explicit bounded selection, replace sample_query with sample_ids.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/clone/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"explicit-sample-copy",
    "sample_ids":["'$SAMPLE_ID'"],
    "preserve_splits":false
  }'

# Import COCO JSON and apply matching annotations by image filename.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/annotations-files/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "file_format=coco" \
  -F "split=training" \
  -F "file=@./annotations.coco.json"

# Upload binary masks asynchronously. Repeat the masks field for each file.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/$DATASET_ID/upload-masks/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "masks=@./sample-001.png" \
  -F "masks=@./sample-002.png" \
  -F "label=lesion" \
  -F "split=training" \
  -F "async=true"

# Color-map masks use hex colors mapped to label names.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/$DATASET_ID/upload-masks/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "masks=@./sample-003.png" \
  -F "mask_mode=color_map" \
  -F 'color_label_map={"#ff0000":"tumor","#00ff00":"stroma"}' \
  -F 'background_colors=["#000000"]' \
  -F "async=true"

curl "$MODASTERA_API_BASE_URL/datasets/$DATASET_ID/mask-upload-progress/$JOB_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

Guides

Pipelines: generation, training, and evaluation#

Pipeline clients create or select a task query, generate or refresh its definition, wait for planning to finish, start a run, track training and evaluation, then fetch results, model cards, snapshots, and deployable model versions. The planning state is response_status; the durable training/evaluation state is task_status.

Create the pipeline record
Call POST /agents/task-queries/ with instruction and dataset_id. When the workspace offers multiple ML backends, list available profiles first and pass ml_backend_profile_id now; explicit profile selection is creation-only. Clones, fine-tunes, reruns, and later model versions inherit the applicable pinned source profile. Save the returned id as TASK_QUERY_ID.
Verify preparation and the runtime contract
Read dataset_preparation from task-query detail. The backend may adopt the source dataset, reuse a prepared dataset, or create a derived split dataset. Then read /runtime-contract/to confirm the adopted dataset, target, architecture, criterion, metrics, and validation warnings.
Review segmentation architecture choices
For segmentation workflows, leave model selection automatic unless the integration has verified a specific choice. The architecture catalog can include EoMT DINOv2 panoptic variants and RF-DETR Segmentation or RTMDet-Ins instance variants. After planning, inspect the task-scoped related models and confirm support on the selected ML backend before pinning a key or swapping the architecture.
Plan, then start training and evaluation
Refresh planning with PATCH /agents/task-queries/<id>/, wait for response_status: completed, then call POST /agents/task-runs/ with task_query_id. A 202 means the run started, queued, or was already running.
Recover and read final outputs
Use WebSockets for live updates, but keep polling or refetching REST state. The final /run-summary/ consolidates the runtime contract, dataset verification, latest model version, canonical metrics, analysis, and failure details. Follow generated media relay URLs from /results/ with the same API key.

# Create a pipeline record. Save the returned id as TASK_QUERY_ID.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"headless-training-run",
    "instruction":"Train and evaluate an image classifier",
    "dataset_id":"'$DATASET_ID'"
  }'

# Generate or refresh the pipeline definition.
curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Train an image classification model and evaluate it on the validation split."}'

# Optional live planning channels. URL-encode the raw key first.
ENCODED_API_KEY=$(python3 -c 'import os, urllib.parse; print(urllib.parse.quote(os.environ["MODASTERA_API_KEY"], safe=""))')
printf "%s\n" "$MODASTERA_WS_BASE_URL/ws/task-status/$TASK_QUERY_ID/?api_key=$ENCODED_API_KEY"
printf "%s\n" "$MODASTERA_WS_BASE_URL/ws/task-response/$TASK_QUERY_ID/?api_key=$ENCODED_API_KEY"

# Durable readiness check. Wait for response_status=completed before running.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Inspect/edit the generated definition when deterministic control is needed.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/definition/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/definition/tasks/$TASK_INDEX/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions":"Keep the evaluation split unchanged."}'

{
  "id": "task_query_id",
  "task_status": "completed",
  "task_result": {
    "status": { "name": "completed" },
    "metrics": { "accuracy": 0.94 },
    "results": { "confusion_matrix": [[12, 1], [2, 15]] },
    "analysis": { "summary": "Final evaluation metrics" }
  }
}

# Discover the ML backends available to this API-key user.
curl "$MODASTERA_API_BASE_URL/users/ml-backend-profiles/available/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Select a profile only when creating the pipeline. Omit it for default routing.
# Clones, fine-tunes, and later model versions inherit their pinned source profile.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"profile-routed-training",
    "instruction":"Train and evaluate an image classifier",
    "dataset_id":"'$DATASET_ID'",
    "ml_backend_profile_id":"'$ML_BACKEND_PROFILE_ID'"
  }'

Readiness failures are ordinary operational states. Starting a run can return 409 when planning is still pending or running, the pipeline has no executable tasks, or a training/evaluation task has no dataset attached. The backend handles its own ML runtime credentials; headless clients only send their API key to the public backend APIs and WebSocket channels.

Guides

Deployments and prediction#

Deployment APIs support model-version discovery, candidate comparison, deployment lifecycle, predictor calls, text generation for compatible deployments, usage inspection, explainability, and usage or latency charts. Create deployments with a task_query, selected_model_version, and an optional selected_checkpoint_stage such as best or final. Prediction examples use server-side multipart requests so API keys never reach a browser.

# List deployable model versions and compare candidates.
curl "$MODASTERA_API_BASE_URL/resources/pipeline-model-versions/?task_query=$TASK_QUERY_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/resources/pipeline-model-versions/compare/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"versions":["model_version_id_1","model_version_id_2"]}'

# Create/list deployments.
curl -X POST "$MODASTERA_API_BASE_URL/resources/deployments/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"headless-predictor","task_query":"'$TASK_QUERY_ID'","selected_model_version":"'$MODEL_VERSION_ID'","selected_checkpoint_stage":"best"}'

curl "$MODASTERA_API_BASE_URL/resources/deployments/?task_query=$TASK_QUERY_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Call predictor and inspect usage/metrics.
curl -X POST "$MODASTERA_API_BASE_URL/executors/predictor/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "deployment=$DEPLOYMENT_ID" \
  -F "file=@./holdout.png"

curl "$MODASTERA_API_BASE_URL/resources/deployment-metrics/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl "$MODASTERA_API_BASE_URL/resources/chart-data/latency/?deployment=$DEPLOYMENT_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl "$MODASTERA_API_BASE_URL/resources/chart-data/api-calls/?deployment=$DEPLOYMENT_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

Guides

MCP adapter: local stdio workflows#

The MCP adapter exposes trusted local tools over stdio for dataset ingestion and verification, annotation and mask upload, local preparation, ML profile discovery, pipeline configuration and execution, diagnostics, reports, and deployment. The adapter uses the same REST/API-key surface as direct clients; it does not bypass auth, permissions, queues, or result persistence.

Call modastera_get_capabilities first. It returns the tools and workflow options available to the authenticated client. Use the returned tool list as the runtime source of truth before starting longer agent workflows.

{
  "tool": "modastera_get_capabilities",
  "arguments": {}
}

See MCP Reference for every exposed tool, its arguments, return shape, backing REST endpoint, and caveats.

Guides

Files and artifacts#

File responses include metadata and stable resource ids for model-card markdown, snapshot archives, and experiment artifacts. Generated prediction and explainability media use authenticated profile-aware relay URLs returned inside task-query results and WebSocket payloads.

# Fetch metadata/listing first when available.
curl "$MODASTERA_API_BASE_URL/agents/experiments/$EXPERIMENT_ID/artifacts/?include_payload=0" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Download generated reports or exports.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/download/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -o model-card.md

curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/snapshot-export/$JOB_ID/download/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -o pipeline-snapshot.zip

# Result payloads contain ready-to-use relay URLs for generated media.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/results/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Follow the returned URL with the same API key. Do not reconstruct its path.
RESULT_MEDIA_URL="<absolute relay URL returned by the results response>"
curl "$RESULT_MEDIA_URL" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Range: bytes=0-1048575" \
  -o result-media.bin

API Reference

API Reference#

The API reference below uses curated metadata for the public headless workflow. It follows the same scanning model as an OpenAPI reference while preserving the guide-first explanations and examples in this docs app.

4workflow groups

107public endpoints

Api-Keyprimary auth scheme

Datasets API43 endpoints

Dataset endpoints cover public ingestion, sample management, filtered cloning, local-file capabilities, summaries, annotations, import jobs, sample query, and split creation.

Pipelines API40 endpoints

Pipeline endpoints cover generation, task-query lifecycle, definition/config inspection and edits, architecture discovery and swap, cloning, diagnostics, runtime summaries, training/evaluation execution, queue/progress state, reports, comparison, fine-tuning, and snapshots.

Deployments API20 endpoints

Deployment endpoints cover model-version selection, deployment lifecycle, server-side prediction calls, text generation, usage inspection, and deployment charts.

Files API4 endpoints

File endpoints expose metadata-first artifact inspection and raw downloads for markdown reports and snapshot archives used by the public workflow.

API Reference

Datasets API reference#

Dataset endpoints cover public ingestion, sample management, filtered cloning, local-file capabilities, summaries, annotations, import jobs, sample query, and split creation.

Use dataset ids returned by create/list calls as DATASET_ID for later sample, split, analysis, and training requests.
Accepted split values are training, validation, test, or no split.
Several import endpoints return job ids or progress payloads instead of raw files.
Local file reference capabilities are read-only discovery for operator-configured no-copy ingestion workflows.
Verification summary is DB-derived and useful before and after split creation to confirm sample, label, and split counts.
Dataset clone requests may select samples by explicit sample_ids or by sample_query, but never both. Omitting both copies the full source dataset.

# Dataset list, detail, update, and delete.
curl "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl -X PATCH "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Updated from a server-side client"}'

# Upload and inspect samples.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/samples/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "split=validation" \
  -F "metadata={\"source\":\"headless-import\"}" \
  -F "file=@./sample.png"

curl "$MODASTERA_API_BASE_URL/datasets/samples/?dataset=$DATASET_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Query samples and create reproducible splits.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/sample-query/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"split":"training","page":1,"page_size":50,"include_ids":true}'

curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/create-random-splits/?response=compact" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset":"'$DATASET_ID'","training":0.7,"validation":0.2,"test":0.1,"splits_seed":42,"lock_splits":true}'

# Generate an annotation export. The response is dataset JSON with output_annotations_file updated.
curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/download-annotations/?file_format=csv" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/datasets/datasets/List datasetsCovered

Returns datasets visible to the API-key owner. Use this as a lightweight operational access check.

AuthApi-Key or Bearer API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.archived`	boolean	No	Filter archived datasets.
`query.access`	string	No	Filter by dataset access value when needed.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Dataset id used by sample, split, analysis, and training calls.
`name`	string	No	Dataset display name.
`format`	string	No	Dataset modality such as image, tabular, video, or text.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

curl "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: application/json"

POST/datasets/datasets/Create a datasetCovered

Creates an empty dataset container. Upload samples before starting a training workflow.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`body.name`	string	Yes	Human-readable dataset name.
`body.format`	string	No	Dataset modality used by downstream workflows. Defaults to image.
`body.description`	string	No	Optional notes for operators.
`body.access`	private \| organization \| global	No	Dataset visibility when supported by the workspace.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Save as DATASET_ID for sample upload and task-query creation.
`created`	datetime	No	Dataset creation timestamp.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

# 1. Configure local shell values.
export MODASTERA_API_BASE_URL="https://api.modastera.com"
export MODASTERA_API_KEY="paste_raw_key_copied_from_platform_frontend"

# 2. Verify authentication against an operational API route.
curl "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: application/json"

# 3. Create a dataset.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"headless-smoke-test","format":"image","description":"Created from the Headless API quickstart"}'

# 4. Upload a sample file. Save the returned sample id.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/samples/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "split=training" \
  -F "file=@./sample.png"

# 5. Inspect dataset summaries and samples.
curl "$MODASTERA_API_BASE_URL/datasets/summary/?archived=False&view=list" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/analysis/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/datasets/datasets/{dataset_id}/Read dataset detailCovered

Reads one dataset and its serializer fields, including generated file references when present.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset to read.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Dataset id.
`labels`	array	No	Dataset labels or annotation schema when configured.
`output_annotations_file`	file field	No	Generated annotation export reference when present.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

PATCH/datasets/datasets/{dataset_id}/Update dataset metadataCovered

Partially updates dataset settings such as name, description, access, labels, or archive state.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset to update.
`query.response`	settings	No	Use settings for the frontend-equivalent settings response.

Request body

Name	Type	Required	Description
`body.name`	string	No	Updated dataset name.
`body.description`	string	No	Updated description.
`body.archived`	boolean	No	Archive or unarchive the dataset.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Updated dataset id.

Status codes

Code	Meaning
`200`	Resource was updated and the updated representation was returned.
`400`	Patch body failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to update the object.
`404`	The object is missing or hidden by permissions.

DELETE/datasets/datasets/{dataset_id}/Delete a datasetCovered

Deletes a dataset visible to the API-key owner when the owner has write access.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset to delete.

Response fields

Name	Type	Required	Description
`empty`	none	No	Successful deletes return no response body.

Status codes

Code	Meaning
`204`	Resource was deleted.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to delete the object.
`404`	The object is missing or hidden by permissions.

POST/datasets/datasets/{dataset_id}/clone/Clone a dataset or filtered selectionCovered

Creates a private dataset clone from all source samples, an explicit list of sample ids, or a server-side sample query. Query selection avoids materializing large filtered result sets in the client.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Accessible source dataset to clone.

Request body

Name	Type	Required	Description
`body.name`	string	Yes	Name for the private clone.
`body.description`	string \| null	No	Optional clone description. The source description is reused when omitted.
`body.sample_ids`	uuid[]	No	Explicit source sample ids. Mutually exclusive with sample_query.
`body.sample_query`	object	No	Server-side selection object. Mutually exclusive with sample_ids.
`body.sample_query.split`	all \| training \| validation \| test	No	Source split scope. Defaults to all.
`body.sample_query.search`	string	No	Optional case-insensitive sample-name search.
`body.sample_query.filters`	object	No	Optional AND/OR sample-query filter tree for name, data type, or indexed annotation values.
`body.preserve_splits`	boolean	No	Preserve selected samples’ source training, validation, and test memberships. Defaults to true.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Created private dataset id.
`access`	private	No	Dataset clones are created private.
`clone_summary.source_dataset_id`	uuid	No	Source dataset id.
`clone_summary.sample_count`	integer	No	Number of selected samples copied.
`clone_summary.split_counts`	object	No	Copied training, validation, and test membership counts.
`clone_summary.preserve_splits`	boolean	No	Whether source split memberships were preserved.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.
`404`	The source dataset is missing or hidden by access rules.

sample_ids and sample_query are mutually exclusive. Omitting both selects all source samples; an empty matching query creates an empty clone.
sample_query accepts only split, search, and filters. The server evaluates those values against the current source at submission, and clone_summary is the authoritative result.
preserve_splits copies overlapping memberships exactly. Set it to false to leave the clone unassigned and without copied split-lock, seed, or strategy metadata.

# Clone the source dataset using its current filtered selection.
# sample_ids and sample_query are alternatives; never send both.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/clone/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"approved-training-copy",
    "description":"Private clone created from an approved training selection",
    "sample_query":{
      "split":"training",
      "search":"",
      "filters":{
        "field":"label_value",
        "label":"review_status",
        "cmp":"eq",
        "value":"approved"
      }
    },
    "preserve_splits":true
  }'

# For an explicit bounded selection, replace sample_query with sample_ids.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/clone/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"explicit-sample-copy",
    "sample_ids":["'$SAMPLE_ID'"],
    "preserve_splits":false
  }'

GET/datasets/local-file-references/capabilities/Read local file reference capabilitiesWorkflow helper

Returns whether no-copy local file reference registration is enabled and which operator-configured roots are available to the current backend environment.

AuthApi-Key API keyCoverageWorkflow helper

Response fields

Name	Type	Required	Description
`enabled`	boolean	No	Whether local file references are enabled on the backend.
`roots`	array \| object	No	Configured local file roots and metadata when enabled.
`strict_metadata`	boolean	No	Whether strict local metadata validation is enabled.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

This endpoint does not register files by itself. It only describes server-side local-reference capability.

curl "$MODASTERA_API_BASE_URL/datasets/local-file-references/capabilities/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

POST/datasets/datasets/{dataset_id}/register-local-files/Register local file referencesWorkflow helper

Registers image, NIfTI, or DICOM samples from an operator-allowlisted backend path without copying file bytes.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset receiving local references.

Request body

Name	Type	Required	Description
`body.root`	string	Yes	Configured backend local root name.
`body.path`	string	Yes	Root-relative file or directory path.
`body.recursive`	boolean	No	Walk directories recursively.
`body.data_type`	auto \| image \| nifti \| dicom	No	Sample type detection mode.
`body.split`	training \| validation \| test	No	Optional split assignment.
`body.classification_label`	string	No	Optional classification label.
`body.classification_value`	any	No	Optional classification value.
`body.label_from_parent_dir`	boolean	No	Derive classification values from parent folders.
`body.annotations_by_path`	object	No	Per-file annotations keyed by path or basename.
`body.dry_run`	boolean	No	Preview matches without creating samples.
`body.limit`	integer	No	Maximum files to register.

Response fields

Name	Type	Required	Description
`registration`	object	No	Matched paths, created/existing counts, skipped files, and dry-run metadata.

Status codes

Code	Meaning
`200`	Registration or dry-run completed.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

Available only when a workspace operator has enabled local registration. Use only an approved root and preview with dry_run before creating samples.

curl "$MODASTERA_API_BASE_URL/datasets/local-file-references/capabilities/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/datasets/samples/List samplesCovered

Lists samples visible through dataset access rules. Use filters to scope the response before downloading content.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.dataset`	uuid	No	Filter samples belonging to one dataset.
`query.data_type`	string	No	Filter by sample type.
`query.tags`	uuid[]	No	Filter by tag ids.
`query.page`	integer	No	Page number for paginated sample responses.
`query.page_size`	integer	No	Maximum samples per page.

Response fields

Name	Type	Required	Description
`results`	array	No	Sample rows when pagination is active.
`id`	uuid	No	Sample id for detail, runtime, content, or annotation calls.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

POST/datasets/samples/Upload a sampleCovered

Uploads one file into a dataset using multipart form data.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`form.dataset`	uuid	Yes	Target dataset id.
`form.file`	file	Yes	Sample file to attach.
`form.split`	training \| validation \| test	No	Optional split assignment.
`form.metadata`	JSON string	No	Optional import metadata.
`form.classification_label`	string	No	Optional label field for classification datasets.
`form.classification_value`	string	No	Optional label value for the uploaded sample.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Sample id returned by the backend.
`dataset`	uuid	No	Dataset id the sample belongs to.
`split`	string	No	Persisted split assignment.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

# Dataset list, detail, update, and delete.
curl "$MODASTERA_API_BASE_URL/datasets/datasets/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"
curl -X PATCH "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Updated from a server-side client"}'

# Upload and inspect samples.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/samples/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "split=validation" \
  -F "metadata={\"source\":\"headless-import\"}" \
  -F "file=@./sample.png"

curl "$MODASTERA_API_BASE_URL/datasets/samples/?dataset=$DATASET_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Query samples and create reproducible splits.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/sample-query/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"split":"training","page":1,"page_size":50,"include_ids":true}'

curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/create-random-splits/?response=compact" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset":"'$DATASET_ID'","training":0.7,"validation":0.2,"test":0.1,"splits_seed":42,"lock_splits":true}'

# Generate an annotation export. The response is dataset JSON with output_annotations_file updated.
curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/download-annotations/?file_format=csv" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/datasets/samples/{sample_id}/Read sample detailCovered

Reads sample metadata, annotations, file references, and dataset relationships.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.sample_id`	uuid	Yes	Sample to read.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Sample id.
`annotations`	array \| object	No	Sample annotation payload when present.
`file`	file field	No	Stored sample file reference.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

PATCH/datasets/samples/{sample_id}/Update sample metadataCovered

Partially updates sample metadata, annotations, tags, or dataset assignment fields.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.sample_id`	uuid	Yes	Sample to update.

Request body

Name	Type	Required	Description
`body.name`	string	No	Updated sample name.
`body.annotations`	array \| object	No	Updated annotation payload.
`body.tags`	uuid[]	No	Tag ids to associate.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Updated sample id.

Status codes

Code	Meaning
`200`	Resource was updated and the updated representation was returned.
`400`	Patch body failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to update the object.
`404`	The object is missing or hidden by permissions.

DELETE/datasets/samples/{sample_id}/Delete a sampleCovered

Deletes a sample when permitted by dataset access rules.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.sample_id`	uuid	Yes	Sample to delete.

Response fields

Name	Type	Required	Description
`empty`	none	No	Successful deletes return no response body.

Status codes

Code	Meaning
`204`	Resource was deleted.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to delete the object.
`404`	The object is missing or hidden by permissions.

GET/datasets/samples/{sample_id}/content/Read sample file contentWorkflow helper

Returns backend content for the stored sample file using the configured runtime media transport.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.sample_id`	uuid	Yes	Sample whose content should be read.

Response fields

Name	Type	Required	Description
`content`	file response \| signed URL payload	No	File content or a runtime content reference.

Status codes

Code	Meaning
`200`	Returns a file response or download metadata for the requested artifact.
`401`	API key is missing, inactive, expired, or malformed.
`404`	The file, export job, or source object is missing or hidden by permissions.

GET/datasets/samples/{sample_id}/runtime/Read sample runtime metadataWorkflow helper

Returns a runtime-friendly sample representation for ML service handoff.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.sample_id`	uuid	Yes	Sample to serialize for runtime use.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Sample id.
`runtime_media`	object	No	Runtime media references for the sample.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

POST/datasets/samples/runtime-manifest/Create sample runtime manifestWorkflow helper

Creates a runtime manifest for a bounded list of samples and requested media transport.

AuthApi-Key API keyCoverageWorkflow helper

Request body

Name	Type	Required	Description
`body.sample_ids`	uuid[]	Yes	Samples to include in the manifest.
`body.transport`	string	Yes	Runtime media transport mode requested by the client.

Response fields

Name	Type	Required	Description
`samples`	array	No	Runtime sample manifest entries.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

# Read sample metadata, content, and runtime payloads.
curl "$MODASTERA_API_BASE_URL/datasets/samples/$SAMPLE_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/datasets/samples/$SAMPLE_ID/runtime/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/datasets/samples/runtime-manifest/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sample_ids":["'$SAMPLE_ID'"],"transport":"ml_backend_content_url"}'

curl -X POST "$MODASTERA_API_BASE_URL/datasets/samples/$SAMPLE_ID/add-annotations/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"annotations":[{"label":"positive","type":"classification","value":"yes"}]}'

POST/datasets/samples/{sample_id}/add-annotations/Add sample annotationsCovered

Adds annotations to one sample without replacing the whole sample resource.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.sample_id`	uuid	Yes	Sample to annotate.

Request body

Name	Type	Required	Description
`body.annotations`	array \| object	Yes	Annotation payload to merge into the sample.

Response fields

Name	Type	Required	Description
`annotations`	array \| object	No	Updated sample annotations.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

GET/datasets/summary/Read dataset summariesCovered

Returns dashboard-ready dataset counts, split distribution, labels, sample types, and timestamps.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.archived`	True \| False	No	Filter archived datasets using the backend’s case-sensitive query values.
`query.view`	list \| settings	No	Use list to request the lightweight list serializer. Cursor pagination is available only for this view.
`query.page_size`	integer	No	Opt into cursor pagination for view=list. Defaults to 20 and is capped at 100.
`query.cursor`	opaque string	No	Opaque cursor returned inside a next or previous URL.
`query.sample_data_type`	string	No	Optional sample data-type filter. data_type is accepted as an alias.
`query.exclude_id`	uuid	No	Exclude one dataset id from the result.

Response fields

Name	Type	Required	Description
`legacy array`	array	No	Returned when page_size and cursor are omitted, including non-list views.
`next`	string \| null	No	Opaque absolute URL for the next cursor page when pagination is active.
`previous`	string \| null	No	Opaque absolute URL for the previous cursor page when pagination is active.
`results`	array	No	Dataset list rows when cursor pagination is active.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.
`404`	The supplied cursor is invalid, malformed, or no longer accepted.

Cursor pagination is opt-in and applies only to view=list. Omit page_size and cursor to retain the legacy raw-array response.
Rows use the fixed order -created, -id. Follow next or previous exactly with the same API key; do not decode, edit, or construct cursor values.

# Page-number pagination remains endpoint-specific.
curl "$MODASTERA_API_BASE_URL/datasets/samples/?dataset=$DATASET_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/experiments/$EXPERIMENT_ID/artifacts/?include_payload=0" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/resources/all-usage/?deployment=$DEPLOYMENT_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Cursor pagination is opt-in for these compact lists.
curl "$MODASTERA_API_BASE_URL/datasets/summary/?view=list&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/task-queries-synopsis/?page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Follow the returned next or previous URL exactly with the same API key.
# Do not decode, edit, or construct the cursor yourself.
NEXT_URL="<opaque next URL returned by the response>"
curl "$NEXT_URL" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/datasets/datasets/{dataset_id}/analysis/Read dataset analysisCovered

Returns analysis and visualization-ready distribution data for one dataset.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset to analyze.
`query.refresh`	boolean	No	Request recomputation when the backend supports it.

Response fields

Name	Type	Required	Description
`analysis`	object	No	Dataset analysis payload, including distribution blocks where available.
`status`	string	No	Analysis status or pending state for asynchronous computation.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/datasets/datasets/{dataset_id}/verification-summary/Read dataset verification summaryWorkflow helper

Returns database-derived sample, annotation-label, and split counts for one dataset. Use it before training to verify ingestion and split state.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset to verify.

Response fields

Name	Type	Required	Description
`total_samples`	integer	No	Total dataset sample count.
`annotated_samples`	integer	No	Samples containing annotations.
`storage_kind_counts`	object	No	Counts by storage mode.
`data_type_counts`	object	No	Counts by sample data type.
`split_counts`	object	No	Training, validation, test, and unassigned split counts.
`classification`	object	No	Classification annotation, sample, label, and value counts.
`split_classification`	object	No	Classification distribution for each split.
`analysis`	object	No	Current dataset analysis state.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/verification-summary/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

POST/datasets/datasets/{dataset_id}/analysis/run/Start dataset analysisWorkflow helper

Starts or refreshes dataset analysis and distribution computation for an accessible dataset.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset to analyze.

Response fields

Name	Type	Required	Description
`started`	boolean	No	Whether this request scheduled a new analysis run.
`already_running`	boolean	No	Whether analysis was already in progress.
`analysis_status`	pending \| computing \| completed \| failed	No	Overall analysis state.
`distribution_status`	string	No	Distribution computation state.
`explanation_status`	string	No	Explanation generation state.
`summary`	object	No	Compact sample, coverage, label, and class summary.

Status codes

Code	Meaning
`200`	Analysis was already running and its current state was returned.
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.
`404`	Dataset is missing.
`500`	Analysis could not be scheduled.

curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/verification-summary/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/datasets/datasets/{dataset_id}/samples-names/List sample namesWorkflow helper

Returns sample names for one dataset, useful for mapping annotations or import reports back to source files.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset whose sample names should be returned.

Response fields

Name	Type	Required	Description
`sample_names`	array	No	Sample names or name-like rows returned by the backend.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

POST/datasets/datasets/{dataset_id}/sample-query/Query dataset samplesCovered

Filters samples in a dataset and can return sample ids for downstream split or inspection workflows.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset to query.

Request body

Name	Type	Required	Description
`body.split`	all \| training \| validation \| test	No	Optional split filter.
`body.search`	string	No	Name search string.
`body.filters`	object	No	Structured sample or annotation filters.
`body.page`	integer	No	Page number for this sample query response.
`body.page_size`	integer	No	Maximum samples to return.
`body.include_ids`	boolean	No	Include sample_ids when the matching set is below the backend limit.

Response fields

Name	Type	Required	Description
`results`	array	No	Sample rows matching the query.
`sample_ids`	uuid[]	No	Optional matching ids when include_ids is true.
`count`	integer	No	Total matching samples.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

POST/datasets/datasets/create-random-splits/Create reproducible splitsCovered

Assigns samples to training, validation, and test splits using ratios and an optional seed. Existing assignments remain fixed unless append-only rebalance is requested.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.response`	compact \| full	No	Use compact to reduce response payload size.

Request body

Name	Type	Required	Description
`body.dataset`	uuid	Yes	Dataset to split.
`body.training`	number	Yes	Training ratio.
`body.validation`	number	Yes	Validation ratio.
`body.test`	number	Yes	Test ratio.
`body.splits_seed`	integer	No	Seed for repeatable assignments.
`body.seed`	integer	No	Alias for splits_seed.
`body.stratified`	boolean	No	Use stratified assignment when possible; defaults to true.
`body.lock_splits`	boolean	No	Prevent accidental split changes when supported.
`body.rebalance_existing`	boolean	No	Append new unassigned samples toward the requested ratios without moving existing assignments.

Response fields

Name	Type	Required	Description
`split_counts`	object	No	Resulting counts for each split in compact responses.
`split_ratios`	object	No	Original and normalized ratios plus rebalance_existing.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.
`409`	Requested append/rebalance conflicts with existing assignments, split locks, or available unassigned samples.

Rebalance is append-only: existing assignments never move, validation and test only grow, and a locked test split cannot receive new test samples.

# Append newly added samples without moving existing assignments.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/create-random-splits/?response=compact" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset":"'$DATASET_ID'",
    "training":0.7,
    "validation":0.15,
    "test":0.15,
    "seed":42,
    "stratified":true,
    "rebalance_existing":true
  }'

POST/datasets/datasets/{dataset_id}/add-samples/Add existing samplesCovered

Adds existing sample ids to a dataset and can assign split or classification metadata while adding them.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset receiving samples.

Request body

Name	Type	Required	Description
`body.sample_ids`	uuid[]	No	Existing sample ids to add.
`body.add_all`	boolean	No	Add all samples from a query context when supported.
`body.split`	training \| validation \| test	No	Optional split assignment.

Response fields

Name	Type	Required	Description
`added_count`	integer	No	Number of samples added.
`skipped_existing_count`	integer	No	Samples already present in the dataset.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

POST/datasets/datasets/merge/Merge datasetsCovered

Creates a new dataset by merging accessible source datasets.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`body.source_dataset_ids`	uuid[]	Yes	Datasets to merge.
`body.name`	string	Yes	Name for the merged dataset.
`body.description`	string	No	Optional merged dataset description.
`body.preserve_splits`	boolean	No	Keep existing split assignments where possible.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Merged dataset id.
`merge_summary`	object	No	Source ids, sample count, skipped duplicates, and split behavior.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

POST/datasets/datasets/{dataset_id}/upload-csv/Upload tabular CSVCovered

Starts CSV processing for a tabular dataset and returns a task id for progress polling.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset receiving rows from the CSV.

Request body

Name	Type	Required	Description
`form.file`	file	Yes	CSV file to process.
`form.split`	training \| validation \| test	No	Optional split assignment for created row samples.
`form.classification_label`	string	No	Optional label column.

Response fields

Name	Type	Required	Description
`task_id`	string	No	Progress handle for csv-upload-progress.
`message`	string	No	Import start message.

Status codes

Code	Meaning
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.

# Upload a CSV into an existing tabular dataset and poll progress.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/upload-csv/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "split=training" \
  -F "classification_label=label" \
  -F "file=@./training.csv"

curl "$MODASTERA_API_BASE_URL/datasets/datasets/$DATASET_ID/csv-upload-progress/$JOB_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Merge accessible datasets into a new dataset.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/merge/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_dataset_ids":["dataset_id_1","dataset_id_2"],"name":"merged-training-set","preserve_splits":true}'

# Import deployment execution rows into a dataset workflow.
curl "$MODASTERA_API_BASE_URL/datasets/datasets/deployment-executions-preview/?deployment=$DEPLOYMENT_ID&page=1" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/datasets/datasets/from-deployment-executions/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment":"'$DEPLOYMENT_ID'","add_all":true,"split":"training"}'

curl "$MODASTERA_API_BASE_URL/datasets/datasets/deployment-execution-imports/$IMPORT_JOB_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/datasets/datasets/{dataset_id}/csv-upload-progress/{task_id}/Poll CSV upload progressCovered

Reads progress for a CSV processing task started by upload-csv.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset receiving CSV rows.
`path.task_id`	string	Yes	Task id returned by upload-csv.

Response fields

Name	Type	Required	Description
`status`	processing \| completed \| error	No	CSV processing state.
`progress`	integer	No	Percent complete.
`processed_rows`	integer	No	Rows processed so far.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/datasets/datasets/deployment-executions-preview/Preview deployment executionsWorkflow helper

Previews deployment usage rows before importing them into a dataset.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`query.deployment`	uuid	Yes	Deployment whose executions should be previewed.
`query.statuses`	string	No	Comma-separated execution statuses to include.
`query.page`	integer	No	Page number for preview rows.

Response fields

Name	Type	Required	Description
`results`	array	No	Execution preview rows.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

POST/datasets/datasets/from-deployment-executions/Create dataset from executionsWorkflow helper

Creates a dataset and starts an import job from selected deployment executions.

AuthApi-Key API keyCoverageWorkflow helper

Request body

Name	Type	Required	Description
`body.deployment`	uuid	Yes	Deployment source.
`body.execution_ids`	uuid[]	No	Selected execution ids unless add_all is true.
`body.add_all`	boolean	No	Import all matching executions.
`body.split`	training \| validation \| test	No	Optional split assignment.

Response fields

Name	Type	Required	Description
`job_id`	uuid	No	Import job id for status polling.

Status codes

Code	Meaning
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.

POST/datasets/datasets/{dataset_id}/add-deployment-executions/Add executions to datasetWorkflow helper

Starts an import job that adds selected deployment executions to an existing dataset.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset receiving execution samples.

Request body

Name	Type	Required	Description
`body.deployment`	uuid	Yes	Deployment source.
`body.execution_ids`	uuid[]	No	Selected execution ids unless add_all is true.
`body.add_all`	boolean	No	Import all matching executions.

Response fields

Name	Type	Required	Description
`job_id`	uuid	No	Import job id for status polling.

Status codes

Code	Meaning
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.

GET/datasets/datasets/deployment-execution-imports/{job_id}/Poll execution importWorkflow helper

Reads status for a dataset import job created from deployment executions.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.job_id`	uuid	Yes	Import job id.

Response fields

Name	Type	Required	Description
`status`	string	No	Import job status.
`dataset`	uuid	No	Target dataset id.
`imported_count`	integer	No	Imported execution count when available.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/datasets/datasets/{dataset_id}/download-annotations/Generate annotation exportCovered

Regenerates the dataset output annotation file in CSV or JSON format and returns the updated dataset serializer.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset whose annotations should be exported.
`query.file_format`	csv \| json	No	Annotation export format. Defaults to csv.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Dataset id.
`output_annotations_file`	file field	No	Updated annotation export file reference.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

This endpoint returns dataset JSON, not the raw annotation file bytes. Read the returned file reference to download the generated export.

GET/datasets/annotations-files/List annotation filesCovered

Lists annotation-file metadata visible through dataset access rules.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.dataset`	uuid	No	Filter annotation files by dataset.
`query.page`	integer	No	Page number for paginated responses.

Response fields

Name	Type	Required	Description
`results`	array	No	Annotation file rows.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

POST/datasets/annotations-files/Upload annotation fileCovered

Uploads CSV, platform JSON, or COCO JSON and applies annotations to existing dataset samples by name.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`form.dataset`	uuid	Yes	Dataset whose samples should be annotated.
`form.file`	file	Yes	Annotation file.
`form.file_format`	csv \| json \| coco	No	Annotation format. Defaults to csv.
`form.split`	training \| validation \| test	No	Optional split assignment for matched samples.
`form.sample_name`	string	No	Required CSV column containing sample filenames.
`form.label_fields`	JSON string[]	No	Required CSV label columns.
`form.labels_type`	JSON object	No	Optional CSV label type mapping.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Annotation file id.
`import_result`	object	No	COCO image matches, annotation counts, skipped duplicates, updated samples, and added labels.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

COCO imports are atomic and retry-safe. CSV-only mapping fields are rejected for JSON and COCO uploads.

# Import COCO JSON and apply matching annotations by image filename.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/annotations-files/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "file_format=coco" \
  -F "split=training" \
  -F "file=@./annotations.coco.json"

# Upload binary masks asynchronously. Repeat the masks field for each file.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/$DATASET_ID/upload-masks/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "masks=@./sample-001.png" \
  -F "masks=@./sample-002.png" \
  -F "label=lesion" \
  -F "split=training" \
  -F "async=true"

# Color-map masks use hex colors mapped to label names.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/$DATASET_ID/upload-masks/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "masks=@./sample-003.png" \
  -F "mask_mode=color_map" \
  -F 'color_label_map={"#ff0000":"tumor","#00ff00":"stroma"}' \
  -F 'background_colors=["#000000"]' \
  -F "async=true"

curl "$MODASTERA_API_BASE_URL/datasets/$DATASET_ID/mask-upload-progress/$JOB_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/datasets/annotations-files/{annotation_file_id}/Read annotation fileCovered

Reads one annotation-file resource and its metadata.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.annotation_file_id`	uuid	Yes	Annotation file to read.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Annotation file id.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

PATCH/datasets/annotations-files/{annotation_file_id}/Replace and re-import annotation fileCovered

Replaces the stored annotation file and applies CSV, platform JSON, or COCO annotations using the same format rules as creation.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.annotation_file_id`	uuid	Yes	Annotation file to update.

Request body

Name	Type	Required	Description
`form.file`	file	Yes	Replacement annotation file.
`form.dataset`	uuid	No	Dataset association; defaults to the existing dataset.
`form.file_format`	csv \| json \| coco	No	Replacement annotation format.
`form.split`	training \| validation \| test	No	Optional split assignment.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Updated annotation file id.
`import_result`	object	No	COCO import result when applicable.

Status codes

Code	Meaning
`200`	Resource was updated and the updated representation was returned.
`400`	Patch body failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to update the object.
`404`	The object is missing or hidden by permissions.

DELETE/datasets/annotations-files/{annotation_file_id}/Delete annotation fileCovered

Deletes an annotation-file resource when permitted.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.annotation_file_id`	uuid	Yes	Annotation file to delete.

Response fields

Name	Type	Required	Description
`empty`	none	No	Successful deletes return no response body.

Status codes

Code	Meaning
`204`	Resource was deleted.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to delete the object.
`404`	The object is missing or hidden by permissions.

POST/datasets/{dataset_id}/upload-masks/Upload mask annotationsWorkflow helper

Uploads binary or color-mapped masks whose filenames match existing samples, then converts foreground regions into polygon annotations.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset receiving masks.

Request body

Name	Type	Required	Description
`form.masks`	file[]	Yes	One or more mask files; repeat this multipart field.
`form.split`	none \| training \| validation \| test	No	Optional split assignment.
`form.label`	string	No	Required annotation label for binary masks.
`form.mask_mode`	color_map	No	Use color_map for multiclass masks.
`form.color_label_map`	JSON object	No	Required hex-color to label mapping in color_map mode.
`form.background_colors`	JSON string[]	No	Colors ignored as background in color_map mode.
`form.async`	boolean	No	Start background processing when true.

Response fields

Name	Type	Required	Description
`task_id`	string	No	Progress handle for asynchronous processing.
`processed_files`	integer	No	Synchronous processing count.
`matched_files`	integer	No	Masks matched to samples.
`skipped_files`	integer	No	Masks skipped because no sample matched.

Status codes

Code	Meaning
`200`	Masks were processed synchronously.
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.

# Import COCO JSON and apply matching annotations by image filename.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/annotations-files/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "file_format=coco" \
  -F "split=training" \
  -F "file=@./annotations.coco.json"

# Upload binary masks asynchronously. Repeat the masks field for each file.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/$DATASET_ID/upload-masks/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "masks=@./sample-001.png" \
  -F "masks=@./sample-002.png" \
  -F "label=lesion" \
  -F "split=training" \
  -F "async=true"

# Color-map masks use hex colors mapped to label names.
curl -X POST "$MODASTERA_API_BASE_URL/datasets/$DATASET_ID/upload-masks/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "masks=@./sample-003.png" \
  -F "mask_mode=color_map" \
  -F 'color_label_map={"#ff0000":"tumor","#00ff00":"stroma"}' \
  -F 'background_colors=["#000000"]' \
  -F "async=true"

curl "$MODASTERA_API_BASE_URL/datasets/$DATASET_ID/mask-upload-progress/$JOB_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/datasets/datasets/{dataset_id}/annotation-engine/Read annotation engine readinessWorkflow helper

Reads the cached assisted-annotation engine state for an accessible dataset without contacting the GPU service.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset whose assisted-annotation access is being checked.

Response fields

Name	Type	Required	Description
`state`	unknown \| starting \| ready \| unavailable	No	Current cached engine state.
`reason`	string \| null	No	Sanitized unavailability reason when known.
`estimated_ready_seconds`	integer \| null	No	Estimated startup time when available.
`retry_after_seconds`	integer	No	Suggested delay before the next readiness check.
`retryable`	boolean	No	Whether another warm-up or status attempt can be made.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

This reports readiness for assisted annotation; it does not start Auto Annotate or return job progress.

POST/datasets/datasets/{dataset_id}/annotation-engine/Start annotation engine warm-upWorkflow helper

Starts one process-safe assisted-annotation engine warm-up, or joins the currently running warm-up.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Accessible dataset used to authorize the warm-up request.

Response fields

Name	Type	Required	Description
`state`	starting \| ready \| unavailable	No	Warm-up state after accepting or joining the request.
`reason`	string \| null	No	Sanitized reason when startup is unavailable.
`retry_after_seconds`	integer	No	Suggested status-poll interval.
`retryable`	boolean	No	Whether a later attempt is supported.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

GET/datasets/auto-annotate/{job_id}/status/Read Auto Annotate progressWorkflow helper

Returns the durable public progress snapshot for an Auto Annotate job after verifying access to its dataset.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.job_id`	uuid	Yes	Auto Annotate job id returned by the start request.

Response fields

Name	Type	Required	Description
`job_id`	uuid	No	Auto Annotate job id.
`status`	accepted \| running \| completed \| error	No	Durable job status.
`phase`	string	No	Current processing phase.
`message`	string	No	Safe progress or failure message.
`progress`	object	No	Processed, total, and percent values.
`updated_at`	datetime	No	Time of the latest stored progress event.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

GET/datasets/{dataset_id}/mask-upload-progress/{task_id}/Poll mask upload progressWorkflow helper

Reads progress for a mask upload task.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.dataset_id`	uuid	Yes	Dataset receiving masks.
`path.task_id`	string	Yes	Mask upload task id.

Response fields

Name	Type	Required	Description
`status`	string	No	Mask upload status payload.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

API Reference

Pipelines API reference#

response_status is the planning/config-generation state: pending, running, completed, or error.
task_status is the durable run state: not_started, in_progress, completed, failed, or interrupted; interrupting can appear during cancellation.
Task-run requests use task_query_id, not task_query.
Use dataset_id and instruction when creating pipelines; prompt and dataset are not accepted create fields.
Clients explicitly select an ML backend profile only when creating a pipeline. Clones, fine-tunes, reruns, and later model versions automatically retain the applicable pinned source profile.
The public segmentation catalog includes EoMT DINOv2 panoptic variants plus RF-DETR Segmentation and RTMDet-Ins instance variants. A public or available catalog entry is discovery metadata, not a guarantee that every selected ML backend can execute it; verify task-scoped alternatives, the planned runtime contract, and backend support before running.
REST polling through task-progress and task-query detail is the durable integration surface even when WebSocket updates are available.
Architecture swaps are available only before a pipeline’s first run and are blocked while planning or execution is active. Clone a pipeline that has already run before changing its architecture.
Runtime contract, failure details, and run summary endpoints are read-only helpers for readiness checks and post-run verification.
Model-card report generation returns JSON; GET can return JSON with response=json or markdown by default, and streaming generation uses server-sent events.

# Discover the ML backends available to this API-key user.
curl "$MODASTERA_API_BASE_URL/users/ml-backend-profiles/available/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Select a profile only when creating the pipeline. Omit it for default routing.
# Clones, fine-tunes, and later model versions inherit their pinned source profile.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"profile-routed-training",
    "instruction":"Train and evaluate an image classifier",
    "dataset_id":"'$DATASET_ID'",
    "ml_backend_profile_id":"'$ML_BACKEND_PROFILE_ID'"
  }'

GET/users/ml-backend-profiles/available/List available ML backend profilesWorkflow helper

Returns execution profiles available to the API-key user without exposing profile credentials or management fields.

AuthApi-Key API keyCoverageWorkflow helper

Response fields

Name	Type	Required	Description
`count`	integer	No	Number of profiles available to the user.
`default_profile_id`	uuid \| null	No	Backend default profile.
`selected_profile_id`	uuid \| null	No	Profile used when pipeline creation omits an explicit choice.
`has_multiple_choices`	boolean	No	Whether the client should present profile selection.
`profiles`	array	No	Available ids, names, selected/default state, and local-file capability.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

This is operational discovery, not profile management. Profile base URLs and credentials are never returned.

# Discover the ML backends available to this API-key user.
curl "$MODASTERA_API_BASE_URL/users/ml-backend-profiles/available/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Select a profile only when creating the pipeline. Omit it for default routing.
# Clones, fine-tunes, and later model versions inherit their pinned source profile.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"profile-routed-training",
    "instruction":"Train and evaluate an image classifier",
    "dataset_id":"'$DATASET_ID'",
    "ml_backend_profile_id":"'$ML_BACKEND_PROFILE_ID'"
  }'

GET/agents/architecture-knowledgebase/List architecture catalogWorkflow helper

Lists supported architecture knowledgebase models and optional details for pipeline planning and architecture swap workflows, including public segmentation catalog variants when they are discoverable.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`query.category`	string	No	Optional architecture category filter.
`query.module_family`	string	No	Optional module family filter.
`query.search`	string	No	Optional search text.
`query.include_details`	boolean	No	Include detailed model metadata when true.

Response fields

Name	Type	Required	Description
`categories`	array \| object	No	Catalog categories when returned.
`models`	array	No	Architecture rows with model keys, task metadata, details, and capability metadata when returned.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

Catalog capability is necessary discovery metadata but does not probe every selected ML backend. Confirm backend support before planning or running an explicitly selected model.

# Browse the architecture catalog used by pipeline config tools.
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/?include_details=true" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Inspect one public segmentation catalog entry. Catalog discovery is not a
# guarantee that every selected ML backend can execute the model.
SEGMENTATION_MODEL_KEY="EoMTDINOv2Small640"
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/$SEGMENTATION_MODEL_KEY/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# After planning, use the task-scoped related list as the replacement set.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-knowledgebase/?resource_id=$RESOURCE_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Swap only a not-started pipeline and only after verifying task and runtime support.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-swap/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_id":"'$RESOURCE_ID'","target_model_key":"'$SEGMENTATION_MODEL_KEY'","override_params":{}}'

GET/agents/architecture-knowledgebase/{model_key}/Read architecture catalog detailWorkflow helper

Returns detailed metadata for one supported architecture model key.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.model_key`	string	Yes	Architecture catalog model key.

Response fields

Name	Type	Required	Description
`model`	object	No	Architecture metadata and configurable parameters.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

For segmentation families, treat the exact returned model_key as the integration value. Do not derive it from the display name or lower-level module metadata.

GET/agents/task-queries/List task queriesCovered

Lists training/evaluation workflow task queries visible to the API-key owner.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.archived`	boolean	No	Filter archived task queries.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Task query id used for definition, run, progress, and output endpoints.
`task_status`	string	No	Execution status such as not_started, in_progress, completed, failed, or interrupted.
`response_status`	string	No	Planning or response status such as pending, running, completed, or error.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

This endpoint currently returns a plain array, not a paginated envelope.

POST/agents/task-queries/Create a task queryCovered

Creates a workflow request for training and evaluation. The returned task query id is the durable handle for planning, execution, results, and deployment handoff.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`body.name`	string	Yes	Workflow name.
`body.instruction`	string	No	Instruction for the training/evaluation workflow.
`body.dataset_id`	uuid	No	Accessible, non-archived dataset to bind as a resource.
`body.ml_backend_profile_id`	uuid	No	Available ML backend profile for this new pipeline. Later derived work inherits a pinned profile automatically.
`body.run_preferences`	object	No	Optional image explainability and run preferences. Omit an architecture preference for automatic model selection; pin only an exact catalog model key whose task and selected backend support have been verified.
`body.preparation_reuse_policy`	reuse_if_unchanged \| always_reprepare	No	Dataset preparation reuse policy.
`body.resources`	array	No	Explicit workflow resources such as a dataset reference.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Save as TASK_QUERY_ID.
`response_status`	pending \| running \| completed \| error	No	Planning/config-generation status. New records commonly start pending.
`task_status`	not_started \| in_progress \| completed \| failed \| interrupted	No	Training/evaluation run status.
`ml_backend_profile`	object \| null	No	Selected execution profile summary.
`dataset_preparation`	object	No	Preparation source/adopted dataset, status, plan, artifacts, fingerprints, and reuse policy.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

# Create a pipeline record. Save the returned id as TASK_QUERY_ID.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"headless-training-run",
    "instruction":"Train and evaluate an image classifier",
    "dataset_id":"'$DATASET_ID'"
  }'

# Generate or refresh the pipeline definition.
curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Train an image classification model and evaluate it on the validation split."}'

# Optional live planning channels. URL-encode the raw key first.
ENCODED_API_KEY=$(python3 -c 'import os, urllib.parse; print(urllib.parse.quote(os.environ["MODASTERA_API_KEY"], safe=""))')
printf "%s\n" "$MODASTERA_WS_BASE_URL/ws/task-status/$TASK_QUERY_ID/?api_key=$ENCODED_API_KEY"
printf "%s\n" "$MODASTERA_WS_BASE_URL/ws/task-response/$TASK_QUERY_ID/?api_key=$ENCODED_API_KEY"

# Durable readiness check. Wait for response_status=completed before running.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Inspect/edit the generated definition when deterministic control is needed.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/definition/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/definition/tasks/$TASK_INDEX/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions":"Keep the evaluation split unchanged."}'

GET/agents/task-queries/{task_query_id}/Read task queryCovered

Reads one task query with its current planning, generated definition, execution state, and latest runtime result.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to read.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Task query id.
`response_status`	pending \| running \| completed \| error	No	Planning/config-generation status.
`response_data.tasks`	array	No	Generated executable pipeline tasks when planning succeeds.
`task_status`	not_started \| in_progress \| completed \| failed \| interrupted	No	Durable training/evaluation run status.
`task_result`	object	No	Latest normalized runtime result when available.
`dataset_preparation`	object	No	Preparation state and dataset lineage.
`ml_backend_profile`	object \| null	No	Pipeline execution profile summary. Derived pipelines may carry an inherited pinned profile.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

After a WebSocket reconnect, read this endpoint to recover planning, preparation, run, and result state. Generated media URLs in task_result are rewritten to authenticated relay URLs.

POST/agents/task-queries/{task_query_id}/dataset-preparation/Replan dataset preparationWorkflow helper

Forces a fresh dataset preparation plan and applies supported automatic steps before pipeline execution.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Editable task query to reprepare.

Response fields

Name	Type	Required	Description
`dataset_preparation.status`	not_needed \| planned \| running \| completed \| stale \| failed	No	Current preparation state.
`dataset_preparation.source_dataset`	uuid \| null	No	Original pipeline dataset.
`dataset_preparation.adopted_dataset`	uuid \| null	No	Dataset used by the executable pipeline.
`dataset_preparation.plan`	object	No	Decision, supported steps, readiness, and warnings.
`dataset_preparation.artifacts`	object	No	Applied preparation result and readiness metadata.

Status codes

Code	Meaning
`200`	Preparation was replanned and the updated task query was returned.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.
`500`	Dataset preparation failed unexpectedly.

Preparation may create and bind a derived split dataset. Use adopted_dataset for the actual runtime dataset and inspect warnings when status is planned or failed.

# Inspect preparation state returned with the task query.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Force a fresh preparation plan and apply supported automatic steps.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/dataset-preparation/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH/agents/task-queries/{task_query_id}/Update task queryCovered

Partially updates a task query. Updating instruction generates or refreshes the pipeline definition and can return 202 while planning continues in the background.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to update.

Request body

Name	Type	Required	Description
`body.instruction`	string	No	New workflow instruction used for pipeline generation.
`body.run_preferences`	object	No	Optional preferences to apply to task configuration.
`body.preparation_reuse_policy`	reuse_if_unchanged \| always_reprepare	No	Control whether unchanged prepared datasets are reused.
`body.archived`	boolean	No	Archive or unarchive the query.

Response fields

Name	Type	Required	Description
`message`	string	No	Returned when replanning starts asynchronously.
`id`	uuid	No	Returned on ordinary serializer update.
`response_status`	pending \| running \| completed \| error	No	Updated planning state when included.

Status codes

Code	Meaning
`200`	Resource was updated and the updated representation was returned.
`400`	Patch body failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to update the object.
`404`	The object is missing or hidden by permissions.
`202`	Instruction update or replanning was started.

# Create a pipeline record. Save the returned id as TASK_QUERY_ID.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"headless-training-run",
    "instruction":"Train and evaluate an image classifier",
    "dataset_id":"'$DATASET_ID'"
  }'

# Generate or refresh the pipeline definition.
curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Train an image classification model and evaluate it on the validation split."}'

# Optional live planning channels. URL-encode the raw key first.
ENCODED_API_KEY=$(python3 -c 'import os, urllib.parse; print(urllib.parse.quote(os.environ["MODASTERA_API_KEY"], safe=""))')
printf "%s\n" "$MODASTERA_WS_BASE_URL/ws/task-status/$TASK_QUERY_ID/?api_key=$ENCODED_API_KEY"
printf "%s\n" "$MODASTERA_WS_BASE_URL/ws/task-response/$TASK_QUERY_ID/?api_key=$ENCODED_API_KEY"

# Durable readiness check. Wait for response_status=completed before running.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Inspect/edit the generated definition when deterministic control is needed.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/definition/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/definition/tasks/$TASK_INDEX/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions":"Keep the evaluation split unchanged."}'

DELETE/agents/task-queries/{task_query_id}/Delete task queryCovered

Deletes a task query and performs related runtime cleanup before removal.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to delete.

Response fields

Name	Type	Required	Description
`empty`	none	No	Successful deletes return no response body.

Status codes

Code	Meaning
`204`	Resource was deleted.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to delete the object.
`404`	The object is missing or hidden by permissions.

POST/agents/task-queries/{task_query_id}/clone/Clone task queryWorkflow helper

Copies an accessible pipeline into a new editable task query. Use this when a generated or completed pipeline needs config changes that are blocked on the original.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Source task query to clone.

Request body

Name	Type	Required	Description
`body.name`	string	No	Optional clone name.
`body.dataset_id`	uuid	No	Optional replacement dataset binding.
`body.access`	private \| organization \| global	No	Optional access setting for the clone.

Response fields

Name	Type	Required	Description
`id`	uuid	No	New cloned task query id.
`response_status`	string	No	Planning state copied or reset by the clone operation.
`task_status`	string	No	Run state for the cloned task query.
`ml_backend_profile`	object \| null	No	Inherited source execution-profile summary.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

Clone is the preferred path before editing generated config on a pipeline whose current state blocks direct edits.
The backend inherits the latest completed model version’s pinned profile when available, then the source pipeline profile or resolved default. Clients do not pass a replacement profile to this operation.
Cloning is rejected when the inherited source profile is not available to the requesting user.

# Clone a task query into a new editable pipeline.
# The clone automatically inherits the source's pinned ML backend profile.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/clone/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"editable-copy","dataset_id":"'$DATASET_ID'"}'

# Inspect runtime readiness and final summary.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/runtime-contract/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/run-summary/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Read sanitized failure details after failed runs.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/failure-details/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/agents/task-queries/{task_query_id}/definition/Read task definitionCovered

Returns the generated pipeline definition so a headless client can inspect planned resources and stages before execution.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to inspect.

Response fields

Name	Type	Required	Description
`tasks`	array	No	Pipeline task definitions.
`resources`	array	No	Resources referenced by the workflow.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/agents/task-queries/{task_query_id}/config/Read pipeline configWorkflow helper

Returns editable training config and resource config entries for a task query.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to inspect.

Response fields

Name	Type	Required	Description
`training_config`	object	No	Editable training configuration when available.
`resource_configs`	array	No	Editable resource config entries.
`edit_block_reason`	string \| null	No	Reason config edits are blocked, when blocked.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

# Read the editable pipeline config surface.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/config/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Update training config or resource config for the next run or rerun.
curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/config/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"training_epochs":12}'

curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/config/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_updates":[{"task_index":0,"resource_type":"architecture","resource_id":"architecture_resource_id","config_patch":{"input_size":[96,96]}}]}'

PATCH/agents/task-queries/{task_query_id}/config/Update pipeline configWorkflow helper

Updates validated training config or resource config entries for the next pipeline run or rerun.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to update.

Request body

Name	Type	Required	Description
`body.training_config_patch`	object	No	Patch to apply to training config.
`body.training_epochs`	integer	No	Convenience update for training epoch count.
`body.resource_updates`	array	No	Validated resource config updates.

Response fields

Name	Type	Required	Description
`training_config`	object	No	Updated training configuration.
`resource_configs`	array	No	Updated resource config entries.
`warnings`	array	No	Validation warnings when present.

Status codes

Code	Meaning
`200`	Resource was updated and the updated representation was returned.
`400`	Patch body failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to update the object.
`404`	The object is missing or hidden by permissions.
`409`	Config cannot be edited while the pipeline is planning or running.

Use either resource_updates or training_config_patch/training_epochs in one request, not both.

# Read the editable pipeline config surface.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/config/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Update training config or resource config for the next run or rerun.
curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/config/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"training_epochs":12}'

curl -X PATCH "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/config/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_updates":[{"task_index":0,"resource_type":"architecture","resource_id":"architecture_resource_id","config_patch":{"input_size":[96,96]}}]}'

GET/agents/task-queries/{task_query_id}/architecture-knowledgebase/?resource_id=...Read related architecture optionsWorkflow helper

Returns the current architecture resource and related catalog models for a task query resource.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to inspect.
`query.resource_id`	string	Yes	Architecture resource id inside the generated pipeline.

Response fields

Name	Type	Required	Description
`can_swap`	boolean	No	Whether architecture swap is currently allowed.
`current`	object	No	Current architecture resource metadata and config.
`related`	array	No	Related architecture catalog options.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

Treat related as the replacement set for this generated resource, then separately confirm that the selected ML backend can execute the candidate before swapping.

# Browse the architecture catalog used by pipeline config tools.
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/?include_details=true" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Inspect one public segmentation catalog entry. Catalog discovery is not a
# guarantee that every selected ML backend can execute the model.
SEGMENTATION_MODEL_KEY="EoMTDINOv2Small640"
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/$SEGMENTATION_MODEL_KEY/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# After planning, use the task-scoped related list as the replacement set.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-knowledgebase/?resource_id=$RESOURCE_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Swap only a not-started pipeline and only after verifying task and runtime support.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-swap/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_id":"'$RESOURCE_ID'","target_model_key":"'$SEGMENTATION_MODEL_KEY'","override_params":{}}'

POST/agents/task-queries/{task_query_id}/architecture-swap/Swap pipeline architectureWorkflow helper

Swaps one architecture resource to a supported catalog model and returns the updated task query state.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to update.

Request body

Name	Type	Required	Description
`body.resource_id`	string	Yes	Architecture resource id.
`body.target_model_key`	string	Yes	Target catalog model key.
`body.override_params`	object	No	Optional parameter overrides.

Response fields

Name	Type	Required	Description
`task_query`	object	No	Updated task query or pipeline definition payload.

Status codes

Code	Meaning
`200`	Architecture was swapped and the updated pipeline state was returned.
`400`	resource_id, target_model_key, or override_params failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the task query.
`404`	The task query or architecture resource was not found.
`409`	Architecture cannot be swapped in the current state; wait for planning or active work, or clone a pipeline that has already run.

Unknown target_model_key returns 400. Swaps require a matching architecture resource and a not-started pipeline. Clone a pipeline that has already run before changing its architecture, and confirm selected-backend support before starting compute.

# Browse the architecture catalog used by pipeline config tools.
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/?include_details=true" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Inspect one public segmentation catalog entry. Catalog discovery is not a
# guarantee that every selected ML backend can execute the model.
SEGMENTATION_MODEL_KEY="EoMTDINOv2Small640"
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/$SEGMENTATION_MODEL_KEY/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# After planning, use the task-scoped related list as the replacement set.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-knowledgebase/?resource_id=$RESOURCE_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Swap only a not-started pipeline and only after verifying task and runtime support.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-swap/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_id":"'$RESOURCE_ID'","target_model_key":"'$SEGMENTATION_MODEL_KEY'","override_params":{}}'

PATCH/agents/task-queries/{task_query_id}/definition/tasks/{task_index}/Update definition taskWorkflow helper

Narrowly edits one generated task definition before execution.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query containing the definition.
`path.task_index`	integer	Yes	Zero-based task index.

Request body

Name	Type	Required	Description
`body.reasoning`	string	No	Updated reasoning text.
`body.instructions`	string	No	Updated task instructions.
`body.evaluation_criteria`	string	No	Updated evaluation criteria.
`body.resources`	array	No	Replacement task resources.

Response fields

Name	Type	Required	Description
`task_index`	integer	No	Updated task index.
`task`	object	No	Updated task payload.

Status codes

Code	Meaning
`200`	Resource was updated and the updated representation was returned.
`400`	Patch body failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to update the object.
`404`	The object is missing or hidden by permissions.
`409`	Definition cannot be edited while planning or running.

GET/agents/task-queries/{task_query_id}/definition/tasks/{task_index}/metric-options/List metric optionsWorkflow helper

Returns metric options for a model-evaluation task definition.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query containing the definition.
`path.task_index`	integer	Yes	Task index to inspect.

Response fields

Name	Type	Required	Description
`metrics`	array	No	Evaluation metric options.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

Returns 400 if the selected task is not a model-evaluation task.

POST/agents/task-runs/Start a task runCovered

Starts or queues training/evaluation execution for a generated task query. The response indicates whether execution started immediately, queued, or was already running.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`body.task_query_id`	uuid	Yes	Task query to execute.
`body.run_again`	boolean	No	Explicitly request rerun behavior for an existing model version.
`body.resume_latest_checkpoint`	boolean	No	Explicitly request continuation from the latest verified checkpoint.

Response fields

Name	Type	Required	Description
`queued`	boolean	No	Whether execution entered the queue.
`running`	boolean	No	Whether the requested task query was already running.
`queue_position`	integer	No	Queue position when queued.
`task_query`	object	No	Updated task query state.
`websocket_url`	string	No	Task-run WebSocket URL when returned.
`model_version`	object \| null	No	Active model-version id and version number when versioning is enabled.
`resume`	object \| null	No	Checkpoint source and resume metadata when an existing checkpoint is used.
`fresh_retry`	object \| null	No	Explicit from-scratch retry metadata for the narrow failed-first-version case.

Status codes

Code	Meaning
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.
`503`	Checkpoint availability could not be verified because the selected ML backend was unavailable.

Returns 409 when planning is still pending/running, the pipeline has no executable tasks, or a training/evaluation task has no dataset attached.
When exactly one failed model version v1 exists, task status is failed, interrupted, or not_started, no queue entry is active, and checkpoint lookup confirms no checkpoint, the backend reuses v1 from scratch. The accepted response has resume: null and fresh_retry.reason: first_version_missing_checkpoint.
A missing checkpoint for later model versions remains a 409 missing_rerun_checkpoint. Do not interpret fresh_retry: null as a from-scratch retry.
Reruns and later model versions retain their pinned ML backend profile instead of switching silently to the user’s current default.
WebSocket events are live-only and do not replay missed messages; refetch REST state after reconnect.

# Start a task run.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-runs/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_query_id":"'$TASK_QUERY_ID'"}'

# Retry a failed first model version. If checkpoint lookup confirms that v1 has
# no checkpoint, the accepted response has resume=null and a fresh_retry reason.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-runs/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_query_id":"'$TASK_QUERY_ID'","run_again":true}'

# Poll progress and inspect queue state.
curl "$MODASTERA_API_BASE_URL/agents/task-progress/$TASK_QUERY_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/task-queue-status/?task_query_id=$TASK_QUERY_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Interrupt a running job when supported for the task.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-runs/$TASK_QUERY_ID/interrupt/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/agents/task-runs/$TASK_QUERY_ID/interrupt-training/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/agents/task-progress/{task_query_id}/Poll task progressCovered

Reads persisted task status, response status, and latest task_result for a running or completed task query.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query being executed.

Response fields

Name	Type	Required	Description
`task_status`	string	No	Execution status.
`response_status`	string	No	Planning or response status.
`task_result.status.name`	string	No	Runtime status name such as in_progress, completed, failed, or interrupted.
`task_result.metrics`	object	No	Training or evaluation metrics persisted so far.
`task_result.results`	object	No	Runtime results persisted so far.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

import os
import time
import requests

base_url = os.environ["MODASTERA_API_BASE_URL"].rstrip("/")
api_key = os.environ["MODASTERA_API_KEY"]
headers = {"Authorization": f"Api-Key {api_key}", "Accept": "application/json"}

status_url = f"{base_url}/agents/task-progress/{os.environ['TASK_QUERY_ID']}/"
terminal = {"completed", "ended", "failed", "interrupted"}

while True:
    response = requests.get(status_url, headers=headers, timeout=30)
    response.raise_for_status()
    job = response.json()
    if job.get("task_status") in terminal:
        break
    time.sleep(5)

if job.get("task_status") not in {"completed", "ended"}:
    raise RuntimeError(job)
print(job.get("task_result"))

GET/agents/task-queue-status/Inspect queue statusWorkflow helper

Returns global queue state plus queued/running entries for the current user and, when provided, one task query. Use this when task-run start returns queued: true.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`query.task_query_id`	uuid	No	Optional task query to inspect.

Response fields

Name	Type	Required	Description
`queue_status`	object	No	Global queue status payload.
`user_queue_entry`	object	No	Most recent queued or running entry for the requested task.
`user_queued_tasks`	array	No	Current user queued tasks.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

POST/agents/task-runs/{task_query_id}/resume-evaluation/Resume pipeline evaluationWorkflow helper

Queues evaluation-only resume or reconciliation for an eligible checkpointed pipeline without repeating completed training.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Checkpointed pipeline to evaluate.

Request body

Name	Type	Required	Description
`body.model_version_id`	uuid	No	Optional eligible model version to evaluate.

Response fields

Name	Type	Required	Description
`task_query`	object	No	Updated serialized pipeline state.
`websocket_url`	string	No	Live task-run update URL.

Status codes

Code	Meaning
`202`	Evaluation resume was accepted and queued.
`400`	Pipeline or requested model version is not eligible for evaluation-only resume.
`401`	API key is missing or invalid.
`403`	The key owner lacks permission to run the pipeline.
`404`	Pipeline or requested model version was not found.
`409`	Pipeline state conflicts with an evaluation-only resume.

Checkpoint selection is verified server-side. Do not use Run Again when the intended operation is evaluation-only recovery.

POST/agents/task-runs/{task_query_id}/interrupt/Interrupt task runWorkflow helper

Requests a generic interrupt for a running task query.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Running task query to interrupt.

Response fields

Name	Type	Required	Description
`message`	string	No	Interrupt request result.

Status codes

Code	Meaning
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.

POST/agents/task-runs/{task_query_id}/interrupt-training/Interrupt trainingWorkflow helper

Requests interruption for an active training task. Use this for operator controls, not ordinary polling.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Running task query to interrupt.

Response fields

Name	Type	Required	Description
`task_status`	interrupting \| interrupted	No	Next task status while cancellation is in flight or complete.
`message`	string	No	Human-readable interruption result.

Status codes

Code	Meaning
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.

GET/agents/task-queries/{task_query_id}/detail-summary/Read compact pipeline detail summaryWorkflow helper

Returns lightweight pipeline identity, overview, dataset, preparation, collaboration, and result-readiness fields without loading the heavy task result.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to summarize.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Task query id.
`name`	string	No	Pipeline display name.
`response_status`	string	No	Planning/config generation state.
`task_status`	string	No	Durable execution state.
`overview`	object	No	Title, task description, and task count.
`dataset`	object \| null	No	Selected dataset id, name, and format.
`dataset_preparation`	object	No	Preparation status, source/adopted datasets, reason, and latest job id.
`collaborator_count`	integer	No	Number of pipeline collaborators.
`has_results`	boolean	No	Whether a task-result record exists.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

Use /results/ for the current result payload and /definition/ for the complete generated task definition.

GET/agents/task-queries/{task_query_id}/results/Read pipeline resultsCovered

Returns the latest normalized pipeline result for a completed or active task query. For training plus evaluation, this is normally the final evaluation result.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to inspect.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Task query id.
`task_status`	string	No	Durable training/evaluation status.
`task_result.status`	object	No	Final or current runtime status.
`task_result.metrics`	object	No	Metric values generated by training or evaluation.
`task_result.results`	object	No	Result tables, predictions, or evaluation payloads.
`task_result.analysis`	object	No	Analysis payload when available.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

This endpoint is not a replay log of all training events. Intermediate updates arrive over WebSocket and are persisted into the latest task_result.
For binary classification, the compact platform summary shows configured threshold-dependent metrics at the default 0.5 threshold. Validation-selected and test-sample-optimal operating points remain in detailed Result Analysis; threshold-independent metrics must be interpreted separately.
Segmentation result shapes and metric names vary by semantic, instance, or panoptic target and by the executing model family. Interpret the exact completed model version and returned result contract instead of assuming that the families are interchangeable.
Generated detection, segmentation, prediction, Grad-CAM, and explainability media paths are rewritten to authenticated result-media relay URLs.

{
  "id": "task_query_id",
  "task_status": "completed",
  "task_result": {
    "status": { "name": "completed" },
    "metrics": { "accuracy": 0.94 },
    "results": { "confusion_matrix": [[12, 1], [2, 15]] },
    "analysis": { "summary": "Final evaluation metrics" }
  }
}

GET/agents/task-queries/{task_query_id}/result-media/?path=...Stream generated result mediaCovered

Streams generated pipeline media from the ML backend selected for the task query. Clients should follow relay URLs returned by results or WebSocket payloads.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query that owns the generated artifact.
`query.path`	string	Yes	Backend-generated artifact path from a returned relay URL.
`header.Range`	bytes range	No	Optional byte range forwarded to the selected ML backend.

Response fields

Name	Type	Required	Description
`file`	binary stream	No	Generated overlay or prediction media with upstream content metadata.
`Cache-Control`	private, no-store	No	Relay responses are not publicly cacheable.

Status codes

Code	Meaning
`200`	Full media stream.
`206`	Partial media stream for a satisfiable Range request.
`400`	Artifact path is missing, malformed, outside allowed generated-media roots, or owned by another creator.
`401`	API key is missing or invalid.
`404`	Task query or upstream media is unavailable.
`416`	Requested byte range is not satisfiable.
`502`	Selected ML backend rejected or could not serve the media.
`504`	Selected ML backend timed out.

Do not construct artifact paths or call ML backend file URLs directly. Use the relay URL returned by the backend and send the same API key.

# Result payloads contain ready-to-use relay URLs for generated media.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/results/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Follow the returned URL with the same API key. Do not reconstruct its path.
RESULT_MEDIA_URL="<absolute relay URL returned by the results response>"
curl "$RESULT_MEDIA_URL" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Range: bytes=0-1048575" \
  -o result-media.bin

GET/agents/task-queries/{task_query_id}/failure-details/Read failure diagnosticsWorkflow helper

Returns sanitized diagnostics for a failed pipeline, including suggested next inspection steps when available.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Failed task query to inspect.
`query.include_debug`	boolean	No	Include additional debug fields when allowed.

Response fields

Name	Type	Required	Description
`pipeline_id`	uuid	No	Failed task query.
`task_status`	string	No	Durable task state.
`failure`	object \| null	No	Canonical sanitized failure payload, including a typed code and safe details when available.
`summary`	object	No	Message, source, stage, task, exception, category, and timestamp when available.
`diagnostics`	object	No	Failure category and fix suggestions.
`agent_action`	object	No	Structured next action for agent clients.
`recommended_next_steps`	array	No	Suggested remediation steps.
`model_versions`	array	No	Model-version status and result-snapshot readiness.
`debug`	object	No	Availability, enablement, and inclusion state for debug details.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

The MCP result helper may automatically attach this payload when /results/ reports a failed pipeline.
Typed GPU-memory failures may expose code GPU_MEMORY_RUNTIME_OOM, category gpu_memory, and optional sanitized fields such as recommended_batch_size, memory estimates, and recommended next steps. Treat those fields as additive and check for their presence.
Apply a positive recommended_batch_size before retrying. A recommendation of zero means batch size one is still too large, so reduce model or input size instead.

# Clone a task query into a new editable pipeline.
# The clone automatically inherits the source's pinned ML backend profile.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/clone/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"editable-copy","dataset_id":"'$DATASET_ID'"}'

# Inspect runtime readiness and final summary.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/runtime-contract/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/run-summary/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Read sanitized failure details after failed runs.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/failure-details/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/agents/task-queries/{task_query_id}/runtime-contract/Read runtime contractWorkflow helper

Returns the normalized planned pipeline contract before or after execution, including attached dataset, target, architecture, metrics, split counts, and explainability request where available.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to inspect.

Response fields

Name	Type	Required	Description
`dataset`	object \| null	No	Attached dataset id, format, accessibility, sample total, and split_counts.
`task`	object \| null	No	Planned training task name, type, and status.
`target`	object	No	Normalized training target.
`classification_mode`	string \| null	No	Resolved binary, multiclass, or non-classification target mode.
`architecture`	object	No	Selected architecture and relevant config.
`training`	object	No	Training resource and config.
`criterion`	object	No	Loss/criterion resource and config.
`optimizer`	object	No	Optimizer resource and config.
`metrics`	array	No	Planned evaluation metrics.
`transforms`	array	No	Planned transforms.
`explainability`	object	No	Requested image explainability mode and config.
`validation_warnings`	array	No	Readiness issues to resolve before execution.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

The runtime contract confirms the planned architecture and validation warnings, but it does not by itself prove that every selected ML backend has the provider required by a newly cataloged model. Confirm backend support before execution.

# Clone a task query into a new editable pipeline.
# The clone automatically inherits the source's pinned ML backend profile.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/clone/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"editable-copy","dataset_id":"'$DATASET_ID'"}'

# Inspect runtime readiness and final summary.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/runtime-contract/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/run-summary/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Read sanitized failure details after failed runs.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/failure-details/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/agents/task-queries/{task_query_id}/run-summary/Read compact run summaryWorkflow helper

Returns one compact final pipeline summary intended for agent and headless-client verification after a run.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to summarize.

Response fields

Name	Type	Required	Description
`task_status`	string	No	Durable final or current task state.
`runtime_contract`	object	No	Normalized planned runtime contract.
`dataset_verification`	object \| null	No	Database-derived dataset counts and distributions.
`model_version`	object \| null	No	Latest model version, metric, status, and checkpoint stages.
`canonical_metrics`	object	No	Normalized final metric values.
`primary_metric`	object \| null	No	Selected primary metric name, value, and source.
`metric_sources`	object	No	Source and confidence state for each metric.
`confusion_matrix`	array \| null	No	Final confusion matrix when available.
`threshold_metadata`	object \| null	No	Evaluation threshold metadata when available.
`explainability`	object \| null	No	Final explainability payload when available.
`failure_details`	object	No	Included when task_status is failed.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

# Clone a task query into a new editable pipeline.
# The clone automatically inherits the source's pinned ML backend profile.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/clone/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"editable-copy","dataset_id":"'$DATASET_ID'"}'

# Inspect runtime readiness and final summary.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/runtime-contract/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/run-summary/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Read sanitized failure details after failed runs.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/failure-details/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

POST/agents/task-queries/{task_query_id}/model-card-report/Generate model-card reportCovered

Generates or refreshes a pipeline-level or model-version-specific model-card report and returns serialized JSON.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query that should produce a report.

Request body

Name	Type	Required	Description
`body.model_version_id`	uuid	No	Optional model version owned by this task query.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Generated report id.
`pipeline_model_version`	uuid \| null	No	Scoped model version, or null for a pipeline-level report.
`model_version_label`	string \| null	No	Display label such as v2.
`report_scope`	pipeline \| pipeline_model_version	No	Report scope.
`markdown`	string	No	Generated model-card markdown when included by the serializer.
`title`	string	No	Report title.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

# Generate or refresh a model-card report and get JSON.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model_version_id":"'$MODEL_VERSION_ID'"}'

# Retrieve the latest report as serializer JSON.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/?response=json&model_version_id=$MODEL_VERSION_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: application/json"

# Stream model-card generation events with SSE.
curl -N -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/stream/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"model_version_id":"'$MODEL_VERSION_ID'"}'

# Download the latest report as markdown.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/download/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -o model-card.md

GET/agents/task-queries/{task_query_id}/model-card-report/?response=jsonRead model-card report JSONCovered

Returns the latest pipeline model-card report through the JSON serializer. Omit response=json only when markdown content is desired.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query that produced the report.
`query.response`	json	Yes	Set to json to request the serializer response.
`query.model_version_id`	uuid	No	Optional model-version report scope.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Report id.
`pipeline_model_version`	uuid \| null	No	Scoped model version.
`model_version_label`	string \| null	No	Display label for the model version.
`report_scope`	pipeline \| pipeline_model_version	No	Whether the report covers the pipeline or one version.
`markdown`	string	No	Generated report markdown.
`title`	string	No	Report title.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

# Generate or refresh a model-card report and get JSON.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model_version_id":"'$MODEL_VERSION_ID'"}'

# Retrieve the latest report as serializer JSON.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/?response=json&model_version_id=$MODEL_VERSION_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: application/json"

# Stream model-card generation events with SSE.
curl -N -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/stream/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"model_version_id":"'$MODEL_VERSION_ID'"}'

# Download the latest report as markdown.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/download/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -o model-card.md

GET/agents/task-queries/{task_query_id}/model-card-report/download/Download model-card markdownCovered

Downloads the latest pipeline model-card report as text/markdown. GET without response=json on the base report URL also returns markdown.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query that produced the report.
`query.model_version_id`	uuid	No	Optional model-version report scope.

Response fields

Name	Type	Required	Description
`file`	text/markdown	No	Model-card markdown bytes.

Status codes

Code	Meaning
`200`	Returns a file response or download metadata for the requested artifact.
`401`	API key is missing, inactive, expired, or malformed.
`404`	The file, export job, or source object is missing or hidden by permissions.

Use ?response=json on the base model-card-report URL when a JSON serializer payload is needed.

POST/agents/task-queries/{task_query_id}/model-card-report/stream/Stream model-card generationCovered

Streams model-card generation events using server-sent events and persists the latest report.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query that should produce a streamed report.

Request body

Name	Type	Required	Description
`body.model_version_id`	uuid	No	Optional model-version report scope.

Response fields

Name	Type	Required	Description
`event`	text/event-stream	No	SSE frames describing report generation progress and output.

Status codes

Code	Meaning
`200`	Returns a text/event-stream response.
`401`	API key is missing, inactive, expired, or malformed.
`404`	The source object is missing, hidden by permissions, or report generation is disabled.

POST/agents/task-queries/{task_query_id}/snapshot-export/Start snapshot exportCovered

Starts an export job for a pipeline snapshot. Save the returned job id before polling or downloading.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query to export.

Request body

Name	Type	Required	Description
`body.include_checkpoint`	boolean	No	Include checkpoint data when supported and needed.

Response fields

Name	Type	Required	Description
`job_id`	string	No	Save as JOB_ID for status and download calls.
`status_url`	string	No	Status URL when returned by the backend.

Status codes

Code	Meaning
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.

# Start snapshot export. Save the returned job_id.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/snapshot-export/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_checkpoint":true}'

# Poll export status.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/snapshot-export/$JOB_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Download the completed archive.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/snapshot-export/$JOB_ID/download/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -o pipeline-snapshot.zip

GET/agents/task-queries/{task_query_id}/snapshot-export/{job_id}/Poll snapshot exportCovered

Checks status for a previously started snapshot export job.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query being exported.
`path.job_id`	string	Yes	Export job id returned by snapshot export start.

Response fields

Name	Type	Required	Description
`status`	string	No	Export job status.
`download_url`	string	No	Download URL when available.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

POST/agents/task-queries/import/Import pipeline snapshotCovered

Imports a pipeline snapshot bundle and returns the imported or hydrated task-query representation.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`form.file`	file	Yes	Snapshot archive to import.
`form.dataset`	uuid	No	Dataset binding to apply during import.

Response fields

Name	Type	Required	Description
`task_query`	object	No	Imported task query payload.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

# Import a pipeline snapshot archive.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/import/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -F "dataset=$DATASET_ID" \
  -F "file=@./pipeline-snapshot.zip"

GET/agents/task-queries-synopsis/List task-query synopsis rowsWorkflow helper

Returns compact task-query rows for selection and comparison workflows.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`query.archived`	boolean	No	Filter archived task queries.
`query.page_size`	integer	No	Opt into cursor pagination. Defaults to 20 and is capped at 100.
`query.cursor`	opaque string	No	Opaque cursor returned inside a next or previous URL.

Response fields

Name	Type	Required	Description
`legacy array`	array	No	Compact task-query rows returned when page_size and cursor are omitted.
`next`	string \| null	No	Opaque absolute URL for the next cursor page when pagination is active.
`previous`	string \| null	No	Opaque absolute URL for the previous cursor page when pagination is active.
`results`	array	No	Compact task-query rows when cursor pagination is active.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.
`404`	The supplied cursor is invalid or malformed.

Pagination is opt-in. Omit page_size and cursor to retain the legacy raw-array response.
Rows use the fixed order -created, -id. Follow next or previous exactly with the same API key; do not parse or construct cursor values.

# Page-number pagination remains endpoint-specific.
curl "$MODASTERA_API_BASE_URL/datasets/samples/?dataset=$DATASET_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/experiments/$EXPERIMENT_ID/artifacts/?include_payload=0" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/resources/all-usage/?deployment=$DEPLOYMENT_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Cursor pagination is opt-in for these compact lists.
curl "$MODASTERA_API_BASE_URL/datasets/summary/?view=list&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/agents/task-queries-synopsis/?page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Follow the returned next or previous URL exactly with the same API key.
# Do not decode, edit, or construct the cursor yourself.
NEXT_URL="<opaque next URL returned by the response>"
curl "$NEXT_URL" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/agents/task-queries/{task_query_id}/compare-candidates/List comparison candidatesWorkflow helper

Returns trained pipelines that can be compared with the current task query.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Current task query.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Candidate task query id.
`primary_test_metric`	string	No	Primary metric name.
`primary_test_metric_value`	number	No	Primary metric value.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

POST/agents/task-queries/{task_query_id}/compare/Compare task queriesWorkflow helper

Compares the current pipeline against selected trained pipeline ids.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Current task query.

Request body

Name	Type	Required	Description
`body.pipeline_ids`	uuid[]	Yes	Other pipeline ids to compare.

Response fields

Name	Type	Required	Description
`columns`	array	No	Compared pipelines.
`rows`	array	No	Metric comparison rows.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

POST/agents/task-queries/{task_query_id}/finetune/Create fine-tune pipelineWorkflow helper

Creates a child pipeline for fine-tuning from a trained source pipeline and target dataset.

AuthApi-Key API keyCoverageWorkflow helper

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Source trained task query.

Request body

Name	Type	Required	Description
`body.dataset_id`	uuid	Yes	Target dataset for fine-tuning.
`body.name`	string	No	Optional child pipeline name.
`body.instruction`	string	No	Additional instruction appended to source instruction.
`body.use_same_config`	boolean	No	Reuse source configuration where supported.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Created child task query id.
`ml_backend_profile`	object \| null	No	Pinned execution profile inherited from the resolved source model version or source pipeline.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

Fine-tuning is only available when the source pipeline has a reusable trained model and architecture configuration.
The child automatically retains the resolved source model version’s ML backend profile. Clients cannot override that profile in this request, and an unavailable source profile is rejected.

API Reference

Deployments and prediction API reference#

Deployment endpoints cover model-version selection, deployment lifecycle, server-side prediction calls, text generation, usage inspection, and deployment charts.

Call predictor from your server so API keys never reach a browser or mobile client.
Create deployments with task_query, selected_model_version, and selected_checkpoint_stage.
Text generation is model-type-specific and returns 400 for deployments that do not support it.

# List model versions produced by a task query.
curl "$MODASTERA_API_BASE_URL/resources/pipeline-model-versions/?task_query=$TASK_QUERY_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Compare candidate model versions before deployment.
curl -X POST "$MODASTERA_API_BASE_URL/resources/pipeline-model-versions/compare/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"versions":["model_version_id_1","model_version_id_2"]}'

# Deploy the chosen model version.
curl -X POST "$MODASTERA_API_BASE_URL/resources/deployments/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"headless-predictor","task_query":"'$TASK_QUERY_ID'","selected_model_version":"'$MODEL_VERSION_ID'","selected_checkpoint_stage":"best"}'

GET/resources/pipeline-model-versions/List model versionsCovered

Lists deployable model versions, usually filtered by task query after a successful run.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.task_query`	uuid	No	Filter model versions by task query.
`query.task_queries`	uuid,csv	No	Filter model versions by multiple task query ids.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Save as MODEL_VERSION_ID for deployment creation.
`status`	string	No	Training/deployment readiness status.
`checkpoint_stage`	string	No	Checkpoint stage metadata when returned.
`ml_backend_profile`	object \| null	No	Sanitized ML backend profile pinned to this model version.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

Use this field, rather than the user’s current default, to identify the backend pinned to the model version.

# List model versions produced by a task query.
curl "$MODASTERA_API_BASE_URL/resources/pipeline-model-versions/?task_query=$TASK_QUERY_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Compare candidate model versions before deployment.
curl -X POST "$MODASTERA_API_BASE_URL/resources/pipeline-model-versions/compare/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"versions":["model_version_id_1","model_version_id_2"]}'

# Deploy the chosen model version.
curl -X POST "$MODASTERA_API_BASE_URL/resources/deployments/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"headless-predictor","task_query":"'$TASK_QUERY_ID'","selected_model_version":"'$MODEL_VERSION_ID'","selected_checkpoint_stage":"best"}'

GET/resources/pipeline-model-versions/{model_version_id}/Read model versionCovered

Reads one pipeline model version visible through task-query access.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.model_version_id`	uuid	Yes	Model version to read.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Model version id.
`primary_metric_value`	number	No	Primary metric value when available.
`ml_backend_profile`	object \| null	No	Sanitized ML backend profile pinned to this model version.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

POST/resources/pipeline-model-versions/compare/Compare model versionsCovered

Compares candidate model versions before choosing one for deployment.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`body.versions`	uuid[]	Yes	Two or more distinct model version ids to compare.

Response fields

Name	Type	Required	Description
`versions`	array	No	Serialized model versions in requested order.
`primary_metric_delta`	number \| null	No	Difference between last and first primary metric values when available.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

POST/resources/deployments/Create a deploymentCovered

Creates a predictor deployment for a selected model version and checkpoint stage.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`body.name`	string	Yes	Deployment name.
`body.task_query`	uuid	Yes	Task query that produced the model.
`body.selected_model_version`	uuid	Yes	Model version to deploy.
`body.selected_checkpoint_stage`	best \| final	No	Checkpoint stage to deploy.
`body.use_model_card_description`	boolean	No	Copy latest model-card markdown into the deployment description when empty.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Save as DEPLOYMENT_ID for predictor calls.
`status`	string	No	Deployment readiness state.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

GET/resources/deployments/List deploymentsCovered

Lists deployments visible to the API-key owner, optionally filtered by task query.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.task_query`	uuid	No	Filter deployments by source task query.
`query.active`	boolean	No	Filter by active state.
`query.hidden`	boolean	No	Filter by hidden state.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Deployment id.
`selected_model_version`	uuid	No	Selected model version id.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/resources/deployments/{deployment_id}/Read deploymentCovered

Reads one deployment and its selected model version details.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.deployment_id`	uuid	Yes	Deployment to read.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Deployment id.
`active`	boolean	No	Whether the deployment is active.
`selected_model_version`	uuid	No	Selected model version id.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

PATCH/resources/deployments/{deployment_id}/Update deploymentCovered

Partially updates deployment metadata, active state, selected model version, or checkpoint stage.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.deployment_id`	uuid	Yes	Deployment to update.

Request body

Name	Type	Required	Description
`body.name`	string	No	Updated deployment name.
`body.active`	boolean	No	Activate or stop the deployment.
`body.selected_model_version`	uuid	No	New selected model version.
`body.selected_checkpoint_stage`	best \| final	No	New checkpoint stage.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Updated deployment id.

Status codes

Code	Meaning
`200`	Resource was updated and the updated representation was returned.
`400`	Patch body failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to update the object.
`404`	The object is missing or hidden by permissions.

# Read, update, and check a deployment.
curl "$MODASTERA_API_BASE_URL/resources/deployments/$DEPLOYMENT_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X PATCH "$MODASTERA_API_BASE_URL/resources/deployments/$DEPLOYMENT_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":true,"selected_checkpoint_stage":"best"}'

curl "$MODASTERA_API_BASE_URL/resources/deployment-versioning-capabilities/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/executors/predictor/?deployment=$DEPLOYMENT_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/resources/deployments/$DEPLOYMENT_ID/generate-text/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Summarize the input.","generation_config":{"max_new_tokens":128}}'

DELETE/resources/deployments/{deployment_id}/Delete deploymentCovered

Deletes a deployment visible to the API-key owner.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.deployment_id`	uuid	Yes	Deployment to delete.

Response fields

Name	Type	Required	Description
`empty`	none	No	Successful deletes return no response body.

Status codes

Code	Meaning
`204`	Resource was deleted.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks permission to delete the object.
`404`	The object is missing or hidden by permissions.

GET/resources/deployment-versioning-capabilities/Read deployment versioning capabilitiesWorkflow helper

Returns the backend capabilities that describe supported deployment versioning behavior.

AuthApi-Key API keyCoverageWorkflow helper

Response fields

Name	Type	Required	Description
`capabilities`	object	No	Deployment versioning feature flags and defaults.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/executors/predictor/Read predictor statusCovered

Checks predictor runtime status for a deployment.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.deployment`	uuid	Yes	Deployment to inspect.

Response fields

Name	Type	Required	Description
`status`	object	No	Predictor status payload returned by the ML backend.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

# Read, update, and check a deployment.
curl "$MODASTERA_API_BASE_URL/resources/deployments/$DEPLOYMENT_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X PATCH "$MODASTERA_API_BASE_URL/resources/deployments/$DEPLOYMENT_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":true,"selected_checkpoint_stage":"best"}'

curl "$MODASTERA_API_BASE_URL/resources/deployment-versioning-capabilities/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/executors/predictor/?deployment=$DEPLOYMENT_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/resources/deployments/$DEPLOYMENT_ID/generate-text/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Summarize the input.","generation_config":{"max_new_tokens":128}}'

POST/executors/predictor/Run predictionCovered

Runs inference against a deployment using multipart form data.

AuthApi-Key API keyCoverageCovered

Request body

Name	Type	Required	Description
`form.deployment`	uuid	Yes	Deployment id.
`form.file`	file	No	Input file to score for image deployments.
`form.data_type`	image \| text \| tabular	No	Input modality. Defaults to image.
`form.inputs`	JSON string	No	Structured inputs for non-image deployments when supported.

Response fields

Name	Type	Required	Description
`prediction`	object	No	Prediction result payload.
`usage`	object	No	Usage or latency metadata when returned.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

import os
import requests

base_url = os.environ["MODASTERA_API_BASE_URL"].rstrip("/")
api_key = os.environ["MODASTERA_API_KEY"]
task_query_id = os.environ["TASK_QUERY_ID"]
model_version_id = os.environ["MODEL_VERSION_ID"]
headers = {"Authorization": f"Api-Key {api_key}", "Accept": "application/json"}

versions = requests.get(
    f"{base_url}/resources/pipeline-model-versions/",
    headers=headers,
    params={"task_query": task_query_id},
    timeout=30,
)
versions.raise_for_status()

deployment = requests.post(
    f"{base_url}/resources/deployments/",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "name": "headless-predictor",
        "task_query": task_query_id,
        "selected_model_version": model_version_id,
        "selected_checkpoint_stage": "best",
    },
    timeout=30,
)
deployment.raise_for_status()
deployment_id = deployment.json().get("id", os.environ.get("DEPLOYMENT_ID"))

with open("holdout.png", "rb") as holdout_file:
    prediction = requests.post(
        f"{base_url}/executors/predictor/",
        headers={"Authorization": f"Api-Key {api_key}"},
        data={"deployment": deployment_id},
        files={"file": holdout_file},
        timeout=120,
    )
prediction.raise_for_status()
print(prediction.json())

metrics = requests.get(
    f"{base_url}/resources/deployment-metrics/",
    headers=headers,
    timeout=30,
)
metrics.raise_for_status()
print(metrics.json())

POST/resources/deployments/{deployment_id}/generate-text/Generate textPartial

Runs text generation for deployments backed by a text-generation language model.

AuthApi-Key API keyCoveragePartial

Parameters

Name	Type	Required	Description
`path.deployment_id`	uuid	Yes	Deployment to use for generation.

Request body

Name	Type	Required	Description
`body.prompt`	string	Yes	Prompt to generate from.
`body.generation_config`	object	No	Optional generation settings.

Response fields

Name	Type	Required	Description
`output`	object	No	Text generation payload returned by the model runtime.

Status codes

Code	Meaning
`201`	Resource was created.
`400`	Request body, form fields, or uploaded files failed validation.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the parent object.

Returns 400 when the deployment is not backed by a text-generation language model.

GET/resources/deployment-metrics/Read deployment metricsCovered

Returns aggregate usage counts for deployments visible to the API-key owner.

AuthApi-Key API keyCoverageCovered

Response fields

Name	Type	Required	Description
`total_api_calls`	integer	No	Total prediction calls across accessible deployments.
`active_deployments`	integer	No	Active accessible deployment count.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/resources/chart-data/latency/Read latency chart dataCovered

Returns daily average latency rows for deployment monitoring.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.deployment`	uuid	No	Limit rows to one deployment.
`query.start_date`	datetime	No	Start of the time range.
`query.end_date`	datetime	No	End of the time range.

Response fields

Name	Type	Required	Description
`timestamp`	datetime	No	Bucket start timestamp.
`avg_latency`	number	No	Average latency for the bucket.
`count`	integer	No	Usage rows in the bucket.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/resources/chart-data/api-calls/Read API-call chart dataCovered

Returns daily API-call volume rows for deployment monitoring.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.deployment`	uuid	No	Limit rows to one deployment.
`query.start_date`	datetime	No	Start of the time range.
`query.end_date`	datetime	No	End of the time range.

Response fields

Name	Type	Required	Description
`timestamp`	datetime	No	Bucket start timestamp.
`api_calls`	integer	No	Prediction calls in the bucket.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/resources/all-usage/List usage recordsCovered

Returns paginated lightweight usage rows across deployments visible to the API-key owner.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.deployment`	uuid	No	Limit usage to one deployment.
`query.start_date`	datetime	No	Start timestamp filter.
`query.end_date`	datetime	No	End timestamp filter.
`query.page`	integer	No	Page number.
`query.page_size`	integer	No	Maximum rows per page.

Response fields

Name	Type	Required	Description
`results`	array	No	Usage rows without heavy response/input payloads.
`warnings`	object	No	Date parsing warnings when provided.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

# Inspect usage rows and explainability.
curl "$MODASTERA_API_BASE_URL/resources/all-usage/?deployment=$DEPLOYMENT_ID&page=1&page_size=25" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/resources/deployment-usages/?deployment=$DEPLOYMENT_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl "$MODASTERA_API_BASE_URL/resources/usage/$USAGE_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

curl -X POST "$MODASTERA_API_BASE_URL/resources/usage/$USAGE_ID/explainability/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

GET/resources/deployment-usages/List deployment usage resourcesCovered

Lists deployment usage resources through the resource viewset for deployments the key owner can access.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`query.deployment`	uuid	No	Filter by deployment.
`query.user`	uuid	No	Filter by usage owner when visible.

Response fields

Name	Type	Required	Description
`results`	array	No	Deployment usage records.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/resources/usage/{usage_id}/Read usage detailCovered

Returns full execution detail for a usage row, including inputs and response.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.usage_id`	uuid	Yes	Usage record to inspect.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Usage id.
`inputs`	object	No	Captured request inputs when stored.
`response`	object	No	Captured prediction response when stored.

Status codes

Code	Meaning
`200`	Returns the requested resource visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested object.
`404`	The object is missing or hidden by permissions.

POST/resources/usage/{usage_id}/explainability/Read usage explainabilityCovered

Returns or lazily computes structured explainability for one usage row.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.usage_id`	uuid	Yes	Usage record to explain.

Response fields

Name	Type	Required	Description
`explainability`	object	No	Structured explainability payload.

Status codes

Code	Meaning
`202`	The operation started, queued, or returned an async handle.
`400`	The request cannot be started with the provided payload or current state.
`401`	API key is missing, inactive, expired, or malformed.
`409`	The operation conflicts with the current resource or task state.

GET/resources/usage/{usage_id}/result-media/Stream deployment result mediaCovered

Streams the stored primary result artifact for an accessible deployment usage row from the ML backend profile that produced it.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.usage_id`	uuid	Yes	Deployment usage record that owns the result artifact.
`header.Range`	bytes range	No	Optional byte range forwarded to the producing ML backend.

Response fields

Name	Type	Required	Description
`file`	binary stream	No	Stored result media with upstream content metadata.
`Cache-Control`	private, no-store	No	Protected result media is not publicly cacheable.

Status codes

Code	Meaning
`200`	Full result media stream.
`206`	Partial stream for a satisfiable Range request.
`401`	API key is missing or invalid.
`404`	Usage row or upstream result media is unavailable.
`416`	Requested byte range is not satisfiable.
`502`	Producing ML backend rejected or could not serve the media.
`504`	Producing ML backend timed out.

Use this authenticated relay instead of reading stored ML file paths directly.

API Reference

Files and artifacts API reference#

File endpoints expose metadata-first artifact inspection and raw downloads for markdown reports and snapshot archives used by the public workflow.

Use include_payload=0 on artifact listings before requesting large payloads.
Treat signed URLs and downloaded report links as bearer credentials.
Model-card report downloads return markdown files.

# List lightweight artifact metadata first.
curl "$MODASTERA_API_BASE_URL/agents/experiments/$EXPERIMENT_ID/artifacts/?include_payload=0" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Retrieve one artifact when you need the full metadata or payload reference.
curl "$MODASTERA_API_BASE_URL/agents/experiments/$EXPERIMENT_ID/artifacts/$ARTIFACT_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Download reports or archives after reading their metadata/status.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/download/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -o model-card.md

GET/agents/experiments/{experiment_id}/artifacts/List experiment artifactsCovered

Lists artifact metadata for an experiment without forcing large payload downloads.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.experiment_id`	uuid	Yes	Experiment whose artifacts should be listed.
`query.include_payload`	0 \| 1	No	Use 0 for lightweight metadata listings.
`query.artifact_type`	string	No	Filter by artifact category when supported.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Save as ARTIFACT_ID for detail calls.
`artifact_type`	string	No	Artifact category.
`metadata`	object	No	Artifact metadata and download references when available.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

GET/agents/experiments/{experiment_id}/artifacts/{artifact_id}/Read artifact detailCovered

Retrieves metadata or payload references for a single artifact.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.experiment_id`	uuid	Yes	Experiment id.
`path.artifact_id`	uuid	Yes	Artifact id.

Response fields

Name	Type	Required	Description
`id`	uuid	No	Artifact id.
`payload`	object	No	Artifact payload when included by the backend.

Status codes

Code	Meaning
`200`	Returns a list, array, or collection payload visible to the API-key owner.
`401`	API key is missing, inactive, expired, or malformed.
`403`	The key owner lacks access to the requested collection.

# List lightweight artifact metadata first.
curl "$MODASTERA_API_BASE_URL/agents/experiments/$EXPERIMENT_ID/artifacts/?include_payload=0" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Retrieve one artifact when you need the full metadata or payload reference.
curl "$MODASTERA_API_BASE_URL/agents/experiments/$EXPERIMENT_ID/artifacts/$ARTIFACT_ID/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Download reports or archives after reading their metadata/status.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/download/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -o model-card.md

GET/agents/task-queries/{task_query_id}/model-card-report/download/Download model-card markdownCovered

Downloads the latest generated model-card report for a task query as text/markdown.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query that produced the report.

Response fields

Name	Type	Required	Description
`file`	text/markdown	No	Model-card markdown bytes.

Status codes

Code	Meaning
`200`	Returns a file response or download metadata for the requested artifact.
`401`	API key is missing, inactive, expired, or malformed.
`404`	The file, export job, or source object is missing or hidden by permissions.

# Fetch metadata/listing first when available.
curl "$MODASTERA_API_BASE_URL/agents/experiments/$EXPERIMENT_ID/artifacts/?include_payload=0" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Download generated reports or exports.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/model-card-report/download/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -o model-card.md

curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/snapshot-export/$JOB_ID/download/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -o pipeline-snapshot.zip

GET/agents/task-queries/{task_query_id}/snapshot-export/{job_id}/download/Download snapshot archiveCovered

Downloads a completed snapshot export archive.

AuthApi-Key API keyCoverageCovered

Parameters

Name	Type	Required	Description
`path.task_query_id`	uuid	Yes	Task query that was exported.
`path.job_id`	string	Yes	Completed snapshot export job id.
`query.token`	string	No	Short-lived download token when using tokenized download links.

Response fields

Name	Type	Required	Description
`file`	application/zip	No	Pipeline snapshot archive bytes.

Status codes

Code	Meaning
`200`	Returns a file response or download metadata for the requested artifact.
`401`	API key is missing, inactive, expired, or malformed.
`404`	The file, export job, or source object is missing or hidden by permissions.

MCP Reference

MCP Reference#

The MCP reference covers the local stdio backend adapter. It wraps supported public REST APIs with tool-friendly payloads while preserving their authentication, permissions, and result behavior.

5tool groups

39MCP tools

stdiolocal transport

MCP capabilities2 tools

Capability tools expose supported tools and selectable model execution profiles.

MCP architecture2 tools

Architecture tools expose the backend architecture knowledgebase used by pipeline config and architecture-swap workflows.

MCP datasets13 tools

Dataset tools create and inspect datasets, upload samples and annotations, register no-copy local references, create splits, verify counts, and run analysis.

MCP pipelines20 tools

Pipeline tools list, create, plan, clone, fine-tune, configure, run, diagnose, summarize, report, interrupt, and inspect model versions.

MCP deployments2 tools

Deployment tools create deployments from pipeline model versions and activate or deactivate existing deployments.

MCP Reference

MCP capabilities reference#

Capability tools expose supported tools and selectable model execution profiles.

Configure the approved local stdio adapter as a trusted child process in your MCP client.
Call capabilities first so clients can confirm the supported tool names.
When multiple ML backend profiles are available, list them before creating a pipeline and pass the chosen id at creation time.

{
  "tool": "modastera_get_capabilities",
  "arguments": {}
}

MCPmodastera_get_capabilitiesRead adapter capabilities

Returns the supported tool names and workflow-selection information available to the authenticated client.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Returns

Name	Type	Required	Description
`tools`	string[]	No	Enabled MCP tool names.
`ml_backend_profile_selection`	object	No	Profile discovery tool, create argument, and default behavior.

{
  "tool": "modastera_get_capabilities",
  "arguments": {}
}

MCPmodastera_list_available_ml_backend_profilesList available ML backend profiles

Lists the ML execution profiles available to the API-key user, including the selected/default profile and local-file capability.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/users/ml-backend-profiles/available/

Returns

Name	Type	Required	Description
`count`	integer	No	Number of available profiles.
`selected_profile_id`	uuid \| null	No	Profile used when create_pipeline omits an explicit id.
`has_multiple_choices`	boolean	No	Whether the client should present a profile choice.
`profiles`	array	No	Available profile ids, names, default/selected state, and local-file capability.

Pass ml_backend_profile_id only when creating a pipeline; it cannot be changed on an existing pipeline.

{
  "tool": "modastera_list_available_ml_backend_profiles",
  "arguments": {}
}

{
  "tool": "modastera_create_pipeline",
  "arguments": {
    "name": "profile-routed-training",
    "instruction": "Train and evaluate an image classifier",
    "dataset_id": "<dataset-id>",
    "ml_backend_profile_id": "<available-profile-id>"
  }
}

MCP Reference

MCP architecture discovery reference#

Architecture tools expose the backend architecture knowledgebase used by pipeline config and architecture-swap workflows.

The public segmentation catalog includes EoMT DINOv2 Small, Base, and Large 640 for panoptic segmentation; RF-DETR Segmentation Nano, Small, Medium, and Large for instance segmentation; and RTMDet-Ins Tiny, Small, Medium, and Large for instance segmentation.
Catalog discovery and capability metadata do not prove that every selected ML backend can execute a model. Verify task-scoped related options, the planned runtime contract, and backend support before pinning or swapping.

# Browse the architecture catalog used by pipeline config tools.
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/?include_details=true" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Inspect one public segmentation catalog entry. Catalog discovery is not a
# guarantee that every selected ML backend can execute the model.
SEGMENTATION_MODEL_KEY="EoMTDINOv2Small640"
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/$SEGMENTATION_MODEL_KEY/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# After planning, use the task-scoped related list as the replacement set.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-knowledgebase/?resource_id=$RESOURCE_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Swap only a not-started pipeline and only after verifying task and runtime support.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-swap/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_id":"'$RESOURCE_ID'","target_model_key":"'$SEGMENTATION_MODEL_KEY'","override_params":{}}'

MCPmodastera_list_supported_architecturesList supported architectures

Lists catalog models, including discoverable segmentation variants, optionally filtered by category, module family, or search text.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/architecture-knowledgebase/

Arguments

Name	Type	Required	Description
`category`	string	No	Optional architecture category filter.
`module_family`	string	No	Optional module family filter.
`search`	string	No	Optional search text.
`include_details`	boolean	No	Include detailed model metadata when true.

Returns

Name	Type	Required	Description
`models`	array	No	Architecture catalog rows or grouped catalog payload with capability metadata when returned.

Treat returned capability as discovery metadata and separately confirm support on the selected ML backend before execution.

MCPmodastera_get_supported_architectureRead architecture detail

Returns detailed metadata for one supported architecture model key.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/architecture-knowledgebase/{model_key}/

Arguments

Name	Type	Required	Description
`model_key`	string	Yes	Catalog model key to read.

Returns

Name	Type	Required	Description
`model`	object	No	Architecture detail payload.

Use the exact returned model_key in later tools. Do not derive a key from a display name or lower-level module metadata.

MCP Reference

MCP datasets and ingestion reference#

Dataset tools create and inspect datasets, upload samples and annotations, register no-copy local references, create splits, verify counts, and run analysis.

Upload and local registration tools read paths from the machine or container running the stdio adapter.
Use local registration only with trusted clients and backend local-file-reference roots configured by an operator.

{
  "tool": "modastera_create_dataset",
  "arguments": {
    "name": "mcp-training-set",
    "description": "Created through the local MCP adapter",
    "format": "image",
    "access": "private"
  }
}

{
  "tool": "modastera_upload_sample",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "file_path": "/absolute/path/to/sample.png",
    "split": "training",
    "classification_label": "Diagnosis",
    "classification_value": "positive"
  }
}

{
  "tool": "modastera_get_csv_upload_progress",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "task_id": "<csv-task-id>"
  }
}

MCPmodastera_list_datasetsList datasets

Lists datasets visible to the API-key user through the existing dataset API.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/datasets/

Arguments

Name	Type	Required	Description
`archived`	boolean	No	Filter archived datasets.
`format`	string	No	Legacy format filter.
`dataset_format`	string	No	Dataset modality filter.
`search`	string	No	Search dataset names or metadata where supported.
`page`	integer	No	Optional page number.
`page_size`	integer	No	Optional page size.

Returns

Name	Type	Required	Description
`datasets`	array \| paginated object	No	Dataset rows visible to the key owner.

MCPmodastera_create_datasetCreate dataset

Creates a dataset through the existing backend dataset API.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/datasets/

Arguments

Name	Type	Required	Description
`name`	string	Yes	Dataset name.
`description`	string	No	Optional description.
`format`	string	No	Dataset format, default image.
`labels`	array	No	Optional label schema.
`access`	private \| organization \| global	No	Dataset access, default private.

Returns

Name	Type	Required	Description
`id`	uuid	No	Created dataset id.

{
  "tool": "modastera_create_dataset",
  "arguments": {
    "name": "mcp-training-set",
    "description": "Created through the local MCP adapter",
    "format": "image",
    "access": "private"
  }
}

{
  "tool": "modastera_upload_sample",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "file_path": "/absolute/path/to/sample.png",
    "split": "training",
    "classification_label": "Diagnosis",
    "classification_value": "positive"
  }
}

{
  "tool": "modastera_get_csv_upload_progress",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "task_id": "<csv-task-id>"
  }
}

MCPmodastera_upload_sampleUpload sample or CSV

Uploads a local file into a dataset. Local CSV files use the dataset bulk CSV upload path and return a task id for progress polling.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/samples//datasets/datasets/{dataset_id}/upload-csv/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Target dataset id.
`file_path`	absolute path	Yes	Path readable by the MCP server process.
`split`	training \| validation \| test	No	Optional split assignment.
`data_type`	string	No	Sample data type, default image.
`annotations`	array	No	Optional annotations.
`classification_label`	string	No	Optional classification label name.
`classification_value`	any	No	Optional classification label value.
`target_label`	string	No	Optional target label for tabular data.
`categorical_labels`	string[]	No	Optional categorical labels for tabular data.

Returns

Name	Type	Required	Description
`sample \| task_id`	object	No	Created sample payload or CSV upload task payload.

The MCP process can read any file path accessible to its local OS user. Configure only trusted clients.

MCPmodastera_get_csv_upload_progressPoll CSV upload

Returns progress for a bulk CSV row upload started by modastera_upload_sample.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/datasets/{dataset_id}/csv-upload-progress/{task_id}/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Dataset receiving rows.
`task_id`	string	Yes	CSV upload task id.

Returns

Name	Type	Required	Description
`progress`	object	No	CSV upload progress payload.

MCPmodastera_upload_annotation_fileUpload annotation manifest

Uploads CSV, platform JSON, or COCO JSON annotations and applies them to existing dataset samples by name.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/annotations-files/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Dataset whose samples should be annotated.
`file_path`	absolute path	Yes	Annotation file readable by the MCP process.
`file_format`	csv \| json \| coco	No	Optional explicit format; otherwise inferred from the extension.
`sample_name`	string	No	CSV column containing sample filenames.
`label_fields`	string[]	No	CSV columns to import as labels.
`labels_type`	object	No	CSV label type mapping.
`split`	training \| validation \| test	No	Optional split assignment for matched samples.

Returns

Name	Type	Required	Description
`id`	uuid	No	Stored annotation-file id.
`import_result`	object	No	COCO match, annotation, label, and skip counts when using COCO.

sample_name, label_fields, and labels_type apply only to CSV uploads. COCO imports are atomic and deduplicate retries.

{
  "tool": "modastera_upload_annotation_file",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "file_path": "/absolute/path/to/annotations.coco.json",
    "file_format": "coco",
    "split": "training"
  }
}

{
  "tool": "modastera_upload_masks",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "mask_paths": [
      "/absolute/path/to/sample-001.png",
      "/absolute/path/to/sample-002.png"
    ],
    "mask_mode": "color_map",
    "color_label_map": {
      "#ff0000": "tumor",
      "#00ff00": "stroma"
    },
    "background_colors": ["#000000"],
    "async_upload": true
  }
}

{
  "tool": "modastera_get_mask_upload_progress",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "task_id": "<mask-upload-task-id>"
  }
}

MCPmodastera_upload_masksUpload mask annotations

Uploads binary or color-mapped mask files and converts matched masks into polygon annotations.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/{dataset_id}/upload-masks/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Dataset receiving mask annotations.
`mask_paths`	absolute path[]	Yes	Non-empty list of mask files readable by the MCP process.
`split`	training \| validation \| test	No	Optional split assignment.
`label`	string	No	Required label for binary masks.
`mask_mode`	color_map	No	Set to color_map for multiclass masks.
`color_label_map`	object	No	Required hex-color to label mapping for color_map mode.
`background_colors`	string[]	No	Colors to ignore in color_map mode.
`async_upload`	boolean	No	Start background processing; defaults to true.

Returns

Name	Type	Required	Description
`task_id \| result`	object	No	Async progress handle or synchronous processing counts.

{
  "tool": "modastera_upload_annotation_file",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "file_path": "/absolute/path/to/annotations.coco.json",
    "file_format": "coco",
    "split": "training"
  }
}

{
  "tool": "modastera_upload_masks",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "mask_paths": [
      "/absolute/path/to/sample-001.png",
      "/absolute/path/to/sample-002.png"
    ],
    "mask_mode": "color_map",
    "color_label_map": {
      "#ff0000": "tumor",
      "#00ff00": "stroma"
    },
    "background_colors": ["#000000"],
    "async_upload": true
  }
}

{
  "tool": "modastera_get_mask_upload_progress",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "task_id": "<mask-upload-task-id>"
  }
}

MCPmodastera_get_mask_upload_progressPoll mask upload

Returns processing, match, skip, and missing-color progress for an asynchronous mask upload.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/{dataset_id}/mask-upload-progress/{task_id}/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Dataset receiving masks.
`task_id`	string	Yes	Task id returned by upload_masks.

Returns

Name	Type	Required	Description
`progress`	object	No	Status, progress percentage, file counts, and missing colors.

MCPmodastera_register_local_samplesRegister local samples

Registers local image, NIfTI, or DICOM file references without copying bytes into Django storage.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/local-file-references/capabilities//datasets/datasets/{dataset_id}/register-local-files/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Target dataset id.
`root`	string \| null	No	Configured local root name; may be omitted when a mapped absolute path resolves it.
`path`	path	Yes	Root-relative path or mapped absolute host path.
`recursive`	boolean	No	Walk directories recursively.
`data_type`	auto \| image \| nifti \| dicom	No	Data type, default auto.
`split`	training \| validation \| test	No	Optional split assignment.
`classification_label`	string	No	Optional label name.
`classification_value`	any	No	Optional label value.
`label_from_parent_dir`	boolean	No	Derive labels from parent folder names.
`dry_run`	boolean	No	Preview without registering.
`limit`	integer	No	Optional max files to register.
`annotations`	array	No	Annotations applied to one file or all files when enabled.
`annotations_by_path`	object	No	Per-file annotations keyed by path or basename.
`apply_annotations_to_all`	boolean	No	Apply shared annotations across the selected files.

Returns

Name	Type	Required	Description
`registered`	object	No	Registration summary and sample references.

Requires backend local file references to be enabled and roots allowlisted by an operator.

{
  "tool": "modastera_register_local_samples",
  "arguments": {
    "dataset_id": "<dataset-id>",
    "root": "datasets",
    "path": "wellgen/cytology-tranche-2/pericardium/positive",
    "recursive": true,
    "data_type": "image",
    "split": "training",
    "classification_label": "Atypia",
    "classification_value": 1.0,
    "label_from_parent_dir": false,
    "dry_run": false
  }
}

MCPmodastera_prepare_tomographic_atypia_variantsPrepare tomographic Atypia variants

Creates deterministic, leakage-safe image variants and train/validation/test folders inside a configured MCP local root.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Arguments

Name	Type	Required	Description
`source_path`	path	Yes	Source dataset path.
`output_path`	path	Yes	Output directory for prepared variants.
`root`	string	No	Configured local root when paths are root-relative.
`seed`	integer	No	Deterministic split seed; defaults to 42.
`training`	number	No	Training ratio; defaults to 0.8.
`validation`	number	No	Validation ratio; defaults to 0.1.
`test`	number	No	Test ratio; defaults to 0.1.
`image_size`	integer	No	Output image size; defaults to 224.
`limit_fovs`	integer	No	Optional field-of-view limit.
`overwrite`	boolean	No	Replace an existing output.
`variants`	string[]	No	Optional subset of generated variants.

Returns

Name	Type	Required	Description
`prepared`	object	No	Output paths, split counts, variant counts, and preparation metadata.

This specialized local preprocessing tool writes files and is available only to trusted local MCP clients.

{
  "tool": "modastera_prepare_tomographic_atypia_variants",
  "arguments": {
    "root": "datasets",
    "source_path": "wellgen/tomographic-atypia/source",
    "output_path": "wellgen/tomographic-atypia/prepared",
    "seed": 42,
    "training": 0.8,
    "validation": 0.1,
    "test": 0.1,
    "image_size": 224,
    "variants": ["raw", "clahe", "sharpened"]
  }
}

MCPmodastera_create_dataset_splitsCreate dataset splits

Creates random or stratified dataset splits through the dataset API.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/datasets/create-random-splits/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Dataset to split.
`training`	number	No	Training proportion, default 0.7.
`validation`	number	No	Validation proportion, default 0.15.
`test`	number	No	Test proportion, default 0.15.
`seed`	integer	No	Optional deterministic seed.
`stratified`	boolean	No	Use stratified split creation when possible.
`lock_splits`	boolean	No	Lock resulting split assignment.
`rebalance_existing`	boolean	No	Append new samples toward requested ratios without moving existing assignments.
`compact`	boolean	No	Request compact response.

Returns

Name	Type	Required	Description
`splits`	object	No	Split creation summary.

Rebalance is append-only. It requires unassigned samples, and a locked test split cannot receive additional test samples.

MCPmodastera_get_dataset_verification_summaryVerify dataset state

Returns database-derived sample, storage, data type, annotation, classification, split, and analysis counts.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/datasets/{dataset_id}/verification-summary/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Dataset to verify.

Returns

Name	Type	Required	Description
`total_samples`	integer	No	All samples in the dataset.
`split_counts`	object	No	Training, validation, test, and unassigned counts.
`classification`	object	No	Classification annotation and label-value counts.
`split_classification`	object	No	Classification distribution by split.
`analysis`	object	No	Current analysis state summary.

{
  "tool": "modastera_get_dataset_verification_summary",
  "arguments": {
    "dataset_id": "<dataset-id>"
  }
}

{
  "tool": "modastera_run_dataset_analysis",
  "arguments": {
    "dataset_id": "<dataset-id>"
  }
}

{
  "tool": "modastera_get_dataset_analysis",
  "arguments": {
    "dataset_id": "<dataset-id>"
  }
}

MCPmodastera_get_dataset_analysisRead dataset analysis

Returns existing dataset analysis payload for an accessible dataset.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/datasets/{dataset_id}/analysis/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Dataset to inspect.

Returns

Name	Type	Required	Description
`analysis`	object	No	Dataset analysis payload.

MCPmodastera_run_dataset_analysisStart dataset analysis

Starts background dataset analysis for an accessible dataset.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/datasets/datasets/{dataset_id}/analysis/run/

Arguments

Name	Type	Required	Description
`dataset_id`	uuid	Yes	Dataset to analyze.

Returns

Name	Type	Required	Description
`status`	object	No	Analysis start or status payload.

Poll modastera_get_dataset_analysis until analysis and distribution statuses stop computing.

MCP Reference

MCP pipeline, config, and run reference#

Pipeline tools list, create, plan, clone, fine-tune, configure, run, diagnose, summarize, report, interrupt, and inspect model versions.

{
  "tool": "modastera_list_available_ml_backend_profiles",
  "arguments": {}
}

{
  "tool": "modastera_create_pipeline",
  "arguments": {
    "name": "profile-routed-training",
    "instruction": "Train and evaluate an image classifier",
    "dataset_id": "<dataset-id>",
    "ml_backend_profile_id": "<available-profile-id>"
  }
}

MCPmodastera_list_pipelinesList pipelines

Lists pipelines/task queries visible to the API-key user, with compact mode enabled by default.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/

Arguments

Name	Type	Required	Description
`archived`	boolean	No	Filter archived pipelines.
`search`	string	No	Search text.
`task_status`	string	No	Filter by run state.
`response_status`	string	No	Filter by planning state.
`task_type`	string	No	Filter by task type.
`dataset_id`	uuid	No	Filter by dataset id.
`limit`	integer	No	Maximum rows, default 50.
`compact`	boolean	No	Return compact summaries by default.

Returns

Name	Type	Required	Description
`pipelines`	array	No	Task-query summaries.

MCPmodastera_create_pipelineCreate pipeline

Creates a pipeline/task query using the same API surface as headless REST clients.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/

Arguments

Name	Type	Required	Description
`instruction`	string	Yes	Pipeline instruction.
`name`	string	No	Optional pipeline name.
`dataset_id`	uuid	No	Optional dataset id.
`ml_backend_profile_id`	uuid	No	Optional profile id returned by list_available_ml_backend_profiles.
`context`	string	No	Optional extra context.
`resources`	array	No	Optional explicit resources.
`access`	string	No	Optional access setting.

Returns

Name	Type	Required	Description
`id`	uuid	No	Created task query id.

ML backend profile selection is creation-only. Omit the id to use backend default or no-choice routing.

{
  "tool": "modastera_list_available_ml_backend_profiles",
  "arguments": {}
}

{
  "tool": "modastera_create_pipeline",
  "arguments": {
    "name": "profile-routed-training",
    "instruction": "Train and evaluate an image classifier",
    "dataset_id": "<dataset-id>",
    "ml_backend_profile_id": "<available-profile-id>"
  }
}

MCPmodastera_plan_pipelineGenerate pipeline plan

Starts or refreshes planning for an existing pipeline/task query.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.
`instruction`	string	No	Optional replacement instruction.

Returns

Name	Type	Required	Description
`task_query`	object	No	Updated task query or accepted planning payload.

MCPmodastera_clone_pipelineClone pipeline

Copies an accessible pipeline into a new editable task query, optionally rebinding its dataset.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/clone/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Source task query id.
`name`	string	No	Optional clone name.
`dataset_id`	uuid	No	Optional replacement dataset.
`access`	private \| organization \| global	No	Optional clone visibility.

Returns

Name	Type	Required	Description
`pipeline`	object	No	New cloned task-query payload.

{
  "tool": "modastera_clone_pipeline",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "name": "editable-copy",
    "dataset_id": "<dataset-id>"
  }
}

{
  "tool": "modastera_get_pipeline_runtime_contract",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_get_pipeline_failure_details",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "include_debug": false
  }
}

{
  "tool": "modastera_get_pipeline_run_summary",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_generate_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "model_version_id": "<model-version-id>"
  }
}

{
  "tool": "modastera_get_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "response": "json",
    "model_version_id": "<model-version-id>"
  }
}

MCPmodastera_finetune_pipelineCreate fine-tune pipeline

Creates a child pipeline from a trained source pipeline and a new accessible dataset.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/finetune/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Trained source pipeline.
`dataset_id`	uuid	Yes	Dataset for fine-tuning.
`instruction`	string	No	Additional fine-tuning instruction.
`use_same_config`	boolean	No	Reuse the source config instead of replanning.
`name`	string	No	Optional child pipeline name.

Returns

Name	Type	Required	Description
`pipeline`	object	No	Created fine-tune child task query.

The source must have a trained model, attached dataset, and reusable non-classical architecture configuration.

MCPmodastera_get_pipeline_configRead pipeline config

Reads editable training and resource config for a pipeline/task query.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/config/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.

Returns

Name	Type	Required	Description
`training_config`	object	No	Editable training config.
`resource_configs`	array	No	Editable resource config entries.

{
  "tool": "modastera_get_pipeline_config",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_update_pipeline_config",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "training_epochs": 12
  }
}

{
  "tool": "modastera_update_pipeline_resource_config",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "resource_type": "architecture",
    "resource_id": "<architecture-resource-id>",
    "task_index": 0,
    "config_patch": {
      "input_size": [96, 96]
    }
  }
}

MCPmodastera_update_pipeline_configUpdate pipeline config

Updates validated training config for the next pipeline run or rerun.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/config/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.
`training_config_patch`	object	No	Patch to apply to training config.
`training_epochs`	integer	No	Convenience epoch update.
`resource_updates`	array	No	Validated resource config updates.

Returns

Name	Type	Required	Description
`config`	object	No	Updated config payload.

Config cannot be edited while a pipeline is planning or running.

MCPmodastera_update_pipeline_resource_configUpdate one resource config

Updates one training resource config for the next run or rerun.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/config/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.
`resource_type`	string	Yes	Resource type such as architecture.
`config_patch`	object	Yes	Config patch.
`task_index`	integer	No	Zero-based task index, default 0.
`resource_id`	string	No	Specific resource id.
`replace_config`	boolean	No	Replace config instead of merging.

Returns

Name	Type	Required	Description
`updated_resources`	array	No	Updated resource entries.

MCPmodastera_swap_pipeline_architectureSwap architecture

Swaps a pipeline architecture resource to a supported catalog model.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/architecture-swap/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.
`resource_id`	string	Yes	Architecture resource id.
`target_model_key`	string	Yes	Target architecture catalog key.
`override_params`	object	No	Optional parameter overrides.

Returns

Name	Type	Required	Description
`task_query`	object	No	Updated pipeline config or task query payload.

Architecture swaps require a not-started pipeline. Clone a pipeline that has already run before changing its architecture, and confirm selected-backend support before starting compute.

# Browse the architecture catalog used by pipeline config tools.
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/?include_details=true" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Inspect one public segmentation catalog entry. Catalog discovery is not a
# guarantee that every selected ML backend can execute the model.
SEGMENTATION_MODEL_KEY="EoMTDINOv2Small640"
curl "$MODASTERA_API_BASE_URL/agents/architecture-knowledgebase/$SEGMENTATION_MODEL_KEY/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# After planning, use the task-scoped related list as the replacement set.
curl "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-knowledgebase/?resource_id=$RESOURCE_ID" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY"

# Swap only a not-started pipeline and only after verifying task and runtime support.
curl -X POST "$MODASTERA_API_BASE_URL/agents/task-queries/$TASK_QUERY_ID/architecture-swap/" \
  -H "Authorization: Api-Key $MODASTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_id":"'$RESOURCE_ID'","target_model_key":"'$SEGMENTATION_MODEL_KEY'","override_params":{}}'

MCPmodastera_run_pipelineRun pipeline

Runs or reruns a pipeline through the existing task-run endpoint.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-runs/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.
`run_again`	boolean	No	Request rerun behavior when supported.
`config_patch`	object	No	Optional config patch for the run.

Returns

Name	Type	Required	Description
`task_query`	object	No	Task-run start or queue payload.

{
  "tool": "modastera_run_pipeline",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_run_pipeline",
  "arguments": {
    "pipeline_id": "<failed-first-version-pipeline-id>",
    "run_again": true
  }
}

{
  "ok": true,
  "data": {
    "model_version": { "id": "<same-model-version-id>", "version_number": 1 },
    "resume": null,
    "fresh_retry": { "reason": "first_version_missing_checkpoint" }
  },
  "error": null,
  "request_id": "<request-id>"
}

{
  "tool": "modastera_get_pipeline_status",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "include_queue": true
  }
}

{
  "tool": "modastera_get_pipeline_results",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

MCPmodastera_get_pipeline_statusRead pipeline status

Reads pipeline/task-query status and optionally includes queue state.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-progress/{task_query_id}//agents/task-queue-status/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.
`include_queue`	boolean	No	Include queue status when true.

Returns

Name	Type	Required	Description
`status`	object	No	Task query progress and optional queue payload.

MCPmodastera_resume_pipeline_evaluationResume pipeline evaluation

Queues evaluation-only resume or reconciliation for an eligible checkpointed pipeline without repeating completed training.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-runs/{task_query_id}/resume-evaluation/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Checkpointed task query id.
`model_version_id`	uuid	No	Optional eligible model version to evaluate.

Returns

Name	Type	Required	Description
`task_query`	object	No	Updated pipeline state after evaluation was queued.
`websocket_url`	string	No	Optional live task-run update URL.

The backend verifies checkpoint eligibility and may reject a pipeline with no usable trained model. Continue polling durable REST state after acceptance.

MCPmodastera_get_pipeline_resultsRead pipeline results

Returns normalized task-query results through the existing result serializer path.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/results/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.

Returns

Name	Type	Required	Description
`task_result`	object	No	Latest normalized pipeline result.

Segmentation result shapes and metrics vary by semantic, instance, or panoptic target. Interpret the exact completed model version and returned result contract.

MCPmodastera_get_pipeline_failure_detailsRead failure diagnostics

Returns sanitized failure context, diagnostic categorization, remediation steps, model-version states, and optional debug metadata.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/failure-details/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Failed task query id.
`include_debug`	boolean	No	Request debug details when the backend permits them.

Returns

Name	Type	Required	Description
`summary`	object	No	Sanitized failure message, stage, source, and exception metadata.
`diagnostics`	object	No	Category and fix suggestions.
`recommended_next_steps`	array	No	Suggested remediation steps.
`model_versions`	array	No	Model-version completion and result-snapshot state.

{
  "tool": "modastera_clone_pipeline",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "name": "editable-copy",
    "dataset_id": "<dataset-id>"
  }
}

{
  "tool": "modastera_get_pipeline_runtime_contract",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_get_pipeline_failure_details",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "include_debug": false
  }
}

{
  "tool": "modastera_get_pipeline_run_summary",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_generate_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "model_version_id": "<model-version-id>"
  }
}

{
  "tool": "modastera_get_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "response": "json",
    "model_version_id": "<model-version-id>"
  }
}

MCPmodastera_get_pipeline_runtime_contractRead runtime contract

Returns the normalized dataset, task, target, architecture, training, criterion, optimizer, metrics, transforms, explainability, and validation-warning contract.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/runtime-contract/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query to inspect.

Returns

Name	Type	Required	Description
`dataset`	object \| null	No	Dataset id, format, accessibility, sample total, and split counts.
`classification_mode`	string \| null	No	Resolved target mode.
`architecture`	object	No	Architecture metadata and config.
`validation_warnings`	array	No	Readiness warnings to resolve before running.

The planned contract and validation warnings do not by themselves prove that every selected ML backend contains the provider required by a newly cataloged model. Confirm backend support before execution.

{
  "tool": "modastera_clone_pipeline",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "name": "editable-copy",
    "dataset_id": "<dataset-id>"
  }
}

{
  "tool": "modastera_get_pipeline_runtime_contract",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_get_pipeline_failure_details",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "include_debug": false
  }
}

{
  "tool": "modastera_get_pipeline_run_summary",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_generate_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "model_version_id": "<model-version-id>"
  }
}

{
  "tool": "modastera_get_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "response": "json",
    "model_version_id": "<model-version-id>"
  }
}

MCPmodastera_get_pipeline_run_summaryRead run summary

Returns a compact post-run verification payload with runtime contract, dataset verification, model version, canonical metrics, and analysis outputs.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/run-summary/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query to summarize.

Returns

Name	Type	Required	Description
`runtime_contract`	object	No	Resolved runtime contract.
`dataset_verification`	object \| null	No	Current dataset counts and distribution.
`model_version`	object \| null	No	Latest version, status, metric, and checkpoint stages.
`canonical_metrics`	object	No	Final normalized metrics.
`failure_details`	object	No	Included when task_status is failed.

{
  "tool": "modastera_clone_pipeline",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "name": "editable-copy",
    "dataset_id": "<dataset-id>"
  }
}

{
  "tool": "modastera_get_pipeline_runtime_contract",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_get_pipeline_failure_details",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "include_debug": false
  }
}

{
  "tool": "modastera_get_pipeline_run_summary",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_generate_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "model_version_id": "<model-version-id>"
  }
}

{
  "tool": "modastera_get_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "response": "json",
    "model_version_id": "<model-version-id>"
  }
}

MCPmodastera_interrupt_pipelineInterrupt pipeline

Requests training interruption for a pipeline/task query.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-runs/{task_query_id}/interrupt-training/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.

Returns

Name	Type	Required	Description
`message`	string	No	Interrupt request result.

MCPmodastera_list_pipeline_model_versionsList model versions

Lists model versions associated with an accessible pipeline/task query.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/resources/pipeline-model-versions/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.

Returns

Name	Type	Required	Description
`model_versions`	array	No	Model version rows.

MCPmodastera_generate_pipeline_reportGenerate model-card report

Generates or refreshes a pipeline-level or model-version-specific model-card report.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/model-card-report/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Pipeline that owns the report.
`model_version_id`	uuid	No	Optional model version to scope the report.

Returns

Name	Type	Required	Description
`report`	object	No	Serialized report including report_scope and pipeline_model_version.

{
  "tool": "modastera_clone_pipeline",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "name": "editable-copy",
    "dataset_id": "<dataset-id>"
  }
}

{
  "tool": "modastera_get_pipeline_runtime_contract",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_get_pipeline_failure_details",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "include_debug": false
  }
}

{
  "tool": "modastera_get_pipeline_run_summary",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_generate_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "model_version_id": "<model-version-id>"
  }
}

{
  "tool": "modastera_get_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "response": "json",
    "model_version_id": "<model-version-id>"
  }
}

MCPmodastera_get_pipeline_reportRead model-card report

Reads the latest pipeline-level or model-version report as serializer JSON or markdown.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/agents/task-queries/{task_query_id}/model-card-report/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Pipeline that owns the report.
`response`	json \| markdown	No	Response representation; defaults to json.
`model_version_id`	uuid	No	Optional model version to scope the report.

Returns

Name	Type	Required	Description
`report`	object \| string	No	Serialized JSON report or markdown content.

{
  "tool": "modastera_clone_pipeline",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "name": "editable-copy",
    "dataset_id": "<dataset-id>"
  }
}

{
  "tool": "modastera_get_pipeline_runtime_contract",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_get_pipeline_failure_details",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "include_debug": false
  }
}

{
  "tool": "modastera_get_pipeline_run_summary",
  "arguments": {
    "pipeline_id": "<task-query-id>"
  }
}

{
  "tool": "modastera_generate_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "model_version_id": "<model-version-id>"
  }
}

{
  "tool": "modastera_get_pipeline_report",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "response": "json",
    "model_version_id": "<model-version-id>"
  }
}

MCP Reference

MCP deployments reference#

Deployment tools create deployments from pipeline model versions and activate or deactivate existing deployments.

{
  "tool": "modastera_create_deployment",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "name": "mcp-predictor",
    "selected_model_version": "<model-version-id>",
    "selected_checkpoint_stage": "best"
  }
}

{
  "tool": "modastera_set_deployment_active",
  "arguments": {
    "deployment_id": "<deployment-id>",
    "active": true
  }
}

MCPmodastera_create_deploymentCreate deployment

Creates a deployment through the existing deployment API.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/resources/deployments/

Arguments

Name	Type	Required	Description
`pipeline_id`	uuid	Yes	Task query id.
`name`	string	Yes	Deployment name.
`description`	string	No	Optional description.
`selected_model_version`	uuid	No	Model version id to deploy.
`selected_checkpoint_stage`	best \| final \| string	No	Checkpoint stage.
`use_model_card_description`	boolean	No	Use model-card description where supported.

Returns

Name	Type	Required	Description
`deployment`	object	No	Created deployment payload.

{
  "tool": "modastera_create_deployment",
  "arguments": {
    "pipeline_id": "<task-query-id>",
    "name": "mcp-predictor",
    "selected_model_version": "<model-version-id>",
    "selected_checkpoint_stage": "best"
  }
}

{
  "tool": "modastera_set_deployment_active",
  "arguments": {
    "deployment_id": "<deployment-id>",
    "active": true
  }
}

MCPmodastera_set_deployment_activeSet deployment active state

Activates or deactivates an existing deployment through the backend API.

TransportLocal stdio MCP v1AuthMODASTERA_MCP_API_KEY env API key

Backed by REST/resources/deployments/{deployment_id}/

Arguments

Name	Type	Required	Description
`deployment_id`	uuid	Yes	Deployment to update.
`active`	boolean	Yes	Desired active state.

Returns

Name	Type	Required	Description
`deployment`	object	No	Updated deployment payload.

Reference

Versioning and changelog#

The headless API surface follows semantic versioning. Breaking changes to endpoint paths, auth schemes, response shapes, async statuses, or file metadata bump the major version; backwards-compatible additions bump the minor version; documentation-only fixes bump the patch version. Pre-1.0, minor versions may include breaking changes, each called out explicitly below.

v0.4.0 July 2026

Added the public dataset clone contract for full, explicit-id, and server-side filtered selections with optional split preservation.
Documented opt-in cursor pagination for lightweight dataset summaries and task-query synopses while preserving legacy raw-array responses.
Clarified that cursor links are opaque and must be followed exactly rather than decoded or reconstructed.
Documented pinned ML backend inheritance across clones, fine-tunes, reruns, and model versions.
Added the public segmentation model catalog and guarded selection guidance for EoMT DINOv2, RF-DETR Segmentation, and RTMDet-Ins variants.
Added the narrow failed-first-version fresh-retry response contract and aligned REST and local MCP recovery guidance.
Clarified binary result operating points and sanitized GPU-memory remediation fields.

v0.3.0 July 2026

Added English and Japanese documentation homes with separate Platform, Headless & API, and Feature updates journeys.
Expanded complete platform workflows with step-by-step instructions, permission and data-safety guidance, and sanitized screenshots.
Added the bilingual July 2026 platform update and a repeatable chronological update archive.
Added production reference cards for compact pipeline summaries, annotation-engine readiness, durable Auto Annotate progress, evaluation-only checkpoint recovery, and deployment usage result media.
Revalidated the local MCP reference against the currently supported tool catalog.

v0.2.0 July 2026

Aligned dataset and pipeline examples with current serializer fields: format, instruction, and dataset_id.
Added public workflow guidance for dataset verification/preparation, COCO and mask annotations, append-only split rebalance, ML backend selection, diagnostics, run summaries, and authenticated result media.
Added pipeline- and model-version-scoped model-card report contracts.
Expanded the local MCP reference and documented its standard result envelope.

v0.1.5 June 2026

Added local stdio MCP v1 setup, trust-boundary guidance, and typed tool reference cards.
Added REST reference coverage for local file capabilities, architecture knowledgebase, pipeline config, and architecture swap workflows.
Clarified the supported public Headless and MCP coverage boundary.

v0.1.4 June 2026

Added API-key-only pipeline training guidance for generation, readiness checks, training/evaluation, WebSockets, durable polling, interruption, and final results.
Expanded task-run examples with queued responses, WebSocket event shapes, and REST recovery guidance.
Clarified that API keys are operational credentials and not account, organization, team, onboarding, or key lifecycle credentials.

v0.1.3 June 2026

Expanded curated public API reference coverage for dataset/sample CRUD, import jobs, task-query lifecycle, deployment lifecycle, prediction status, and usage inspection.
Corrected model-card report docs to distinguish JSON generation, markdown downloads, and server-sent event streaming.
Corrected annotation export docs to show dataset serializer responses with updated annotation file references.
Replaced broad pagination claims with endpoint-specific pagination and filtering guidance.

v0.1.2 June 2026

Added the OpenAPI-style API Reference generated from a curated public endpoint registry.
Added endpoint-level request, response, status-code, auth, coverage, async, caveat, and example guidance.
Added the first model to prediction walkthrough to show id handoff from dataset creation through prediction.

v0.1.1 June 2026

Expanded public workflow coverage with a coverage status matrix.
Corrected sample split examples to use training, validation, and test.
Corrected task-run creation examples to use task_query_id.
Corrected deployment creation examples to use task_query, selected_model_version, and selected_checkpoint_stage.
Clarified endpoint-specific async handles and mixed backend error response shapes.

v0.1.0 June 2026

Initial public documentation release.
API-key authentication with Api-Key and Bearer header schemes for operational APIs. Account setup and key creation remain frontend-only and outside this headless guide.
Dataset workflow: dataset CRUD, sample upload, summaries, analysis, and annotation download.
Pipeline workflow: task queries, run start, progress polling, results, model cards, and snapshot export.
Deployment workflow: model-version discovery, deployment creation, predictor calls, and metrics.
Standard async job protocol, pagination and filtering conventions, and error shapes.