<a id="drafts-api"></a>
<a id="api-drafts"></a>
# Drafts API

The Drafts API provides read-only access to CRF Draft objects in TrialGrid. Use it to list and retrieve drafts and the design objects they contain — folders, forms, fields, edit checks, derivations and so on.

The API is read-only: creating and updating draft objects via the API is not currently supported. For the full request and response schema of every endpoint, see the [Swagger documentation](/api/v1/documentation) (and the [Swagger and the Browseable API](swagger_and_browseable.html.md#api-swagger) page).

<a id="drafts"></a>
## Drafts

- `GET /api/v2/drafts/` — list drafts the user has access to.
- `GET /api/v2/drafts/<id>/` — retrieve a single draft.

<a id="draft-objects"></a>
## Draft objects

Each draft contains a number of design objects. Every endpoint family below follows the same three-view shape:

- `GET /api/v2/drafts/<draft_id>/<family>/` — list view.
- `GET /api/v2/drafts/<draft_id>/<family>/<id>` — detail view.
- `GET /api/v2/drafts/<draft_id>/<family>/<id>/metadata` — detail plus [Labels](../urls/labels.html.md#labels), Comments and [Custom Properties (Metadata)](../urls/properties.html.md#properties).

See [Lists, filtering and object detail](lists_and_filtering.html.md#api-lists) for the response format and the [available query parameters](lists_and_filtering.html.md#api-list-query-parameters) for filtering and expansion.

The available object families are:

| Family | URL path | Notes |
| --- | --- | --- |
| Folders | `folders` |  |
| Forms | `forms` |  |
| Fields | `fields` |  |
| Edit Checks | `checks` | Use `?include_check_step_comments=true` to include per-step comments. |
| Derivations | `derivations` |  |
| Matrices | `matrices` |  |
| Custom Functions | `custom_functions` |  |
| Data Dictionaries | `data_dictionaries` |  |
| Data Dictionary Entries | `data_dictionary_entries` |  |
| Unit Dictionaries | `unit_dictionaries` |  |
| Test Cases | `test_cases` |  |

<a id="standards-deviation-explanations"></a>
## Standards deviation explanations

For Library Drafts you can additionally retrieve explanations for standards deviations recorded against drafts that link to the library:

- `GET /api/v2/draft/<draft_id>/standards_explanations/` — list explanations.
- `GET /api/v2/draft/<draft_id>/standards_explanations/<id>/` — retrieve one.

This endpoint additionally requires the User API permission, which the user's [Organization Role](../organizations/roles.html.md#organization-roles) grants (see [User API](api_users.html.md#user-api)).

<a id="authentication-and-authorization"></a>
## Authentication and authorization

Requests must be authenticated — see [Authentication and Authorization](authentication.html.md#api-authentication). The user must have view permission on the Project that owns the Draft; Drafts in Projects the user cannot see are excluded from list responses and return `404` on detail requests.
