<a id="api-v3-schema"></a>

# Schema discovery

The v3 API exposes its generated JSON schemas so clients can discover what each content type accepts and returns, without hand-copying field definitions. Schema discovery requires an authenticated request.

## Listing registered content types

The `/schema/` endpoint lists the content types registered with the API. Each entry has a `name` (the exact Django model label) and a `label` (a human-readable name):

```sh
curl -H "Authorization: Bearer $TOKEN" "https://example.com/api/v3/schema/"
```

```json
{
    "types": [
        {"name": "wagtailcore.Page", "label": "page"},
        {"name": "blog.BlogPage", "label": "blog page"},
        {"name": "myapp.Advert", "label": "advert"}
    ]
}
```

The content types depend on the project’s installed apps and registered models, so the exact list is specific to each site.

## Reading the schemas for a content type

The `/schema/{type_name}/` endpoint returns the JSON schemas for a single content type, split by direction: `read`, `create`, and `patch`:

- The `read` schema describes what the API returns for that type.
- The `create` schema describes what you can submit to create an instance.
- The `patch` schema describes what you can submit to update an instance.

```sh
curl -H "Authorization: Bearer $TOKEN" \
  "https://example.com/api/v3/schema/tests.BlogPage/"
```

An unknown content type returns `404`.

## How schemas are generated

Schemas are generated at runtime from the project’s models. The fields in each direction depend on the model’s `api_fields`, as described in [Configuring fields](fields.html.md#api-v3-fields).

#### NOTE
Avoid using the same model name across multiple apps. Schemas aren’t prefixed with the app label, so a `BlogPage` in two different apps would collide. Similarly, avoid using the same names for type variables, as they may cause confusion in the generated project-wide schema.

## Compared with the v2 API

The v2 API exposes fields through a dynamic `?fields=` query projection. The v3 API instead uses these fixed generated schemas and does not support `?fields=` projection. The [v2 to v3 migration guide](migration.html.md#api-v3-migration) describes the practical differences in detail.
