API conventions - CoreWeave Docs

This page describes the conventions that the Model Distillation Management API applies across its endpoints. It covers how Studio projects map to API task names, how to reference models, how to interpret asynchronous status, and how errors, pagination, and create-or-replace requests behave. Before you script against the API or build an agent that calls it, read this page so that your client handles asynchronous work and retries correctly.

Projects and tasks

Studio calls the unit you optimize a project. The Management API and trace attributes use the name task for the same resource:

API paths start with /tasks/{alias}, where alias is the proxy model name shown in Studio.
Dataset queries filter by task_version, which is the project version.
Error messages refer to tasks, for example Task 'missing' not found in entity 'your-team'.

The W&B project that stores a project’s traces is a separate resource. Set it with project and project_mode when you create a project.

Model references

Management request fields use the following format:

{provider-name}/{provider-model-id}

The provider name is lowercase and identifies stored credentials. The model ID is provider-defined and might contain additional slashes or an encoded reasoning-effort query.

Asynchronous operations

202 Accepted means that the desired state or background work was stored, not that it’s already serving or complete. Poll the returned resource:

Provider and routing deployment status must become applied at the current revision.
Datasets become ready or failed.
Relabel runs become completed, failed, or stale.
Fine-tunes become deployed or failed.
Evaluations expose live case counts and might complete with failed cases.

Errors

Management API errors use the following format:

{
  "error": {
    "message": "Task 'missing' not found in entity 'your-team'",
    "type": "not_found"
  }
}

Validation failures return 400 Bad Request for malformed JSON or query values, or 422 Unprocessable Entity for a body that doesn’t satisfy its schema. Conflicts such as referenced-provider deletion return 409 Conflict.

Pagination

Dataset entries use page-based pagination:

GET .../entries?page=1&limit=50

limit can be from 1 to 200. The response includes page, limit, total, and entries. Entry filters and evaluation sorting are JSON-encoded query parameters. When you construct requests, URL-encode the serialized JSON.

Create and replace behavior

Management write operations differ in whether a repeated request is safe. To retry safely, know which calls replace state and which create new resources:

PUT /providers/{name} creates or rotates a provider.
PUT /tasks/{alias} creates a project and returns a conflict if the project already exists.
Routing PUT replaces all targets for that version.
Dataset, fine-tune, and evaluation POST requests create new resources and might consume compute.

When you retry non-idempotent create calls after an ambiguous network failure, use client-side request IDs and your own orchestration state.

API: Safe request handling

Use the Management OpenAPI specification as the source of truth for methods, paths, schemas, and status codes. When an agent calls the API, it should do the following:

Resolve every placeholder from user-provided or previously returned values.
Show the user any request that starts paid compute or replaces routing.
Treat 202 Accepted as the beginning of work and poll the documented resource.
Preserve returned resource IDs instead of rediscovering resources by name.
Stop on an unexpected status rather than automatically retrying a create operation.

​Projects and tasks

​Model references

​Asynchronous operations

​Errors

​Pagination

​Create and replace behavior