> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Set a volume tag

> Creates a tag or moves it to an existing volume version.



## OpenAPI

````yaml post /v1/volumes/{volume_namespace}/{volume_name}/tags
openapi: 3.1.0
info:
  description: REST API for management of Baseten resources
  title: Baseten management API
  version: 1.0.0
servers:
  - url: https://api.baseten.co
security:
  - BearerAuth: []
paths:
  /v1/volumes/{volume_namespace}/{volume_name}/tags:
    parameters:
      - $ref: '#/components/parameters/volume_namespace'
      - $ref: '#/components/parameters/volume_name'
    post:
      summary: Sets a volume tag
      description: >-
        Setting an existing tag overwrites it. The previous version remains
        available by digest. Pass `expires_at` to set the tag's expiration time.
        Omit `expires_at` to clear any expiration time on the tag. Version or
        volume expiration still deletes the tag. Setting `head` changes the
        version used by references without a tag or digest. You cannot set
        `head` on an expiring version or supply `expires_at` when setting
        `head`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetVolumeTagRequestV1'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetVolumeTagResponseV1'
      x-codeSamples:
        - lang: bash
          source: >-
            curl --request POST \

            --url
            https://api.baseten.co/v1/volumes/{volume_namespace}/{volume_name}/tags
            \

            --header "Authorization: Bearer $BASETEN_API_KEY" \

            --data '{
              "tag": "nightly",
              "version": "head",
              "expires_at": null,
              "expected_sequence": null
            }'
        - lang: python
          source: >-
            import requests

            import os

            API_KEY = os.environ.get("BASETEN_API_KEY", "<YOUR_API_KEY>")

            url =
            "https://api.baseten.co/v1/volumes/{volume_namespace}/{volume_name}/tags"


            headers = {"Authorization": f"Bearer {API_KEY}"}


            response = requests.request(
                "POST",
                url,
                headers=headers,
                json={'tag': 'nightly', 'version': 'head', 'expires_at': None, 'expected_sequence': None}
            )


            print(response.text)
components:
  parameters:
    volume_namespace:
      schema:
        type: string
      name: volume_namespace
      in: path
      required: true
    volume_name:
      schema:
        type: string
      name: volume_name
      in: path
      required: true
  schemas:
    SetVolumeTagRequestV1:
      additionalProperties: false
      properties:
        tag:
          description: >-
            Name of the tag to set. Tags are case-sensitive. Setting a tag that
            already exists overwrites it, and the version it pointed at before
            stays reachable by digest.
          examples:
            - nightly
          pattern: ^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$
          title: Tag
          type: string
        version:
          description: >-
            Version to set the tag on. Address it with `:<tag>` for a tag,
            `@<digest>` for a full content digest or a prefix of at least 12
            hexadecimal characters, or `head` for the version a reference with
            no tag or digest resolves to.
          examples:
            - head
          title: Version
          type: string
        expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          default: null
          description: >-
            Time at which the tag expires, in ISO 8601 format, with a UTC
            offset. It must be in the future and at most ten years ahead. Omit
            it for a tag with no expiration time of its own. Omitting it also
            clears the expiration time of an existing tag. Version or volume
            expiration still deletes the tag. Do not specify it when setting
            `head`.
          title: Expires At
        expected_sequence:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          default: null
          description: >-
            Revision the volume is expected to be at. When set, the request
            fails with a conflict if the volume has changed since. Take the
            value from volume_sequence.
          title: Expected Sequence
      required:
        - tag
        - version
      title: SetVolumeTagRequestV1
      type: object
    SetVolumeTagResponseV1:
      properties:
        namespace:
          description: Namespace the volume belongs to, in lowercase.
          title: Namespace
          type: string
        volume:
          description: Name of the volume, in lowercase.
          title: Volume
          type: string
        tag:
          description: Name of the tag that was set, with its original capitalization.
          title: Tag
          type: string
        digest:
          description: Content digest of the version the tag points at, as `b3:<hex>`.
          title: Digest
          type: string
        version_ref:
          description: >-
            Full address of the tagged version, as
            `bdn:<namespace>/<volume>@<digest>`. Paste it into a config.yaml to
            pin this version, even if the tag is later set on another version.
          title: Version Ref
          type: string
        volume_sequence:
          description: Revision of the volume after the tag was set.
          title: Volume Sequence
          type: integer
        expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            Tag expiration time in ISO 8601 format. Null when the tag has no
            expiration time of its own.
          title: Expires At
      required:
        - namespace
        - volume
        - tag
        - digest
        - version_ref
        - volume_sequence
        - expires_at
      title: SetVolumeTagResponseV1
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send `Authorization: Bearer <api_key>`. The legacy `Authorization:
        Api-Key <api_key>` scheme is also accepted.

````