Ctrlk
APIDownloadsIndex of dx CommandsLegal
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ChatGPT

Project API Methods

Learn more about Project methods.

Projects

Projects serve as special containers for collaboration. Users with ADMINISTER access manage permissions within projects.

Projects and Containers

Create projects through the web user interface or use the API method /project/new. Creating a project outside an organization makes the creator responsible for storage costs and compute time for project jobs. Each project includes metadata (name, description, tags, properties) and can use boolean flags to control data modifications and copying per Project Data Access Controls.

The system creates generic data containers automatically for analysis and data sharing. Each container links to a project, user, or organization that pays storage costs.

Project Metadata

Projects can have names, descriptions, properties, and tags. The DNAnexus Platform sets properties automatically for optimal user experience.

Project API Method Specifications

API method: /project/new

Specification

Creates a new project and grants ADMINISTER access to the creating user.

Inputs

  • name string (required) The name of the project.

  • summary string (optional) A short summary of what the project contains. Defaults to "".

  • description string (optional) A longer description of the project. Defaults to "".

  • protected boolean (optional) Sets protection for the project. See details in the Project Data Access Controls section. Defaults to false.

  • restricted boolean (optional) Sets restrictions for the project. See details in the Project Data Access Controls section. Defaults to false.

  • downloadRestricted boolean (optional) Controls downloading of data outside the platform. For database objects, controls access to project data from outside DNAnexus. When set to true, previewViewerRestricted automatically defaults to true unless explicitly overridden by providing the previewViewerRestricted parameter. See details in the Project Data Access Controls section. Defaults to false.

  • previewViewerRestricted boolean (optional) When true, disables file preview and viewer for the project. This setting automatically defaults to true when downloadRestricted is true, but can be explicitly overridden by providing this parameter. See details in the Project Data Access Controls section.

    • Defaults to true when downloadRestricted is true, otherwise false.

  • externalUploadRestricted boolean (optional) When true, rejects data uploads from outside the job context. See Project Data Access Controls for details. Defaults to false.

  • httpsAppIsolatedBrowsing boolean (optional) When true, wraps httpsApp access in Isolated Browsing for project jobs. See Project Data Access Controls and Isolated Browsing for details. Defaults to false.

  • httpsAppIsolatedBrowsingOptions mapping (optional) A mapping with Isolated Browsing options that can be specified only if the httpsAppIsolatedBrowsing argument is also set to true. Mapping, if specified, may contain the following keys. Defaults to {}.

    • pasteFromLocalClipboardMaxBytes integer (optional) Must be between 0 and 262,144 bytes. Specifies the maximum size of the locally copied text that is pasteable in the remote browser. A value of 0 disables pasting of any local text into the remote browser and is the default when pasteFromLocalClipboardMaxBytes is not explicitly specified. Defaults to 0.

  • databaseUIViewOnly boolean (optional) If set to true, project members with VIEW access have their access to project databases restricted to the Cohort Browser only. Defaults to false.

  • containsPHI boolean (optional) Whether to mark the project as containing protected health information (PHI). See more details in the Project Data Access Controls section. Defaults to false.

  • destroyProtected boolean (optional) When true, prevents the project from being destroyed. See more details in the Project Data Access Controls section. Defaults to false.

  • membersListRestricted boolean (optional) When true, only project admins can list project members via /system/findProjectMembers. Non-admin members receive a PermissionDenied error when attempting to list members. See Project Data Access Controls for details. Defaults to false.

  • egressBillTo string (optional) Specifies whether to bill egress costs to the project's billTo account or the downloading user's default billTo account. Defaults to "projectBillTo".

    • Must be one of "projectBillTo" or "downloaderBillTo".

  • tags array of strings (optional) Tags to associate with the project.

  • properties mapping (optional) Properties to associate with the project.

    • key — Property name.

    • value string — Property value.

  • billTo string (optional) ID of the entity for billing any costs associated with this project. This must be the ID of the requesting user or an org of which the requesting user is a member with allowBillableActivities permission. Defaults to the billTo of the requesting user.

  • region string (optional) The region where this project is created. The region must be among the allowed regions of the project's billTo. For more information about regions, see Region. Defaults to the defaultRegion of the billTo of the project.

  • monthlyComputeLimit integer (optional, nullable) The project-level compute spending limit.

  • monthlyEgressBytesLimit integer (optional, nullable) The project-level egress spending limit.

  • monthlyStorageLimit number (optional, nullable) The project-level storage limit.

A license is required to use the Monthly Project Spending Limit for Computing and Egress and Monthly Project Spending Limit for Storage features. Contact DNAnexus Sales for more information.

  • tre mapping (optional) Associates the new project with an approved Data Access Request. When specified, project-level restriction flags are set based on TRE policies. The project region must match the TRE region.

    • treApplicationId string (required) The ID of the approved Data Access Request.

    • dispense boolean (optional) Whether to dispense the requested data into the project. Defaults to false.

    • workspaceType string (optional) The TRE workspace classification for the project. Defaults to "restricted".

