> ## 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](/model-distillation/reference/management) 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:

```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.

## Errors

Management API errors use the following format:

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

```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 /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.

<Accordion title="API: Safe request handling">
  Use the [Management OpenAPI specification](/openapi/model-distillation/management.openapi.yaml) 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.
</Accordion>