> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API conventions

> Understand model references, asynchronous status, errors, pagination, and idempotency.

This page describes the conventions that the Model Distillation [Management API](https://docs.coreweave.com/model-distillation/reference/management.md) 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 project alias shown in the UI. Inference requests select the project with the `OpenAI-Project` header instead.
* 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 Weights & Biases 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:

```text theme={"system"}
{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:

```json theme={"system"}
{
  "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:

```text theme={"system"}
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.

> [accordion] API: Safe request handling
>
> Use the [Management API reference](https://docs.coreweave.com/model-distillation/reference/management.md) 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.