Apollo and Trusted Research Environments licenses are required to use Trusted Research Environments on the DNAnexus Platform. Contact DNAnexus Sales for more information.

  • deletionRetentionEnabled boolean (optional) Whether deleted data objects move to the project's recycle bin instead of being permanently deleted. For details, see Recycle Bin. Defaults to false.

    • Can be set only when the billTo of the project has the deletionRetention license feature.

    • Defaults to true, and cannot be set to false, when the billTo sets the deletionRetentionEnforced org policy to true.

A license is required to use data retention. Contact DNAnexus Sales for more information.

Outputs

  • id string ID of the created project.

Errors

  • InvalidInput

    • name may not be empty and may not match the regex [\x00-\x1F].

    • containsPHI may not be set to false if the project is marked as containing PHI.

    • protected, restricted, downloadRestricted, previewViewerRestricted, externalUploadRestricted, destroyProtected, containsPHI, databaseUIViewOnly, httpsAppIsolatedBrowsing, membersListRestricted (if provided) are not booleans.

    • deletionRetentionEnabled (if provided) is not a boolean.

    • deletionRetentionEnabled was set to false, but the billTo sets the deletionRetentionEnforced org policy to true.

    • If httpsAppIsolatedBrowsingOptions is being set, but httpsAppIsolatedBrowsing is not being set to true.

    • httpsAppIsolatedBrowsingOptions is not a mapping or contains unrecognized keys.

    • httpsAppIsolatedBrowsingOptions.pasteFromLocalClipboardMaxBytes is not an integer or within the expected range.

    • If tre.workspaceType is specified, the supported value is "restricted".

    • The provider and tre mappings cannot both be specified.

    • If TRE policy-controlled project flags are provided in the request and the corresponding TRE policy value is non-null, the request is invalid.

    • If the TRE uses a customized rate card, billTo must be associated with the specified Data Access Request.

  • InvalidState

    • containsPHI is true, but the project is in a region that does not support PHI features.

    • If tre is specified, the Data Access Request must be in approved state.

    • If tre is specified, the project region must match the TRE region.

    • If tre is specified and the TRE uses a customized rate card, the billTo must use the same rate card as the TRE.

  • SpendingLimitExceeded

    • The billTo has reached its spending limit.

  • OrgExpired

    • The billTo organization has expired.

  • PermissionDenied

    • One of the following must be supplied: a full-scope token, a token with ADMINISTER access in all projects ("*"), or a token with the projectCreation scope set.

    • If containsPHI was set to true, the billTo of the project must have PHI features enabled.

    • If externalUploadRestricted was set to true, the billTo of the project must have the externalUploadRestrictedControl license.

    • If httpsAppIsolatedBrowsing is being set to true, the billTo of the project must have the httpsAppIsolatedBrowsingControl license.

    • If deletionRetentionEnabled was provided, the billTo of the project must have the deletionRetention license feature.

    • billTo must be either the ID of the requesting user or the ID of an org in which the requesting user is a member with allowBillableActivities permission.

    • The billTo of the invoking user is an org and the user is no longer a member of that org.

    • The region that was selected was not among the permittedRegions of the billTo.

    • If tre is specified, the requesting user must be the applicant or a collaborator on the specified Data Access Request.

API method: /project-xxxx/update

Specification

Updates the specified project with the specified options. Options not supplied in the input hash remain unchanged. For example, if a project has the protected flag set, calling this method to update the title or description without the protected field preserves the flag's value. Only members with ADMINISTER access can update the project.

