# Records A record object stores no additional data nor has any additional API methods beyond those described for all entities and classes. A record object can be used to store data in its details, that is, as a base object containing only metadata and links to other objects. ## Record API Method Specifications ### API method: `/record/new` #### Specification Creates a new record object. If `initializeFrom` is set to a hash specifying a record object, then all metadata fields of the new record created are initialized to be the same as the specified record (except for any other specified fields). #### Inputs * `project` **string** (required) ID of the project or container to which the record should belong, such as the string "project-xxxx". * `name` **string** (optional) The name of the object. Defaults to the new ID. * `tags` **array of strings** (optional) Tags to associate with the object. * `types` **array of strings** (optional) Types to associate with the object. See the [Types](https://documentation.dnanexus.com/developer/api/data-object-lifecycle/types) page for details on valid input. * `hidden` **boolean** (optional) Whether the object should be hidden. Defaults to `false`. * `properties` **mapping** (optional) Properties to associate with the object. * **key** — the property name. * **value** **string** — the property value. * `details` **mapping or array** (optional) JSON object or array that is to be associated with the object. See the [Object Details](https://documentation.dnanexus.com/developer/api/data-object-lifecycle/details-and-links) section for details on valid input. Defaults to `{}`. * `folder` **string** (optional) Full path of the folder that is to contain the new object. Defaults to `"/"`. * `close` **boolean** (optional) Whether the record should be closed immediately after creation. Defaults to `false`. * `parents` **boolean** (optional) Whether all folders in the path provided in `folder` should be created if they do not exist. Defaults to `false`. * `initializeFrom` **mapping** (optional) Indicate an existing record from which to use the metadata as default values for all fields that are not given: * `project` **string** (required) ID of the project or container containing the record to use. * `id` **string** (required) ID of the record to use. * `nonce` **string** (optional) Unique identifier for this request. Ensures that even if multiple requests fail and are retried, only a single record is created. For more information, see [Nonces](https://documentation.dnanexus.com/developer/api/nonces). #### Outputs * `id` **string** ID of the created record object, for example, a string in the form "record-xxxx". #### Errors * InvalidInput * A reserved linking string ("$dnanexus\_link") appears as a key in a hash in `details` but is not the only key in the hash * A reserved linking string ("$dnanexus\_link") appears as the only key in a hash in `details` but has a value other than a string * The `id` given under `initializeFrom` is not a valid record ID * For each property key-value pair, the size, encoded in UTF-8, of the property key may not exceed 100 bytes and the property value may not exceed 700 bytes * A `nonce` was reused in a request but other inputs had changed signifying a new and different request * A `nonce` may not exceed 128 bytes * InvalidType (`project` is not a project ID) * SpendingLimitExceeded * The `billTo` has reached its spending limit * OrgExpired * The `billTo` organization has expired * PermissionDenied (UPLOAD access required, VIEW access required for the project specified under `initializeFrom` if a record was specified) * ResourceNotFound (the specified project is not found, the path in `folder` does not exist while `parents` is false, or the specified project and/or record ID specified in `initializeFrom` are not found) ### API method: `/record-xxxx/describe` #### Specification Describes a record. A project ID can be given to request user-provided metadata from a particular project and serves as a hint. If the specified project doesn't contain the object but another accessible project does (with the user having VIEW permissions), that other project's metadata is returned instead. The response includes the project ID used for the metadata, whether it matches the hint or not. Details can also be requested via this method, but require VIEW access to be returned. Alternatively, you can use the [`/system/describeDataObjects`](https://documentation.dnanexus.com/developer/system-methods#api-method-system-describedataobjects) method to describe many data objects at once. #### Inputs * `project` **string** (optional) Project or container ID to be used as a hint for finding the object in an accessible project. * `defaultFields` **boolean** (optional) Whether to include the default set of fields in the output (the default fields are described in the "Outputs" section below). The selections are overridden by any fields explicitly named in `fields`. * Defaults to `false` if `fields` is supplied, `true` otherwise. * `fields` **mapping** (optional) Include or exclude the specified fields from the output. These selections override the settings in `defaultFields`. * **key** — the output field to include or exclude. See "Outputs" below for valid values. * **value** **boolean** — whether to include the field. The following options are deprecated (and are ignored if `fields` is present): * `properties` **boolean** (optional, deprecated) Whether the properties should be returned. Defaults to `false`. * `details` **boolean** (optional, deprecated) Whether the details should also be returned. Defaults to `false`. #### Outputs * `id` **string** The object ID, such as "record-xxxx". The following fields are included by default (but can be disabled using `fields` or `defaultFields`): * `project` **string** ID of the project or container in which the object was found. * `class` **string** The value "record". * `types` **array of strings** Types associated with the object. * `created` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which this object was created. * `state` **string** Either "open" or "closed". * `hidden` **boolean** Whether the object is hidden or not. * `links` **array of strings** The object IDs that are pointed to from this object. * `name` **string** The name of the object. * `folder` **string** The full path to the folder containing the object. * `sponsored` **boolean** Whether the object is sponsored by DNAnexus. * `tags` **array of strings** Tags associated with the object. * `modified` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which the user-provided metadata of the object was last modified. * `createdBy` **mapping** How the object was created. * `user` **string** ID of the user who created the object or launched an execution which created the object. * `job` **string** ID of the job that created the object. * Only present when a job created the object. * `executable` **string** ID of the app or applet that the job was running. * Only present when a job created the object. The following field (included by default) is available if the object is sponsored by a third party: * `sponsoredUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Indicates the expiration time of data sponsorship. This field exists only for sponsored objects and specifies a future timestamp. The following fields are only returned if the corresponding field in the `fields` input is set to `true`: * `properties` **mapping** Properties associated with the object. * **key** — the property name. * **value** **string** — the property value. * `details` **mapping or array** Contents of the object's details. #### Errors * ResourceNotFound (the specified object does not exist or the specified `project` does not exist) * InvalidInput (the input is not a hash, `project` (if supplied) is not a string, or the value of `properties` (if supplied) is not a boolean) * PermissionDenied (VIEW access required for the `project` provided (if any), and VIEW access required for **some** project containing the specified object (not necessarily the same as the hint provided)) --- # 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/introduction-to-data-object-classes/records.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.