---
myst:
  html_meta:
    "description": "Available content types in a Plone site can be listed and queried by accessing the /@types endpoint on any context. Access requires an authenticated user."
    "property=og:description": "Available content types in a Plone site can be listed and queried by accessing the /@types endpoint on any context. Access requires an authenticated user."
    "property=og:title": "Types"
    "keywords": "Plone, plone.restapi, REST, API, Types"
---

(types)=

# Types

```{note}
These docs are generated by code tests, therefore you will see some `test` content types appear here.
```

Available content types in a Plone site can be listed and queried by accessing the `/@types` endpoint on any context.
Access requires an authenticated user.
The `addable` key specifies if the content type can be added to the current context.
The `layouts` key specifies the defined views:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types.req
```

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types.resp
:language: http
```

The API consumer can create, read, update, and delete a content types schema.

| Verb    | URL              | Action                                             |
| ------- | ---------------- | -------------------------------------------------- |
| `POST`  | `/@types/{type}` | Add field/fieldset to content type schema          |
| `GET`   | `/@types/{type}` | Get the schema of a content type                   |
| `PATCH` | `/@types/{type}` | Update existing schema fields/fieldsets properties |
| `PUT`   | `/@types/{type}` | Replace content-type schema                        |

In addition to the above methods we can also do:

| Verb     | URL                              | Action                            |
| -------- | -------------------------------- | --------------------------------- |
| `GET`    | `/@type/{type}/{field/fieldset}` | Get field/fieldset properties     |
| `PATCH`  | `/@type/{type}/{field/fieldset}` | Update field/fieldset properties  |
| `DELETE` | `/@type/{type}/{field/fieldset}` | Remove field/fieldset from schema |

```{note}
Schema fields and fieldsets defined by [behaviors](https://5.docs.plone.org/external/plone.app.dexterity/docs/behaviors/index.html) are immutable and can NOT be changed via this RestAPI endpoint.
See {ref}`dexterity-types` control panel RestAPI endpoint for enabling and disabling behaviors.
```


## Add schema fieldset or field with `POST`

To create a new *fieldset*, send a `POST` request to the `/@types/Document` endpoint:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_post_fieldset.req
```

Response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_post_fieldset.resp
:language: http
```

To create a new *field*, send a `POST` request to the `/@types/Document` endpoint:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_post_field.req
```

Response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_post_field.resp
:language: http
```

For a complete list of available field `@types`, you can access `/@vocabularies/Fields` endpoint:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/vocabularies_get_fields.req
```

Response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/vocabularies_get_fields.resp
:language: http
```


## Get the schema with `GET`

To get the schema of a content type, access the `/@types` endpoint with the name of the content type, for example, `plone/@types/Document`:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document.req
```

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document.resp
:language: http
```

The content type schema uses the [JSON Schema](https://json-schema.org/) format.
The tagged values for the widgets are also exposed in the `properties` attribute of the schema.

For `Choice` fields, their vocabulary or source will be linked to in a `vocabulary` or `querysource` property (one or the other, never both):

- If a `querysource` property is included, that field is backed by an `IQuerysource`.
  In that case, the source's terms can't be enumerated.
  The terms need to be *queried* by issuing a request to the linked endpoint and including the user's search terms in the `?query=` parameter.
- If a `vocabulary` property is included, the field is backed by a vocabulary or another kind of iterable source.
  The terms can then be *enumerated* by issuing a request to the linked endpoint.

See {ref}`vocabularies` for details on these endpoints.

See {ref}`types-schema` for a detailed documentation about the available field types.

To get one schema **fieldset** properties, access `@types/Document/{fieldset}` endpoint:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_get_fieldset.req
```

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_get_fieldset.resp
:language: http
```

To get one schema *field* properties, access `@types/Document/{field}` endpoint:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_get_field.req
```

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_get_field.resp
:language: http
```


## Update schema with `PATCH`

To update content type schema defaults, we send a `PATCH` request to the server.
`PATCH` allows to provide just a subset of the resource, that is, the values you actually want to change.

To update one or more schema *field* properties:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_patch_properites.req
```

Response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_patch_properites.resp
:language: http
```

To change one or more *fieldset* properties:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_patch_fieldsets.req
```

Response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_patch_fieldsets.resp
:language: http
```

To update one *fieldset* settings, we can also send a `PATCH` request to `@types/Document/{fieldset}` endpoint:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_patch_fieldset.req
```

Response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_patch_fieldset.resp
:language: http
```

To update one *field* settings, we can also send a `PATCH` request to `@types/Document/{field}` endpoint:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_patch_field.req
```

Response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_patch_field.resp
:language: http
```


## Update schema with `PUT`

Use `PUT` when more changes are needed in one call, such as creating new fields or fieldsets, moving fields to a fieldset, removing multiple fields, and so on:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_put.req
```

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_put.resp
:language: http
```


## Removing schema field/fieldset with `DELETE`

Delete an existing schema *field* by sending a `DELETE` request to the URL of an existing schema field:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_delete_field.req
```

Response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_delete_field.resp
:language: http
```

Delete an existing schema *fieldset* by sending a `DELETE` request to the URL of an existing schema fieldset:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/types_document_delete_fieldset.req
```

Response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/types_document_delete_fieldset.resp
:language: http
```