Inputs

  • name string (optional) The new name of the project.

  • summary string (optional) The new summary of the project.

  • description string (optional) The new description of the project.

  • protected boolean (optional) The new value of the protected property. See more details in the Project Data Access Controls section.

  • restricted boolean (optional) The new value of the restricted property. See more details in the Project Data Access Controls section.

  • destroyProtected boolean (optional) When true, prevents the project from being destroyed. Can also be set or cleared by an ADMIN of the project's billTo organization, even without direct project membership. See more details in the Project Data Access Controls section.

  • membersListRestricted boolean (optional) When true, only project admins can list project members via /system/findProjectMembers. See Project Data Access Controls for details.

  • downloadRestricted boolean (optional) If set to true, disables the downloading of data outside of the platform. For database objects, it prohibits users from accessing the data in the project from outside DNAnexus. When changed to true on an existing project, previewViewerRestricted automatically defaults to true unless explicitly overridden by providing the previewViewerRestricted parameter in the same request.

  • previewViewerRestricted boolean (optional) If true, disables file preview and viewer for this project. When downloadRestricted is changed to true, this flag automatically defaults to true, but can be explicitly overridden by providing this parameter in the same request. See Project Data Access Controls for details.

  • externalUploadRestricted boolean (optional) If true, data uploads to this project from outside the job context are rejected. See Project Data Access Controls for details. Defaults to false.

  • httpsAppIsolatedBrowsing boolean (optional) If true, the jobs in the project have their httpsApp access wrapped in Isolated Browsing. See more details in the Project Data Access Controls and Isolated Browsing sections. Defaults to false.

  • httpsAppIsolatedBrowsingOptions mapping (optional) A mapping with Isolated Browsing options that replaces the existing httpsAppIsolatedBrowsingOptions mapping. Can be specified only if the httpsAppIsolatedBrowsing argument is also set to true. Mapping, if specified, may contain the following keys:

    • pasteFromLocalClipboardMaxBytes integer (optional) Must be between 0 and 262,144 bytes. Specifies the maximum size of the locally copied text that is pasteable in the remote browser. Value of 0 disables pasting of any local text into the remote browser and is the default when pasteFromLocalClipboardMaxBytes is not explicitly specified. Defaults to 0.

  • containsPHI boolean (optional) Set to true to mark the project as containing protected health information (PHI). See more details in the Project Data Access Controls section.

  • egressBillTo string (optional) The new value for the egressBillTo property.

    • Must be one of "projectBillTo" or "downloaderBillTo".

  • databaseUIViewOnly boolean (optional) If set to true, project members with VIEW access have their access to project databases restricted to the Cohort Browser only.

  • version integer (optional) If provided, the value must match the current project's version. Otherwise, the update applies unconditionally.

  • billTo string (optional) ID of the entity to bill for any costs associated with this project. This must be the ID of the requesting user or an org of which the requesting user is a member with allowBillableActivities permission. Updating this field resets both totalSponsoredEgressBytes and consumedSponsoredEgressBytes for the project.

  • allowedExecutables array of strings (optional, nullable) List of executable IDs permitted for root executions in this project. Set to null or omit to remove executable restrictions.

  • monthlyComputeLimit integer (optional, nullable) The project-level compute spending limit. Treat null as unlimited, which is a higher value than any non-null defaults.

  • monthlyEgressBytesLimit integer (optional, nullable) The project-level egress spending limit. Treat null as unlimited, which is a higher value than any non-null defaults.

  • monthlyStorageLimit number (optional, nullable) The project-level storage spending limit. Treat null as unlimited, which is a higher value than any non-null defaults.

  • deletionRetentionEnabled boolean (optional) Whether deleted data objects move to the project's recycle bin instead of being permanently deleted. For details, see Recycle Bin.

    • Can be set only when the billTo of the project has the deletionRetention license feature.

    • Cannot be set to false when the billTo sets the deletionRetentionEnforced org policy to true, or while the project's recycle bin is not empty.

    • Recalculated when billTo changes, based on the new billing org's license and deletionRetentionEnforced policy.

A license is required to use both the Monthly Project Spending Limit for Computing and Egress feature, and the Monthly Project Spending Limit for Storage feature. Contact DNAnexus Sales for more information.

Outputs

  • id string ID of the manipulated project.

Errors

  • ResourceNotFound

    • The specified project does not exist.

  • InvalidInput

    • The input is not a hash.

    • name (if provided) is not a nonempty string.

    • summary (if provided) is not a string.

    • description (if provided) is not a string.

    • protected, restricted, downloadRestricted, previewViewerRestricted, externalUploadRestricted, containsPHI, databaseUIViewOnly, httpsAppIsolatedBrowsing, destroyProtected, and membersListRestricted (if provided) are not booleans.

    • containsPHI (if provided) cannot be false -- marking a project as no longer containing PHI is unsupported.

    • containsPHI is true, but the project is in a region that does not support PHI features.

    • monthlyComputeLimit is not an integer and not null, or is not larger than zero.*

    • monthlyEgressBytesLimit is not an integer and not null, or is not larger than zero.*

    • monthlyComputeLimit is higher than the max value of the org default value and the current monthlyComputeLimit and the user is NOT the admin user of the org.*

    • monthlyEgressBytesLimit is higher than the max value of the org default value and the current monthlyEgressBytesLimit and the user is NOT the admin user of the org.*

    • monthlyStorageLimit is not a number, or null, or is not larger than or equal to zero.*

    • monthlyStorageLimit is higher than the max value of the org default value and the current monthlyStorageLimit, and the user is not an org admin.*

    • httpsAppIsolatedBrowsingOptions can only be specified when httpsAppIsolatedBrowsing is true.

    • httpsAppIsolatedBrowsingOptions is not a mapping or contains unrecognized keys.

    • httpsAppIsolatedBrowsingOptions.pasteFromLocalClipboardMaxBytes is not an integer or within the expected range.

    • deletionRetentionEnabled (if provided) is not a boolean.

    • deletionRetentionEnabled was set to false, but the billTo sets the deletionRetentionEnforced org policy to true.

  • InvalidState

    • version was provided and does not match the current version number found in the project.

    • The project's recycle bin is not empty, and deletionRetentionEnabled was set to false. To turn off data retention, first recover or purge the recycle bin contents.

    • The project's recycle bin is not empty, and billTo was specified. To change the billing account, first recover or purge the recycle bin contents.

    • The project's recycle bin contains only objects past their retention period, and deletionRetentionEnabled was set to false or billTo was specified. Try again after the system permanently deletes them.

    • The project is associated with a TRE and billTo was specified. Changing the billing account of a TRE project is not allowed.

    • The project is associated with a TRE and one or more project flags are enforced by TRE Policies for the project's workspace type (that is, non-null). TRE-enforced project flags cannot be overridden.

  • PermissionDenied

    • containsPHI was set to true, but the billTo of the project does not have PHI features enabled.

    • If externalUploadRestricted was set to true, the billTo of the project must have the externalUploadRestrictedControl license.

    • The new billTo must be licensed to use the externalUploadRestricted option.

    • If httpsAppIsolatedBrowsing is being set to true, the billTo of the project must have the httpsAppIsolatedBrowsingControl license.

    • The new billTo must have the httpsAppIsolatedBrowsingControl license for projects with httpsAppIsolatedBrowsing set to true.

    • If deletionRetentionEnabled was set to true, the billTo of the project must have the deletionRetention license feature.

    • billTo must be either the ID of the requesting user or the ID of an org of which the requesting user is a member with allowBillableActivities permission.

    • If the requesting user is not one of the project admins or org admins of the project billTo org.

    • The billTo org of the project does not have monthlyProjectSpendingLimit enabled.

    • The billTo org does not have monthlyProjectStorageSpendingLimit enabled.

    • The requesting user is neither an ADMIN of the project nor an ADMIN of the billTo org of the project.

    • Setting or clearing destroyProtected requires either ADMINISTER access to the project or admin privileges on the project's billTo organization.

    • Can not change the billTo of project-xxxx while the project contains a DBCluster.

    • billTo must have the region of this project in its permittedRegions:

      • If billTo is specified and the project is billed to an org, then the requesting user must be a member of the org. Depending on the restrictProjectTransfer, the requesting user may be required to be an ADMIN of the org.

