> ## Documentation Index > Fetch the complete documentation index at: https://developer.onecodex.com/llms.txt > Use this file to discover all available pages before exploring further. # Updating Samples In general, samples should be considered an immutable resource, but how they are shared may be updated by changing their `visibility` and `project` properties and the tags associated with them may also be changed. All other sample attributes are read-only, and the associated metadata record should be used for storing additional (mutable) structured information about a sample. **Additional authorization checks:** Note that `PATCH`ing to update the sample's visibility triggers additional account- and organization-level checks. For certain accounts (e.g., those in which PII is deposited), it may not be possible to make samples `shared` or `public`. Please [contact us](mailto:support@onecodex.com) to discuss setting additional restrictions on sample-sharing for your or your organization's account. Similarly, users may only add their samples to projects for which they have appropriate project-level permissions. ## OpenAPI ````yaml Patch /api/v1/samples/{id} openapi: 3.1.0 info: description: >- The One Codex API (v1) -- programmatic access to One Codex's suite of microbial genomics data storage, analysis, and query tools. title: One Codex API (v1) version: v1 servers: - url: https://app.onecodex.com security: - apiKeyAuth: [] paths: /api/v1/samples/{id}: patch: summary: PATCH samples operationId: patch_samples_self parameters: - in: path name: id required: true schema: type: string requestBody: content: application/json: schema: additionalProperties: false properties: project: anyOf: - properties: __DOLLAR_REF__: example: /api/v1/projects/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/projects/[a-f0-9]{16}$ type: string type: object - $ref: '#/components/schemas/projects' - type: 'null' default: null title: Project tags: anyOf: - items: properties: __DOLLAR_REF__: example: /api/v1/tags/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/tags/[a-f0-9]{16}$ type: string type: object type: array - items: properties: name: description: >- The tag label or name. Name must be 30 characters or fewer. maxLength: 30 title: Name type: string required: - name title: InlineTag type: object type: array default: [] title: Tags visibility: default: private description: >- Enum for the v1 API `visibility` attribute. Note: this is legacy and only exists for backwards-compatibility in the public v1 API. enum: - public - shared - private - importing - awaiting data title: ApiV1Visibility type: string title: SampleUpdateSchema type: object required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/samples' description: OK components: schemas: projects: properties: $uri: example: /api/v1/projects/0d77065796f8d173 pattern: ^/api/v1/projects/[a-f0-9]{16}$ readOnly: true title: $Uri type: string description: anyOf: - type: string - type: 'null' default: null title: Description external_id: anyOf: - type: string - type: 'null' default: null example: PRJ-2024-001 title: External Id name: anyOf: - type: string - type: 'null' default: null title: Name owner: properties: __DOLLAR_REF__: example: /api/v1/users/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/users/[a-f0-9]{16}$ type: string title: users type: object permissions: items: type: string title: Permissions type: array project_name: anyOf: - maxLength: 15 minLength: 3 pattern: ^[a-zA-Z0-9_-]{3,15}$ type: string - type: 'null' title: Project Name public: default: false title: Public type: boolean required: - $uri - owner - permissions - project_name title: projects type: object samples: properties: $uri: example: /api/v1/samples/0d77065796f8d173 pattern: ^/api/v1/samples/[a-f0-9]{16}$ readOnly: true title: $Uri type: string created_at: description: >- Timestamp for when the object was created on the One Codex platform, encoded as a [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp. format: date-time title: Created At type: string error_msg: anyOf: - type: string - type: 'null' default: null description: >- An error message if the sample failed to upload, import, or validate. title: Error Msg filename: anyOf: - type: string - type: 'null' default: null description: The sample filename. title: Filename metadata: description: A metadata object. properties: __DOLLAR_REF__: example: /api/v1/metadata/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/metadata/[a-f0-9]{16}$ type: string title: metadata type: object owner: description: The owner of the sample. properties: __DOLLAR_REF__: example: /api/v1/users/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/users/[a-f0-9]{16}$ type: string title: users type: object primary_classification: anyOf: - properties: __DOLLAR_REF__: example: /api/v1/classifications/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/classifications/[a-f0-9]{16}$ type: string title: classifications type: object - type: 'null' description: >- A reference to a Classification for the sample. This will typically be the [One Codex Database](https://docs.onecodex.com/en/articles/3761205-one-codex-database) or [Targeted Loci Database](https://docs.onecodex.com/en/articles/3754219-targeted-loci-database) results as appropriate. Note that samples will not have a `primary_classification` while they are still importing or being uploaded. title: Primary Classification project: anyOf: - properties: __DOLLAR_REF__: example: /api/v1/projects/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/projects/[a-f0-9]{16}$ type: string title: projects type: object - properties: __DOLLAR_REF__: example: /api/v1/projects/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/projects/[a-f0-9]{16}$ type: string type: object - type: 'null' default: null description: The project the sample belongs to (optional). title: Project size: anyOf: - type: integer - type: 'null' default: null description: The size of the uploaded file in bytes. title: Size status: description: >- Enum for user-facing data status. This is a subset of `DataStatus` for the `status` attribute in the APIs. enum: - awaiting_data - importing - validating - failed_validation - available - deleted title: UserFacingDataStatus type: string tags: default: [] description: >- An (optionally empty) array of references to Tags describing the sample. Tags are an additional unstructured organizational tool that complement Projects and Metadata records. items: properties: __DOLLAR_REF__: example: /api/v1/tags/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/tags/[a-f0-9]{16}$ type: string title: tags type: object title: Tags type: array updated_at: anyOf: - format: date-time type: string - type: 'null' default: null description: >- Timestamp for when the object was last updated on the One Codex platform, encoded as a [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp. title: Updated At visibility: description: >- Enum for the v1 API `visibility` attribute. Note: this is legacy and only exists for backwards-compatibility in the public v1 API. enum: - public - shared - private - importing - awaiting data title: ApiV1Visibility type: string required: - $uri - created_at - metadata - owner - primary_classification - status - visibility title: samples type: object securitySchemes: apiKeyAuth: in: header name: X-API-Key type: apiKey ````