# Trusted Research Environments API A Trusted Research Environment (TRE) is a DNAnexus entity that provides a secure, controlled environment for accessing and analyzing sensitive datasets. TREs enforce data governance policies, manage data inventories, and control user access through configurable workspace restrictions. TREs are managed by org members with the `treManagement` permission, who can create new TREs and be selected as TRE-specific admins. Each TRE is associated with a billing organization and a region, and provides data inventories, workspace policies, and role-based access controls for researchers. {% hint style="info" %} Apollo and Trusted Research Environments licenses are required to use Trusted Research Environments on the DNAnexus Platform. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information. {% endhint %} ## TRE States A TRE progresses through the following lifecycle states: * `"draft"` The initial state after creation. All TRE settings, including inventory, policies, and user management, are fully configurable. * `"active"` The TRE is operational and available for downstream use, such as data requests and project creation. Inventory cannot be changed. Policies and user management remain configurable. * `"amending"` A transitional state entered by deactivating an active TRE (appears as **Maintenance** in the UI). Inventory can be updated with a new pending version. Policies and user management remain configurable. | Setting | Configurable in draft | Configurable in amending | Configurable in active | | --------------------------------------------------------------- | --------------------- | ------------------------ | ---------------------- | | `name`, `description` | Yes | Yes | Yes | | `region`, `billTo` | Yes | No | No | | `customizedRateCard`, `customizedURL` | Yes | No | No | | [Inventory](#tre-inventory) | Yes | Yes | No | | [Policies](#tre-policies) | Yes | Yes | Yes | | [User management](#tre-roles) | Yes | Yes | Yes | | [Add or remove review steps](#data-access-request-review-steps) | Yes | No | No | | [Add or remove reviewers](#data-access-request-review-steps) | Yes | Yes | Yes | ## TRE Roles The following roles govern access and administration of a TRE: * **TRE Admin** Full administrative control over a specific TRE, including configuration, activation, and user management. TRE admins receive ADMIN access to inventory projects when the TRE is active or amending. Any org member with the `treManagement` permission (displayed as **Research Environment Management** in the Org settings UI) can create new TREs (automatically becoming TRE admin of those they create) or be added as TRE admin to TREs created by other users. * **Reviewer** Access to review [Data Access Requests](/developer/api/trusted-research-environments/data-access-requests.md). Reviewers are assigned to specific review steps and can approve or reject access requests for their assigned steps. Reviewers receive VIEW access to showcase projects and can discover the TRE in the same way as authorized users. * **Authorized User** Visibility access to discover the TRE and view its basic details and policies. Authorized users can be individual users, orgs, or the `PUBLIC` placeholder (making the TRE discoverable by all platform users). Authorized users can create [Data Access Requests](/developer/api/trusted-research-environments/data-access-requests.md). ## TRE Robot User When a TRE is activated, the platform provisions and manages a TRE robot user and a TRE working project for that TRE. These resources support internal TRE operations, including dispensal processing and temporary processing artifacts. The TRE robot user and the TRE working project are tied to the TRE billing context. Operational compute and storage for these internal workflows are billed to the same `billTo` organization as the TRE. Manage these resources only through supported TRE controls. Do not manually remove or modify TRE robot user access or TRE working project permissions. Manual changes can break dispensal and support workflows. Use `supportOrg` and `allowSupportAccess` to control troubleshooting access to the TRE working project. Keep support access disabled unless active debugging is required. ## Data Access Request Review Steps TRE admins configure data access request review steps that define the approval workflow for [Data Access Requests](/developer/api/trusted-research-environments/data-access-requests.md). Each review step has a unique identifier, a name, and a description, and is assigned one or more reviewers. When an access request is submitted, each review step must be independently resolved (approved or rejected) by a reviewer assigned to that step. The overall access request decision follows this priority: | Priority | Condition | Overall decision | | -------- | ------------------------------------------ | ---------------- | | 1 | Any review step is rejected | Rejected | | 2 | No rejected steps, but any step is pending | Pending | | 3 | All steps are approved | Approved | Review steps can only be added or removed when the TRE is in `draft` state. Reviewers can be added or removed in any state. A TRE must have at least one review step with at least one reviewer per step before it can be activated. ## TRE Inventory Each TRE manages one or more data inventories that define the datasets available to researchers. A TRE inventory includes: * **File inventory** A file, such as a TSV, associated with a project. * **Tabular data inventory** An Apollo dataset in a project associated with the hosting billTo org. * **Showcase data inventory** A dataset used for TRE discovery and preview. The project hosting the showcase dataset must be separate from the projects containing the file and tabular data inventories, because authorized users automatically gain access to the project where the showcase dataset is stored. * **Assays** An array of assay configurations, each linking entities, projects, datasets, and assay PID map databases. Each inventory has a `version` that follows [semantic versioning](https://semver.org). Inventories also have their own states: * `"active"` The inventory configuration for the current data release. * `"inactive"` A historical inventory configuration, replaced by a newer version. * `"pending"` A new inventory configuration that is not yet effective. Pending inventories become active on TRE activation. Inventory settings can only be changed when the TRE is in the `draft` or `amending` state. ## TRE Policies Policies define workspace-level restrictions that the TRE enforces on projects. Each policy key maps to an existing [project data access control](/getting-started/key-concepts/projects.md#project-data-access-controls). Policy values follow these rules: * `true` or `false` The setting is enforced at the TRE level and cannot be overridden by project admins. * `null` The TRE does not enforce this setting. Project admins can configure it independently. The available policy keys are: * `restricted` **boolean** (nullable) Controls whether users can copy data out of the project. In the UI, this policy is labeled *Copy Access*. * `protected` **boolean** (nullable) Defines which roles can delete data from the project. In the UI, this policy is labeled *Delete Access*. * `downloadRestricted` **boolean** (nullable) Controls whether users can download data from the project. In the UI, this policy is labeled *Download Access*. * `externalUploadRestricted` **boolean** (nullable) Allows users to upload files and create data from outside the DNAnexus Platform. In the UI, this policy is labeled *External Upload Access*. Requires the `externalUploadRestrictedControl` feature switch. * `previewViewerRestricted` **boolean** (nullable) Allows users to preview and download file content up to 100 KB. In the UI, this policy is labeled *File Preview*. * `databaseUIViewOnly` **boolean** (nullable) Controls whether databases are restricted to platform UI access only. When `true`, programmatic access via apps, HTTPS environments, and API requests is not allowed. In the UI, this policy is labeled *Programmatic Database Access*. * `containsPHI` **boolean** (nullable) Enables enhanced security controls for projects containing PHI, in compliance with HIPAA. Once enabled, this setting cannot be disabled. In the UI, this policy is labeled *PHI Data Protection*. Requires the `phiFeaturesEnabled` feature switch. * `httpsAppIsolatedBrowsing` **boolean** (nullable) Enforces [isolated browsing](/developer/apps/https-applications/isolated-browsing-for-https-apps.md) for all HTTPS apps, preventing data copy and download during app sessions. In the UI, this policy is labeled *Isolated Browsing Enforcement*. * `jobOutboundInternet` **boolean** (nullable) Controls whether jobs in the project can access the public internet. In the UI, this policy is labeled *Job Outbound Internet Access*. * `displayDataProtectionNotice` **boolean** (nullable) Displays a configurable data protection notice that users must acknowledge before accessing the project. In the UI, this policy is labeled *Data Protection Notice*. Requires the `dataProtectionNotice` feature switch. Changes to policies take effect immediately on TRE projects. When a policy value changes via [`/tre-xxxx/setPolicies`](#api-method-tre-xxxx-setpolicies), the corresponding project-level flag is synchronized on existing TRE projects. ## Non-Configurable Restrictions Beyond the configurable policies above, the platform enforces a set of non-configurable restrictions on all TRE projects. These restrictions cannot be overridden by project admins or TRE admins. ### General Restrictions The following operations are forbidden in all TRE projects: * Creating new apps via [`/app/new`](/developer/api/running-analyses/apps.md#api-method-app-new) is not allowed. * Creating new global workflows via [`/globalworkflow/new`](/developer/api/running-analyses/global-workflows.md#api-method-globalworkflow-new) is not allowed. * Transferring TRE projects via [`/project-xxxx/transfer`](/developer/api/data-containers/project-permissions-and-sharing.md#api-method-project-xxxx-transfer) is not allowed. * Accepting a transfer for a TRE project via [`/project-xxxx/acceptTransfer`](/developer/api/data-containers/project-permissions-and-sharing.md#api-method-project-xxxx-accepttransfer) is not allowed. * Changing the `billTo` of a TRE project via [`/project-xxxx/update`](/developer/api/data-containers/projects.md#api-method-project-xxxx-update) is not allowed. * Updating workflows in TRE projects via [`/workflow-xxxx/update`](/developer/api/running-analyses/workflows-and-analyses.md#api-method-workflow-xxxx-update) must continue to comply with TRE execution restrictions. * Inviting a user to a TRE project via [`/project-xxxx/invite`](/developer/api/data-containers/project-permissions-and-sharing.md#api-method-project-xxxx-invite) requires the invitee to be a request owner or collaborator on the Data Access Request associated with the project. * Removing dispensed data objects via [`/class-xxxx/removeObjects`](/developer/api/data-containers/folders-and-deletion.md#api-method-class-xxxx-removeobjects) is not allowed. Objects placed into a TRE project by the platform's dispensal process are protected from deletion. Dispensed data is removed only when the entire project is destroyed. For more information, see [Dispensal](/developer/api/trusted-research-environments/data-access-requests.md#dispensal). ### Clone Restrictions Cloning objects between TRE projects via [`/class-xxxx/clone`](/developer/api/data-containers/cloning.md#api-method-class-xxxx-clone) or [`/database-xxxx/relocate`](/developer/api/introduction-to-data-object-classes/databases.md#api-method-database-xxxx-relocate) is subject to the following rules: * The source and destination projects must be associated with the same Data Access Request. * Cloning between TRE projects and non-TRE projects is not allowed. ### Execution Restrictions The following restrictions apply to job execution in TRE projects. These affect [`/applet-xxxx/run`](/developer/api/running-analyses/applets-and-entry-points.md#api-method-applet-xxxx-run), [`/app-xxxx[/yyyy]/run`](/developer/api/running-analyses/apps.md#api-method-app-xxxx-yyyy-run), [`/workflow-xxxx/run`](/developer/api/running-analyses/workflows-and-analyses.md#api-method-workflow-xxxx-run), and [`/globalworkflow-xxxx[/yyyy]/run`](/developer/api/running-analyses/global-workflows.md#api-method-globalworkflow-xxxx-yyyy-run): * `allowSSH` is not allowed. * `httpsApp` can expose HTTPS only for allowlisted HTTPS apps, and only on port `443`. * `singleContext` is enforced as `true`. * `allProjects` with `UPLOAD` or above is not allowed. * `projectCreation` is not allowed. ## API Method Specifications ### API Method: `/tre-xxxx/delete` #### Specification Deletes a TRE and its associated inventory. The TRE can only be deleted when: * The TRE isn't associated with any data access requests or projects. * The TRE is in the `draft` or `amending` [state](#tre-states). * The requesting user must be a TRE admin. On deletion, authorized users are removed from the hosting project of the showcase dataset. #### Inputs None. #### Outputs * `id` **string** ID of the deleted TRE. #### Errors * InvalidState * The TRE has active access requests or projects associated with it * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be a TRE admin * The requesting user must use a full-scope token ### API Method: `/tre/new` #### Specification Creates a new TRE and places it in the `draft` state. The requesting user must be an org admin of the billing organization with the `treManagement` permission flag. On creation, the requesting user is automatically selected as a TRE admin. #### Inputs * `handle` **string** (required) A unique identifier for the TRE. The handle must be lowercase, between 3 and 63 characters long, and follow the same constraints as [org handles](/developer/api/organizations.md#api-method-org-new). * `name` **string** (required) A descriptive name for the TRE, between 1 and 256 characters long. * `description` **string** (required) Detailed information about the TRE, between 1 and 5,000 characters long. * `summary` **string** (required) A short summary of the TRE, between 1 and 500 characters long. * `billTo` **string** (required) The org ID of the data hosting organization. * `region` **string** (required) One of the allowed [DNAnexus regions](/developer/api/regions.md) for the billing org, for example, `aws:us-east-1`. * `customizedRateCard` **boolean** (optional) If true, the TRE uses the rates of the hosting org rather than standard rates. Defaults to `false`. * `customizedURL` **boolean** (optional) If true, the TRE uses a customized URL. Defaults to `false`. #### Outputs * `id` **string** ID of the newly created TRE (for example, `tre-genomics`). #### Errors * InvalidInput * `handle` must be lowercase and between 3 and 63 characters long * `name` must not be empty and must not exceed 256 characters * `description` must not exceed 5,000 characters * `region` is not one of the allowed regions for the billing org * ResourceNotFound * The org specified in `billTo` was not found * PermissionDenied * The requesting user must be an admin of the org specified in `billTo` * The requesting user must have the `treManagement` permission flag * The org must have the `treManagement` feature enabled * The requesting user must use a full-scope token ### API Method: `/tre-xxxx/update` #### Specification Updates basic information for a TRE. The set of modifiable fields depends on the current state of the TRE. In `draft` state, all fields listed below can be modified. In `active` or `amending` state, only `name` and `description` can be modified. The requesting user must be a TRE admin. #### Inputs * `name` **string** (optional) A descriptive name for the TRE, between 1 and 256 characters long. * `description` **string** (optional) Detailed information about the TRE, between 1 and 5,000 characters long. * `billTo` **string** (optional) The org ID of the data hosting organization. Only modifiable in `draft` state. * `region` **string** (optional) One of the allowed DNAnexus regions. Only modifiable in `draft` state. * `supportOrg` **string** (optional) Org ID used for support users when troubleshooting access is enabled. Only modifiable in `draft` state. * `allowSupportAccess` **boolean** (optional) Whether users from `supportOrg` can access the TRE working project for troubleshooting. * `customizedRateCard` **boolean** (optional) Whether the TRE uses the rates of the hosting org. Only modifiable in `draft` state. * `customizedURL` **boolean** (optional) Whether the TRE uses a customized URL. Only modifiable in `draft` state. #### Outputs * `id` **string** ID of the updated TRE. #### Errors * InvalidInput * `name` must not exceed 256 characters * `description` must not exceed 5,000 characters * InvalidState * Fields other than `name`, `description`, and `allowSupportAccess` cannot be modified when the TRE is in `active` or `amending` state * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be a TRE admin ### API Method: `/tre-xxxx/setInventory` #### Specification Sets the inventory for a TRE. Each TRE has a 1:N relationship with inventory objects. In `draft` state, the inventory is created or updated in place. In `amending` state, a new pending inventory is created (or updated if one already exists). Pending inventories become active on TRE activation. #### Inputs All inventory input keys are required. Use `{}` for `file`, `dataset`, or `showcase` to indicate no inventory of that type, and ensure at least one of `file` or `dataset` is non-empty. * `file` **mapping** (required) File inventory configuration. An empty mapping `{}` is valid only if `dataset` is specified. * `project` **string** (required) The project ID containing the file. * `id` **string** (required) The file ID. * `dataset` **mapping** (required) Tabular data inventory configuration. An empty mapping `{}` is valid only if `file` is specified. * `project` **string** (required) The project ID containing the dataset. * `id` **string** (required) The dataset record ID. * `showcase` **mapping** (required) Showcase data inventory configuration. An empty mapping `{}` is valid. The project specified here must be different from the projects in `file` and `dataset` because authorized users automatically receive access to the project containing the showcase dataset. * `project` **string** (required) The project ID containing the showcase dataset. * `id` **string** (required) The showcase record ID. * `dataTypeGroups` **mapping** (optional) Data type group metadata file configuration. * `project` **string** (required) The project ID containing the data type groups file. * `id` **string** (required) The file ID for data type group metadata. * `assays` **array of mappings** (required) Assay configurations. An empty array `[]` is valid. * `entity` **string** (required) The assay entity name. * `project` **string** (required) The project ID for the assay. * `workingProject` **string** (required) The working project ID used for assay processing for this inventory entry. * `dataset` **string** (required) The dataset record ID. * `assayPidMapDatabase` **string** (required) The unique name of the assay PID map database. * `version` **string** (required) The inventory version in semantic versioning format (`major.minor.patch`). Must be greater than the previous active version. #### Outputs * `id` **string** ID of the updated TRE. #### Errors * InvalidInput * Both `file` and `dataset` cannot be empty * File, dataset, showcase, or assay inventory entries must reference valid projects and objects * `dataTypeGroups` must reference a valid project and file when provided * The `assayPidMapDatabase` must reference an existing database * `version` must follow semantic versioning format and be greater than the previous active version * The requesting user must be an admin of the projects hosting the inventory * All inventory projects must have the same `billTo` as the TRE * All inventory projects must be in the same region as the TRE * InvalidState * Inventory cannot be updated when the TRE is in `active` state * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be a TRE admin ### API Method: `/tre-xxxx/setPolicies` #### Specification Sets the workspace policies for the TRE. Policies map to existing project-level restriction flags. When a policy value changes, the corresponding project-level flag is synchronized on existing TRE projects. Project creation for the TRE is temporarily blocked during synchronization to ensure consistency. The requesting user must be a TRE admin. #### Inputs * `restrictedWorkspace` **mapping** (optional) Workspace policies for TRE projects. Each key is a policy name and each value is `true`, `false`, or `null`. See [TRE Policies](#tre-policies) for the list of available policy keys. #### Outputs * `id` **string** ID of the TRE that was modified. #### Errors * InvalidInput * Unrecognized policy key in input * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be a TRE admin ### API Method: `/tre-xxxx/addTreAdmins` #### Specification Adds users as TRE admins for the specified TRE. If the TRE is in `active` or `amending` state, newly added TRE admins are granted ADMIN access to the inventory projects. The requesting user must be a TRE admin. #### Inputs * `users` **array of strings** (required) A list of user IDs to add as TRE admins. * The total number of TRE admins must not exceed 100. #### Outputs * `id` **string** ID of the TRE that was modified. #### Errors * InvalidInput * The `users` array is empty or adding these users would exceed the limit of 100 TRE admins * ResourceNotFound * The TRE was not found * One or more users in the list do not exist * PermissionDenied * The requesting user must be a TRE admin ### API Method: `/tre-xxxx/removeTreAdmins` #### Specification Removes users from the TRE admin role. If the TRE is in `active` or `amending` state, removed users lose their access to the inventory projects. The requesting user must be a TRE admin. #### Inputs * `users` **array of strings** (required) A list of user IDs to remove from the TRE admin role. #### Outputs * `id` **string** ID of the TRE that was modified. #### Errors * InvalidInput * The `users` array does not contain valid user IDs * ResourceNotFound * The TRE was not found * One or more users in the list do not exist * PermissionDenied * The requesting user must be a TRE admin ### API Method: `/tre-xxxx/addAuthorizedUsers` #### Specification Adds users or orgs to the authorized users list for the specified TRE. Authorized users can discover and view the TRE. The input list can contain user IDs, org IDs, or the `PUBLIC` placeholder. If `PUBLIC` is specified, any user on the platform can discover the TRE, and any existing individual user or org entries are replaced. The requesting user must be a TRE admin. #### Inputs * `users` **array of strings** (required) A list of user IDs, org IDs, or `PUBLIC` to add as authorized users of the TRE. #### Outputs * `id` **string** ID of the TRE that was modified. #### Errors * InvalidInput * The `users` array does not contain valid user IDs, org IDs, or `PUBLIC` * ResourceNotFound * The TRE was not found * One or more users or orgs in the list do not exist * PermissionDenied * The requesting user must be a TRE admin ### API Method: `/tre-xxxx/removeAuthorizedUsers` #### Specification Removes users or orgs from the authorized users list for the specified TRE. If `PUBLIC` is in the current list and the input does not include `PUBLIC`, removing users or orgs has no effect until `PUBLIC` is also removed. The requesting user must be a TRE admin. #### Inputs * `users` **array of strings** (required) A list of user IDs, org IDs, or `PUBLIC` to remove from the authorized users list. #### Outputs * `id` **string** ID of the TRE that was modified. #### Errors * InvalidInput * The `users` array does not contain valid user IDs, org IDs, or `PUBLIC` * ResourceNotFound * The TRE was not found * One or more users or orgs in the list do not exist * PermissionDenied * The requesting user must be a TRE admin ### API Method: `/tre-xxxx/addApplicationReviewStep` #### Specification Adds an access request review step to the TRE. Review steps define the stages in the approval workflow for [Data Access Requests](/developer/api/trusted-research-environments/data-access-requests.md). Review steps can only be added when the TRE is in `draft` state. The requesting user must be a TRE admin. #### Inputs * `reviewStepId` **string** (required) A unique identifier for the review step. Must be alphanumeric lowercase without spaces or reserved characters, matching the pattern `^[a-z0-9]{1,256}$`. * `name` **string** (required) A descriptive name for the review step, up to 256 characters. * `description` **string** (required) A description of the review step, up to 1,000 characters. #### Outputs * `id` **string** ID of the modified TRE. #### Errors * InvalidInput * `reviewStepId` does not match the required pattern or exceeds 256 characters * `name` exceeds 256 characters * `description` exceeds 1,000 characters * A review step with the same `reviewStepId` already exists * InvalidState * The TRE is not in `draft` state * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be a TRE admin * The requesting user must use a full-scope token ### API Method: `/tre-xxxx/updateApplicationReviewStep` #### Specification Updates an existing access request review step on the TRE. The requesting user must be a TRE admin. #### Inputs * `reviewStepId` **string** (required) The identifier of the review step to update. * `name` **string** (optional) The updated name for the review step, up to 256 characters. * `description` **string** (optional) The updated description for the review step, up to 1,000 characters. #### Outputs * `id` **string** ID of the modified TRE. #### Errors * InvalidInput * `reviewStepId` does not match an existing review step * `name` exceeds 256 characters * `description` exceeds 1,000 characters * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be a TRE admin * The requesting user must use a full-scope token ### API Method: `/tre-xxxx/removeApplicationReviewStep` #### Specification Removes an access request review step from the TRE. Review steps can only be removed when the TRE is in `draft` state. If the removed step's reviewers are not assigned to any other review steps, they are also removed from the showcase projects. The requesting user must be a TRE admin. #### Inputs * `reviewStepId` **string** (required) The identifier of the review step to remove. #### Outputs * `id` **string** ID of the modified TRE. #### Errors * InvalidInput * `reviewStepId` does not match an existing review step * InvalidState * The TRE is not in `draft` state * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be a TRE admin * The requesting user must use a full-scope token ### API Method: `/tre-xxxx/addApplicationReviewers` #### Specification Adds reviewers to a specific review step of the TRE. Reviewers are granted VIEW access to the showcase projects in the TRE inventories. The requesting user must be a TRE admin. #### Inputs * `reviewStepId` **string** (required) The identifier of the review step. * `users` **array of strings** (required) A list of user IDs to add as reviewers. * The total number of reviewers per step must not exceed 100. #### Outputs * `id` **string** ID of the modified TRE. #### Errors * InvalidInput * `reviewStepId` is not defined in the TRE * `users` array contains more than 100 reviewers * ResourceNotFound * The TRE was not found * One or more users in the list do not exist * PermissionDenied * The requesting user must be a TRE admin * The requesting user must use a full-scope token ### API Method: `/tre-xxxx/removeApplicationReviewers` #### Specification Removes reviewers from a specific review step of the TRE. If a reviewer is removed from all review steps, their VIEW access to the showcase projects is also revoked. The requesting user must be a TRE admin. #### Inputs * `reviewStepId` **string** (required) The identifier of the review step. * `users` **array of strings** (required) A list of user IDs to remove from the review step. #### Outputs * `id` **string** ID of the modified TRE. #### Errors * InvalidInput * `reviewStepId` is not defined in the TRE * ResourceNotFound * The TRE was not found * One or more users in the list do not exist * PermissionDenied * The requesting user must be a TRE admin * The requesting user must use a full-scope token ### API Method: `/tre-xxxx/getDataTypeGroups` #### Specification Returns the contents of the file specified in the `dataTypeGroups` section of the inventory for the TRE. #### Inputs None. #### Outputs * `results` **array of mappings** The parsed data type groups. * `name` **string** Name of the data type group. * `description` **string** Description of the data type group. * `mandatory` **boolean** Whether the data type group is mandatory. * `files` **integer** Number of files represented in this data type group. * `fields` **array of strings** Field IDs represented by this data type group. * `detailsURL` **string** URL with more details for the data type group. #### Errors * ResourceNotFound * The TRE was not found * The file configured in `dataTypeGroups` was not found * PermissionDenied * The requesting user must be a TRE admin, reviewer, or authorized user of the TRE * The requesting user must use a full-scope token * InvalidState * `dataTypeGroups` is not configured in the TRE inventory * `dataTypeGroups.project` is not configured in the TRE inventory * `dataTypeGroups.id` is not configured in the TRE inventory * The configured data type groups file does not contain valid JSON * The configured data type groups file JSON does not conform to the expected output schema ### API Method: `/tre-xxxx/describe` #### Specification Describes a TRE. The output depends on the requesting user's role. Authorized users and reviewers see a subset of basic fields, including active inventory showcase details. TRE admins see all fields. #### Inputs * `fields` **mapping** (optional) Specifies fields to include or exclude from the output. * **key** — requested output field (see "Outputs" section for valid values). * **value** **boolean** — whether to include the field. #### Outputs The following fields are available to all users who have access to the TRE (authorized users, reviewers, and TRE admins): * `id` **string** The TRE ID. * `name` **string** The descriptive name of the TRE. * `description` **string** Detailed information about the TRE. * `summary` **string** A short summary of the TRE. * `handle` **string** The unique handle for the TRE. * `region` **string** The region of the TRE. * `billTo` **string** The billing org ID. * `state` **string** The current state of the TRE. * Must be one of `"draft"`, `"active"`, or `"amending"`. * `public` **boolean** Whether the TRE is publicly discoverable. * `policies` **mapping** The TRE workspace policies. See [TRE Policies](#tre-policies). * `inventory` **string** The active inventory version identifier. * `showcaseInventory` **mapping** The active inventory details for the showcase section only. Includes the showcase project and record IDs needed to load the showcase dataset in the Cohort Browser. The following fields are available only to TRE admins: * `inventoryDetails` **array of mappings** Full historical inventory records, each including the inventory configuration, version, state, and activation timestamp. See [`/tre-xxxx/setInventory`](#api-method-tre-xxxx-setinventory) for details on inventory configuration. * `treAdmins` **array of strings** The user IDs of TRE admins. * `authorizedUsers` **array of strings** The user IDs, org IDs, or `PUBLIC` entries in the authorized users list. * `customizedRateCard` **boolean** Whether the TRE uses a customized rate card. * `customizedURL` **boolean** Whether the TRE uses a customized URL. * `supportOrg` **string** Org ID for the support org of the TRE that can be used for troubleshooting access. * `allowSupportAccess` **boolean** Whether troubleshooting access to the TRE working project is enabled for users from `supportOrg`. * `applicationReviewSteps` **mapping** The access request review step definitions and the reviewers associated with each review step. See [Data Access Request Review Steps](#data-access-request-review-steps). * `created` [**timestamp**](/developer/api.md#data-types) When the TRE was created. * `modified` [**timestamp**](/developer/api.md#data-types) When the TRE was last modified. #### Errors * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be an authorized user, reviewer, or TRE admin of the TRE ### API Method: `/tre-xxxx/activate` #### Specification Activates a TRE, transitioning it from `draft` or `amending` state to `active` state. On activation, pending inventory becomes active and the previously active inventory becomes inactive. A dispensal queue is created for the TRE. TRE admins are granted ADMIN access to the inventory projects. Authorized users are granted VIEW access to the showcase project. The TRE robot user and the TRE working project are also provisioned or synchronized for TRE operations. The requesting user must be a TRE admin. #### Inputs None. #### Outputs * `id` **string** ID of the TRE that was activated. #### Errors * InvalidState * The TRE is not in `draft` or `amending` state * The inventory or policies are not set * The TRE uses a `customizedRateCard` but the billing org does not have a rate card set * The TRE does not have at least one access request review step defined * One or more review steps do not have at least one reviewer assigned * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be a TRE admin * The requesting user must use a full-scope token ### API Method: `/tre-xxxx/deactivate` #### Specification Deactivates a TRE, transitioning it from `active` state to `amending` state. This allows TRE admins to modify the TRE configuration before reactivating it. The requesting user must be a TRE admin. #### Inputs None. #### Outputs * `id` **string** ID of the TRE that was deactivated. #### Errors * InvalidState * The TRE is not in `active` state * ResourceNotFound * The TRE was not found * PermissionDenied * The requesting user must be a TRE admin * The requesting user must use a full-scope token --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.dnanexus.com/developer/api/trusted-research-environments.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.