---
title: "PATCH samples"
method: PATCH
path: "/api/v1/samples/{id}"
---

# PATCH samples

`PATCH /api/v1/samples/{id}`

## Path parameters

- `id` string, required

## Request body

- object
  - `project` union
    - object
      - `__DOLLAR_REF__` string, uri
    - Projects
      - `$uri` string, required
      - `description` string, nullable
      - `external_id` string, nullable
      - `name` string, nullable
      - `owner` object, required
        - `__DOLLAR_REF__` string, uri
      - `permissions` string[], required
      - `project_name` string, nullable, required
      - `public` boolean
  - `tags` union
    - object[]
      - `__DOLLAR_REF__` string, uri
    - object[]
      - `name` string, required — The tag label or name. Name must be 30 characters or fewer.
  - `visibility` 'public' | 'shared' | 'private' | 'importing' | 'awaiting data' — Enum for the v1 API `visibility` attribute. Note: this is legacy and only exists for backwards-compatibility in the public v1 API.

## Response `200`

OK

- Samples
  - `$uri` string, required
  - `created_at` string, date-time, required — 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.
  - `error_msg` string, nullable — An error message if the sample failed to upload, import, or validate.
  - `filename` string, nullable — The sample filename.
  - `metadata` object, required — A metadata object.
    - `__DOLLAR_REF__` string, uri
  - `owner` object, required — The owner of the sample.
    - `__DOLLAR_REF__` string, uri
  - `primary_classification` object, nullable, required — 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.
    - `__DOLLAR_REF__` string, uri
  - `project` union — The project the sample belongs to (optional).
    - object
      - `__DOLLAR_REF__` string, uri
    - object
      - `__DOLLAR_REF__` string, uri
  - `size` integer, nullable — The size of the uploaded file in bytes.
  - `status` 'awaiting_data' | 'importing' | 'validating' | 'failed_validation' | 'available' | 'deleted', required — Enum for user-facing data status. This is a subset of `DataStatus` for the `status` attribute in the APIs.
  - `tags` object[] — An (optionally empty) array of references to Tags describing the sample. Tags are an additional unstructured organizational tool that complement Projects and Metadata records.
    - `__DOLLAR_REF__` string, uri
  - `updated_at` string, date-time, nullable — 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.
  - `visibility` 'public' | 'shared' | 'private' | 'importing' | 'awaiting data', required — Enum for the v1 API `visibility` attribute. Note: this is legacy and only exists for backwards-compatibility in the public v1 API.

---

[API](https://skmtc.net/onecodex/apis/one-codex-api-v1.md) · [All operations](https://skmtc.net/onecodex/apis/one-codex-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onecodex/one-codex-api-v1/versions/fe9d9bfc8a6a/schema)