* A license is required to use both the Monthly Project Spending Limit for Computing and Egress feature, and the Monthly Project Spending Limit for Storage feature. Contact DNAnexus Sales for more information.

API method: /project-xxxx/updateSponsorship

Specification

This method modifies specific forms of sponsorship in the project. It can be used to set or modify data egress sponsorship or to set or unset third-party data storage sponsorship in the project.

Data egress sponsorship, when set to a specified number of bytes, charges the project's billTo for data transferred outside of the system up to that amount, covering data downloaded by users. The billing rate varies based on the downloader's IP range. After exceeding the sponsored bytes limit, the downloader incurs the costs of downloading data from the project.

For projects with data storage sponsorship, the project's billTo covers storage charges for all objects in the project. Users or organizations with copies of these data objects in other projects receive free storage until the sponsorship period expires.

Adding data objects to a sponsored project makes them sponsored, and removing them revokes their sponsorship. An object can be sponsored in only one project at a time. Cloning an object into a sponsored project fails if another project sponsors the object.

For sponsored projects, use this method to update the expiration time or terminate sponsorship.

Inputs

  • sponsoredUntil timestamp (optional, nullable) Sets the expiration time of data storage sponsorship. Specifying null (or any time in the past) terminates the sponsorship effective immediately.

  • totalSponsoredEgressBytes integer (optional) Sets the number of bytes to be sponsored for downloads (data egress) from the DNAnexus Platform to an external IP for this project. Users may download up to the specified number of bytes from the project at no cost to themselves, with the cost charged to the project's billTo. If the new value is less than the consumed bytes, the sponsor's charges apply only to completed downloads. Setting this value overrides rather than increments the previous value. To extend the byte limit, invoke this method with a value higher than its previous value.

Outputs

  • id string ID of the project.

Errors

  • InvalidInput

    • totalSponsoredEgressBytes must be a non-negative integer.

  • InvalidState

    • A data object in the project has third-party sponsorship in another project. Remove the data objects from this project (or from the other project) before applying third-party sponsorship. When this error occurs, the error details has the form {alreadySponsored: [{id: ..., project: ...}, ...]} indicating the ID and sponsoring project of each third-party sponsored object.

    • A data object in the project has DNAnexus sponsorship.

    • The project is archived.

    • The project has a pending transfer.

  • PermissionDenied

    • If sponsoredUntil is supplied, the billTo of the project requires data sponsorship features. Contact DNAnexus Support to enable data storage sponsorship features for your account.

    • ADMINISTER access to the project is required.

    • The user's billTo must match the billTo of the project.

API method: /project-xxxx/setProperties

Specification

Sets properties on the specified project. To remove a property, set its value to JSON null instead of a string. This call updates project properties by merging the available properties with the provided input. The new values take precedence when the same key appears in both sets.

Best practice for resetting properties: Issue a describe call to get the property names, then issue a setProperties request to set those property values to null. This removes all key/value pairs. You can then replace them with new ones.

Inputs

  • properties mapping (required) Properties to modify.

    • key — Name of property to modify.

    • value string or null — Either a new string value for the property, or null to unset the property.

Outputs

  • id string ID of the manipulated project, such as "project-xxxx".

Errors

  • InvalidInput

    • The input is not a hash, properties is missing or is not a hash, or there exists at least one value in properties which is neither a string nor the JSON null.

  • ResourceNotFound

    • The specified project does not exist.

  • PermissionDenied

    • CONTRIBUTE access is required for the specified project.

API method: /project-xxxx/describe

Specification

Describes the specified project.

