API conventions - CoreWeave Docs

This page describes the conventions that the Model Distillation Management API applies across its endpoints. It covers how projects appear in API paths and fields, 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

The UI and the Management API both call the unit you optimize a project:

API paths start with /projects/{alias}, where alias is the proxy model name shown in the UI.
Some request and response fields keep the earlier name task: task_alias, task_id, and task_version, which is the project version. Dataset queries filter by task_version, and a dataset built from proxy traffic sets source to "task".
The earlier /tasks/... paths are deprecated. Until October 26, 2026 at 00:00 UTC, they still work, and their responses carry Deprecation, Sunset, and Link headers that name the replacement path. From that time, they return HTTP 410 with the error type endpoint_moved and a message that names the replacement path.

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.
Dataset and fine-tune deletions return 202 Accepted with a deletion operation. To check its progress, repeat the DELETE request or read the deletion-plan endpoint.

Errors

Management API errors use the following format:

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

Validation failures return 400 Bad Request for malformed JSON, in the body or in a JSON-encoded query parameter, or 422 Unprocessable Entity for a body or query value that doesn’t satisfy its schema. Conflicts such as referenced-provider deletion return 409 Conflict. A write request that arrives through the public ingress from an unsupported country or region returns 403 Forbidden with type region_restricted.

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 /projects/{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.
Dataset and fine-tune DELETE requests queue durable deletion in one request. A repeated request returns the existing operation, retries failed cleanup, or returns 204 No Content if the resource is already gone.

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

​Model references

​Asynchronous operations

​Errors

​Pagination

​Create and replace behavior