Inputs

  • fields mapping (optional) Restrict the output of this method to have only the provided keys in this field.

    • key — Output field to include or exclude. See the "Outputs" section for additional valid values here.

    • value boolean — Whether to include the field.

Outputs

  • id string ID of the project, such as "project-xxxx"

The following fields are included by default (but can be disabled using fields) :

  • class string The value "project".

  • name string The name of the project.

  • region string The region this project resides in. For more information about regions, see Regions.

  • summary string The summary of the project.

  • description string The description of the project.

  • version integer The version number of the project used for tracking changes to its metadata.

  • tags array of strings Tags associated with the project.

  • billTo string ID of the account to which any costs associated with this project are billed.

  • protected boolean The value of the protected flag.

  • restricted boolean The value of the restricted flag.

  • downloadRestricted boolean The value of the downloadRestricted flag.

  • previewViewerRestricted boolean The value of the previewViewerRestricted flag.

  • externalUploadRestricted boolean The value of the externalUploadRestricted flag.

  • httpsAppIsolatedBrowsing boolean The value of the httpsAppIsolatedBrowsing flag.

  • destroyProtected boolean Whether Project Deletion Protection is enabled. When true, the project cannot be destroyed until this flag is set to false.

  • httpsAppIsolatedBrowsingOptions mapping A mapping with Isolated Browsing options.

    • pasteFromLocalClipboardMaxBytes integer Must be between 0 and 262,144 bytes. Specifies the maximum size of the locally copied text that is pasteable in the remote browser. Value of 0 disables pasting of any local text into the remote browser and is the default when pasteFromLocalClipboardMaxBytes is not explicitly specified.

  • containsPHI boolean Whether the project is marked as containing protected health information (PHI) and subject to additional restrictions to ensure security and compliance.

  • databaseUIViewOnly boolean If set to true, project members with VIEW access have their access to project databases restricted to the Cohort Browser only.

  • membersListRestricted boolean The value of the membersListRestricted flag.

  • created timestamp Time at which this project was created.

  • createdBy mapping How the project was created.

    • user string ID of the user who created the project.

    • job string ID of the job that created the project.

      • Only present when the project was created by a job.

    • executable string ID of the applet or app that the job was running.

      • Only present when the project was created by a job.

  • modified timestamp Time at which this project was last updated.

  • level string The highest permission level that the requesting user has.

  • dataUsage number Data usage in GB (not including sponsored data or DBCluster storage). Value updates can experience delays after project changes.

  • defaultInstanceType string Default instance type for apps to run on.

  • sponsoredDataUsage number Sum of DNAnexus-sponsored and third-party sponsored data usage in GB, excluding DBCluster storage. For third-party sponsored projects, objects appear in dataUsage rather than sponsoredDataUsage since the project's billTo handles the billing. Value updates can experience delays after container changes.

  • sponsoredUntil timestamp Indicates that the project is sponsored by its billTo until the specified time. The specified time must be in the future.

    • Only present when the project is sponsored.

  • pendingTransfer string (nullable) If applicable, account ID that has been invited to take the project. Otherwise null.

  • totalSponsoredEgressBytes integer The total number of bytes sponsored for this project over the lifetime of the project's current billTo. If this value is less than consumedSponsoredEgressBytes, the downloader is billed for additional downloads instead of the sponsor.

  • consumedSponsoredEgressBytes integer The number of sponsored bytes used to transfer files from this project out of the DNAnexus Platform, over the lifetime of the project's current billTo.

  • allowedExecutables array of strings If present, the set of executable IDs that are allowed to run as root executions in this project.

  • displayDataProtectionNotice boolean Whether a data protection notice is displayed for the project.

  • tre mapping TRE association details. Only present when the project is associated with a Trusted Research Environment.

    • treId string ID of the TRE.

    • treApplicationId string ID of the Data Access Request used to create the project.

    • workspaceType string The TRE workspace classification of the project. Defaults to "restricted".

    • inventoryVersion string The inventory version active when the project was dispensed.

      • Only present on projects created with dispensal enabled (tre.dispense: true at project creation).

The following fields (included by default) are available if the requesting user has UPLOAD+ access to the project:

  • atSpendingLimit boolean Indicates whether the billTo of the project is at their spending limit (and therefore functionality is restricted).

The following fields (included by default) are available if the requesting user has permissions to view the pricing model of the billTo of the project:

  • storageCost number Storage cost (in dollars) of the project per month based on data usage (the total cost of an account's projects may be smaller than the sum of this value over all projects if any objects are shared between the projects).

The following fields are only returned if the corresponding field in the fields input is set to true:

  • folders array of strings List of all folders in the project.

  • objects integer The number of visible objects in the project.

  • permissions mapping Who has permissions to access this project.

    • key — Entity ID. A user or org ID.

    • value string — The permission level.

      • Must be one of "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER".

  • egressBillTo string The value of the egressBillTo property.

  • appCaches mapping List of containers attached to the project that have been created for running apps.

    • key — App ID.

    • value string — ID of the app ID's project cache container.

  • properties mapping Properties associated with the project.

    • key — Property name.

    • value string — Property value.

  • fileUploadParameters mapping Information about what part sizes and numbers are used to upload files in this project. See the section Limits on Parts of the Files API for more information about interpreting this. A mapping with the following key/value pairs:

    • minimumPartSize integer Minimum part size, in bytes, that applies to all parts except the part with the highest index. (Clients may assume that if emptyLastPartAllowed is false, then minimumPartSize is at least 1, that is, the constraint on the last part is no stronger than the constraint on previous parts.)

    • maximumPartSize integer Maximum part size, in bytes.

    • emptyLastPartAllowed boolean If true, then the minimum number of parts is 1 and the part with the highest index may contain 0 bytes. If false, then the minimum number of parts is 0 and the part with the highest index must contain at least 1 byte. All parts other than the part with the highest index must still have minimum size given by minimumPartSize. If true, then the client can upload a 0-byte file by invoking /file-xxxx/upload once with a part of size 0. If false, then the client can upload a 0-byte file by not invoking /file-xxxx/upload at all.

    • maximumNumParts integer The maximum number of parts that may be uploaded (also equal to the largest permissible part index).

    • maximumFileSize integer The maximum size of the file, in bytes.

  • availableInstanceTypes mapping Instances available in the project for apps and applets to run on.

    • key — Instance type.

    • value mapping — Contains information on the instance type.

      • numCores integer Number of cores.

      • totalMemoryMB integer Memory size in MB.

      • ephemeralStorageGB integer Storage size in GB.

      • os array of mappings Supported operating systems. Each value is a mapping with the following fields, indicating one of the supported operating systems:

        • distribution string The Linux operating system distribution. Must match the distribution of the run specifications of the app or the applet to be run.

        • release string The Linux operating system release. Must match the release of the run specifications of the app or the applet to be run.

      • rank integer Ranking of the instance type based on its value, with a rank value of 1 being the least valuable.

  • metadataCapacity number Value of metadataCapacity. Between 0 and 1, with a 1 indicating the project is at maximum metadata capacity and cannot accept additional metadata.

  • supportAccess mapping (nullable) Information about DNAnexus Support access granted to the project via /project-xxxx/invite, or null if no DNAnexus Support invitation has been made.

    • enabled boolean Whether a DNAnexus Support organization has access to the project.

    • supportOrgId string ID of the DNAnexus Support organization granted access. The organization ID has the form org-dnanexus_support_<project billTo's org-handle>, for example org-dnanexus_support_org-abc.

    • grantedAt timestamp Time at which DNAnexus Support access was granted.

    • grantedBy string ID of the user who granted DNAnexus Support access.

    • expiresAt timestamp Time at which DNAnexus Support access expires and is automatically revoked.

    • revokedAt timestamp Time at which DNAnexus Support access was revoked before its scheduled expiration.

      • Only present when access was revoked before expiresAt.

    • revokedBy string ID of the user who revoked DNAnexus Support access before its scheduled expiration.

      • Only present when access was revoked before expiresAt.

The following fields are only returned if the corresponding field in the fields input is set to true and the billTo of the project has the dataCatalog feature enabled:

  • dataCatalog string (nullable) The ID of the data catalog the project belongs to, or null if the project is not associated with a data catalog.

The following fields (included by default) are available if the requesting user has permissions to view the pricing model of the billTo of the project and the billTo of the project has monthlyProjectSpendingLimit enabled:

  • monthlyComputeLimit integer (nullable) The current monthly project spending limit for compute.

  • monthlyEgressBytesLimit integer (nullable) The current monthly project spending limit for egress.

  • currentMonthComputeAvailableBudget number (nullable) The current month's project available spending budget for compute.

  • currentMonthEgressBytesAvailableBudget number (nullable) The current month's project available spending budget for egress.

  • currentMonthComputeUsage number The current month's project usage for compute.

  • currentMonthEgressBytesUsage number The current month's project usage for egress.

The following fields (included by default) are available if the requesting user has permissions to view the pricing model of the billTo of the project and the billTo of the project has monthlyProjectStorageSpendingLimit enabled:

  • monthlyStorageLimit number (nullable) The current monthly project spending limit for storage

  • currentMonthStorageAvailableBudget number (nullable) The current month's project available spending budget for storage

  • currentMonthExpectedStorageUsage number The current month's projected usage for storage

Licenses are required for both the Monthly Project Spending Limit for Computing and Egress feature, and the Monthly Project Spending Limit for Storage feature. Contact DNAnexus Sales for more information.

The following fields (included by default) are available if the billTo of the project has the deletionRetention feature enabled. For more information, see Recycle Bin:

  • deletionRetentionEnabled boolean Whether deleted data objects in this project move to the project's recycle bin instead of being permanently deleted.

  • deletionRetentionEnforced boolean The value of the billTo org's deletionRetentionEnforced policy. When true, deletionRetentionEnabled cannot be set to false for this project.

  • deletionRetentionPeriod integer The number of days that deleted data objects are kept in the recycle bin, taken from the billTo org's deletionRetentionPeriod policy.

A license is required to use data retention. Contact DNAnexus Sales for more information.

Errors

  • ResourceNotFound

    • The specified project does not exist.

  • InvalidInput

    • Input is not a hash, or fields if present, is not a hash or has a non-boolean key.

  • PermissionDenied

    • Must have at least VIEW access to the project, be the billTo with a full-scope token (if the billTo is a user) , or be an admin of the billTo with a full-scope token (if the billTo is an org).

API method: /project-xxxx/destroy

Specification

Destroys the specified project. All objects in the project are removed.

For jobs not in a terminal state (not done, failed, or terminated), the system throws an InvalidState error unless the terminateJobs option is set to force termination.

In a project with data retention turned on, remove all data from the project and purge the recycle bin before you destroy it. To purge the recycle bin, use /project-xxxx/purgeRecycleBinObjects.

Inputs

  • terminateJobs boolean (optional) Whether to force the destruction of the project and terminate all non-terminal jobs. Defaults to false.

Outputs

  • id string ID of the manipulated project.

Errors

  • ResourceNotFound

    • The specified project does not exist.

  • PermissionDenied

    • The requesting user is neither an ADMIN of the project nor an ADMIN of the billTo org of the project.

  • InvalidInput

    • terminateJobs (if present) is not a boolean.

  • InvalidState

    • terminateJobs was not set to true, and there still remain jobs which are not in a terminal state.

    • The project is sponsored (sponsorship must be terminated before the project may be destroyed).

    • The project's destroyProtected flag is set to true. The project must have destroyProtected explicitly set to false before it can be destroyed.

    • The project has data retention turned on and still contains data. To destroy the project, first remove all its data.

    • The project's recycle bin is not empty. To destroy the project, first purge the recycle bin contents.

    • The project's recycle bin contains only objects past their retention period. Try again after the system permanently deletes them.

API method: /project-xxxx/listRecycleBin

Specification

Lists the data objects in the project's recycle bin, including hidden linked objects that moved into the recycle bin with a deleted object. Objects past their purgeAt time are not listed. For more information, see Recycle Bin.

Inputs

This method takes no input fields.

Outputs

  • id string ID of the project.

  • objects array of mappings The objects in the recycle bin. Each mapping contains:

    • id string ID of the data object.

    • class string The class of the data object, such as "file" or "record".

    • name string The name of the data object.

    • deletedAt timestamp Time at which the object was deleted.

    • purgeAt timestamp Time after which the object is permanently deleted.

    • previousFolder string The folder the object was deleted from.

Errors

  • ResourceNotFound

    • The specified project does not exist.

  • InvalidState

    • Data retention is not turned on for the project.

  • PermissionDenied

    • VIEW access is required.

This method may return standard API errors.

API method: /project-xxxx/recoverObjects

Specification

Restores data objects from the project's recycle bin. Each object returns to the folder recorded in its previousFolder metadata, and any missing folders on that path are recreated. Hidden linked objects that moved into the recycle bin with a requested object are restored with it.

If any requested object cannot be recovered, none of the objects in the request are recovered.

To recover a DBCluster, use /dbcluster-xxxx/recover.

Inputs

  • objects array of strings (required) IDs of the data objects to recover. Must be nonempty and must contain at most 10,000 IDs.

Outputs

  • id string ID of the project.

  • dataObjects array of strings IDs of the recovered data objects, including hidden linked objects recovered with them.

Errors

  • InvalidInput

    • objects is missing, is not an array of nonempty strings, or is empty.

    • objects contains more than 10,000 IDs.

    • objects contains a DBCluster ID.

  • ResourceNotFound

    • The specified project does not exist.

    • One of the specified objects is not in the project's recycle bin.

  • InvalidState

    • Data retention is not turned on for the project.

    • One of the specified objects is past its retention period.

  • PermissionDenied

    • CONTRIBUTE access is required.

This method may return standard API errors.

API method: /project-xxxx/purgeRecycleBinObjects

Specification

Purges data objects from the project's recycle bin before their retention period ends. Hidden linked objects that moved into the recycle bin with a requested object are purged with it. Purged objects cannot be recovered.

Purging permanently removes the project's links to the specified objects. Copies of those objects in other projects remain unaffected. The underlying file data is permanently deleted from platform storage only when the purged object is the last remaining link. For more information about how data objects and copies share platform data, see Platform IDs and Data Objects in Projects.

Each object is processed independently. Objects that cannot be purged are listed in failed, and the rest are purged.

Inputs

  • objects array of strings (required) IDs of the data objects to purge. Must be nonempty and must contain at most 10,000 IDs.

Outputs

  • id string ID of the project.

  • scheduled array of strings IDs of the objects scheduled for permanent deletion, including hidden linked objects scheduled with them.

  • failed array of mappings The objects that were not scheduled. Each mapping contains:

    • id string ID of the object.

    • reason string Why the object was not scheduled.

      • Must be one of "notFoundInRecycleBin" or "expired".

Errors

  • InvalidInput

    • objects is missing, is not an array of nonempty strings, or is empty.

    • objects contains more than 10,000 IDs.

  • ResourceNotFound

    • The specified project does not exist.

  • InvalidState

    • Data retention is not turned on for the project.

    • The request covers more than 10,000 objects, counting hidden linked objects. To purge them, split the request into smaller batches.

  • PermissionDenied

    • ADMINISTER access is required.

This method may return standard API errors.

API method: /project-xxxx/addTags

Specification

Tags the project with the given strings. Previously applied tags remain unaffected.

Inputs

  • tags array of strings (required) Tags to be added.

Outputs

  • id string ID of the manipulated project.

Errors

  • ResourceNotFound

    • The specified project does not exist.

  • InvalidInput

    • tags is not present or is not a list of nonempty strings.

  • PermissionDenied

    • CONTRIBUTE access is required.

API method: /project-xxxx/removeTags

Specification

Removes the given tags from the project. Tags that do not exist have no effect when removed.

Inputs

  • tags array of strings (required) Tags to be removed.

Outputs

  • id string ID of the manipulated project.

Errors

  • ResourceNotFound

    • The specified project does not exist.

  • InvalidInput

    • tags is not present or is not a list of nonempty strings.

  • PermissionDenied

    • CONTRIBUTE access is required.

API method: /project-xxxx/countRootExecutions

Specification

Counts the root executions in this project that were created within the last 7 days by state. Returns an object whose keys are execution states, and whose values are the number of root executions that are in that state.

Inputs

  • None

Outputs

  • key — State.

  • value integer — Number of root executions in that state.

Errors

  • ResourceNotFound

    • The specified project does not exist.

  • PermissionDenied

    • VIEW access is required.

API method: /system/getProjectTags

Specification

Returns the tags on all visible projects. The initial implementation includes only public projects.

Inputs

  • None

Outputs

  • key — Tag.

  • value integer — Number of projects with the tag.

Errors

No errors are returned.

API method: /project-xxxx/archive

A license is required to use the DNAnexus Archive Service. Contact DNAnexus Sales for more information.

Specification

Requests that a set of files be archived on the platform. For each file, if this is the last copy of a file to have archival requested, this triggers the full archival of the object. Otherwise, the file receives an archival state marking that archival has been requested.

Inputs

  • files array of strings (optional) A subset list of files to archive. Example: '{"files": ["file-xxxx", "file-yyyy"], "allCopies": true}'. Mutually exclusive with folder.

  • folder string (optional) The folder that contains all files to archive. Example: '{"folder" : "/folder1"}'. Mutually exclusive with files and required when files is not present.

  • recurse boolean (optional) If true, archive all files in subfolders of folder. If false, only archive files in folder. folder must be set. Defaults to true.

  • allCopies boolean (optional) This flag forces the transition of files into the archived state. The requesting user must be the ADMIN of the project billTo org. If true, archive all the copies of files in projects with the same billTo org. If false, only the copy of the file in the current project transitions to the archival state, while other copies of the file in other projects with the same billTo org remain in the live state. Defaults to false.

While files and folder are optional on their own, one of them is required.

Outputs

  • id string The id of the project.

  • count integer The number of files to be tagged for archival.

Errors

  • InvalidInput

    • If both files and folder are provided.

  • InvalidState

    • One or more files are in an "open" ("non-closed") state.

    • One or more files are being used as bundledDepends for applets.

  • ResourceNotFound

    • The specified project does not exist.

    • A file or folder does not exist.

  • PermissionDenied

    • CONTRIBUTE access is required, or the requesting user must have the archivalManagement permission for org-wide operations.

    • Must be an org ADMIN of the project billTo org, or a MEMBER with the archivalManagement permission, to use the allCopies option.

API method: /project-xxxx/unarchive

A license is required to use the DNAnexus Archive Service. Contact DNAnexus Sales for more information.

Specification

Requests that a set of files be unarchived on the platform. This is an asynchronous command. The requested copy transitions to the live state while all other copies move to the archival state.

Inputs

  • files array of strings (optional) A subset list of files to unarchive. Mutually exclusive with folder and required when folder is not present.

  • folder string (optional) The folder that contains all files to unarchive. Mutually exclusive with files and required when files is not present.

  • recurse boolean (optional) If true, unarchive all files in subfolders of folder. If false, only unarchive files in folder. folder must be set. Defaults to true.

  • rate string (optional) The speed at which all files in this request are unarchived. Valid entries:

    • For Azure regions, the accepted values are "Standard" and "Expedited". For details about retrieval times, see Rehydration priority in the Azure documentation.

    • For AWS regions, the accepted values are "Standard" and "Bulk". For details about retrieval times, see Understanding archive retrieval options in the AWS documentation.

  • dryRun boolean (optional) If true, only display the output of the API call without executing the unarchival process. Defaults to false.

Outputs

  • files integer The number of files to be unarchived.

  • size integer The size of the data, in GB, to be unarchived.

  • cost number The total cost, in millidollars, to be charged for the unarchival request.

Errors

  • InvalidInput

    • If both files and folder are provided.

  • ResourceNotFound

    • The specified project does not exist.

    • A file or folder does not exist.

  • PermissionDenied

    • CONTRIBUTE access is required, or the requesting user must have the archivalManagement permission for org-wide operations.

Last updated

Was this helpful?