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

# Finalize a release upload for an unscoped volume



## OpenAPI

````yaml /spec/0.1.0-rc.1/api-reference/bibliotheca.openapi.json post /api/v1/volumes/{name}/uploads/{uploadId}/finalize
openapi: 3.1.1
info:
  title: Agent Volumes Bibliotheca API
  version: 0.1.0-rc.1
servers: []
security: []
paths:
  /api/v1/volumes/{name}/uploads/{uploadId}/finalize:
    post:
      summary: Finalize a release upload for an unscoped volume
      operationId: finalizeVolumeUpload
      parameters:
        - in: path
          name: name
          required: true
          schema:
            $ref: '#/components/schemas/NameSegment'
        - in: path
          name: uploadId
          required: true
          schema:
            type: string
        - in: header
          name: Idempotency-Key
          required: false
          description: >-
            Preferred portable idempotency key for finalize. If an operation
            also accepts a body idempotencyKey, the two values MUST match
            exactly.
          schema:
            type: string
      responses:
        '201':
          description: Published release metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/release-upload-finalize.schema'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - bearerAuth: []
components:
  schemas:
    NameSegment:
      type: string
      maxLength: 128
      pattern: ^(?!.*--)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$
    release-upload-finalize.schema:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: >-
        https://agentvolumes.org/spec/0.1.0-rc.1/schemas/release-upload-finalize.schema.json
      title: Agent Volumes Release Upload Finalize Result
      type: object
      additionalProperties: false
      required:
        - uploadId
        - release
        - detailUrl
      properties:
        uploadId:
          type: string
          minLength: 1
        release:
          allOf:
            - $ref: '#/components/schemas/release-metadata.schema'
            - type: object
              required:
                - dist
              properties:
                dist: {}
                status:
                  type: object
                  required:
                    - state
                  properties:
                    state:
                      type: string
                      const: available
        detailUrl:
          type: string
          format: uri-reference
    release-metadata.schema:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: >-
        https://agentvolumes.org/spec/0.1.0-rc.1/schemas/release-metadata.schema.json
      title: Agent Volumes Release Metadata
      type: object
      additionalProperties: false
      required:
        - name
        - version
        - purl
        - integrity
        - status
      allOf:
        - if:
            properties:
              status:
                type: object
                properties:
                  state:
                    enum:
                      - available
                      - yanked
                required:
                  - state
            required:
              - status
          then:
            properties:
              dist: true
            required:
              - dist
        - if:
            properties:
              status:
                type: object
                properties:
                  state:
                    enum:
                      - blocked
                      - tombstoned
                      - unavailable
                required:
                  - state
            required:
              - status
          then:
            not:
              required:
                - dist
      properties:
        name:
          $ref: '#/components/schemas/volumeName'
        version:
          $ref: '#/components/schemas/semver'
        purl:
          $ref: '#/components/schemas/releasePurl'
        integrity:
          $ref: '#/components/schemas/digest'
        status:
          $ref: '#/components/schemas/versionStatus'
        externalDependencies:
          type: array
          description: >-
            Declaration-only external package dependency metadata derived from
            the release manifest. These records are not resolved dependency
            inventory, lockfile content, provenance material, scanner findings,
            or vulnerability evidence.
          items:
            $ref: '#/components/schemas/externalDependencyDeclaration'
          uniqueItems: true
        dist:
          oneOf:
            - type: object
              additionalProperties: false
              required:
                - source
                - mediaType
                - url
              properties:
                source:
                  type: string
                  const: cdn
                mediaType:
                  type: string
                  const: application/gzip
                url:
                  type: string
                  format: uri
                  description: >-
                    Opaque portable download locator for hosted .tar.gz archive
                    bytes. Clients verify normalized-file-tree integrity after
                    retrieval.
            - type: object
              additionalProperties: false
              required:
                - source
                - repository
                - ref
              properties:
                source:
                  type: string
                  const: git
                repository:
                  type: string
                  format: uri
                ref:
                  type: string
                  minLength: 1
      $defs:
        volumeName:
          type: string
          maxLength: 194
          pattern: >-
            ^(@(?!.*--)[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?/)?(?!.*--)[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$
        semver:
          type: string
          pattern: >-
            ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$
        releasePurl:
          type: string
          pattern: >-
            ^pkg:volume/(?:%40(?![a-z0-9-]*--)[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?/)?(?![a-z0-9-]*--)[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?@(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$
        digest:
          type: string
          pattern: ^sha256:[a-f0-9]{64}$
        versionStatus:
          type: object
          additionalProperties: false
          required:
            - state
          properties:
            state:
              type: string
              enum:
                - available
                - yanked
                - tombstoned
                - blocked
                - unavailable
            reason:
              type: string
        externalDependencyDeclaration:
          type: object
          additionalProperties: false
          required:
            - declarationKey
            - purl
            - constraint
            - purpose
          properties:
            declarationKey:
              $ref: '#/components/schemas/externalDependencyDeclarationKey'
            purl:
              type: string
              pattern: >-
                ^pkg:(?!volume(?:/|$))[A-Za-z][A-Za-z0-9.+-]*/[^@#]+(?:\?[^#]+)?$
            constraint:
              type: string
              pattern: ^vers:[A-Za-z][A-Za-z0-9.-]*/\S+$
            purpose:
              type: string
              anyOf:
                - enum:
                    - runtime
                    - build
                    - development
                    - test
                    - optional
                    - peer
                    - source
                    - documentation
                    - other
                - pattern: ^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+:[a-z][a-z0-9-]*$
            components:
              type: array
              items:
                type: string
                pattern: ^(?!.*--)[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$
              minItems: 1
              uniqueItems: true
        externalDependencyDeclarationKey:
          type: string
          pattern: ^av-extdep-v1:sha256:[a-f0-9]{64}$
    ProblemDetails:
      oneOf:
        - $ref: '#/components/schemas/AuthenticationRequiredProblem'
        - $ref: '#/components/schemas/AuthorizationFailedProblem'
        - $ref: '#/components/schemas/NotFoundProblem'
        - $ref: '#/components/schemas/ValidationFailedProblem'
        - $ref: '#/components/schemas/InvalidManifestProblem'
        - $ref: '#/components/schemas/InvalidArchiveProblem'
        - $ref: '#/components/schemas/IdentityMismatchProblem'
        - $ref: '#/components/schemas/VersionConflictProblem'
        - $ref: '#/components/schemas/DigestMismatchProblem'
        - $ref: '#/components/schemas/SubjectBindingMismatchProblem'
        - $ref: '#/components/schemas/InconsistentRegistryStateProblem'
        - $ref: '#/components/schemas/UploadExpiredProblem'
        - $ref: '#/components/schemas/MissingUploadedBytesProblem'
        - $ref: '#/components/schemas/InvalidUploadStateProblem'
        - $ref: '#/components/schemas/IdempotencyConflictProblem'
        - $ref: '#/components/schemas/PayloadTooLargeProblem'
        - $ref: '#/components/schemas/UnsupportedMediaTypeProblem'
        - $ref: '#/components/schemas/PermissionEscalationProblem'
        - $ref: '#/components/schemas/RateLimitedProblem'
    volumeName:
      type: string
      maxLength: 194
      pattern: >-
        ^(@(?!.*--)[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?/)?(?!.*--)[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$
    semver:
      type: string
      pattern: >-
        ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$
    releasePurl:
      type: string
      pattern: >-
        ^pkg:volume/(?:%40(?![a-z0-9-]*--)[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?/)?(?![a-z0-9-]*--)[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?@(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$
    digest:
      type: string
      pattern: ^sha256:[a-f0-9]{64}$
    versionStatus:
      type: object
      additionalProperties: false
      required:
        - state
      properties:
        state:
          type: string
          enum:
            - available
            - yanked
            - tombstoned
            - blocked
            - unavailable
        reason:
          type: string
    externalDependencyDeclaration:
      type: object
      additionalProperties: false
      required:
        - declarationKey
        - purl
        - constraint
        - purpose
      properties:
        declarationKey:
          $ref: '#/components/schemas/externalDependencyDeclarationKey'
        purl:
          type: string
          pattern: ^pkg:(?!volume(?:/|$))[A-Za-z][A-Za-z0-9.+-]*/[^@#]+(?:\?[^#]+)?$
        constraint:
          type: string
          pattern: ^vers:[A-Za-z][A-Za-z0-9.-]*/\S+$
        purpose:
          type: string
          anyOf:
            - enum:
                - runtime
                - build
                - development
                - test
                - optional
                - peer
                - source
                - documentation
                - other
            - pattern: ^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+:[a-z][a-z0-9-]*$
        components:
          type: array
          items:
            type: string
            pattern: ^(?!.*--)[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$
          minItems: 1
          uniqueItems: true
    AuthenticationRequiredProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/authentication-required
            status:
              const: 401
    AuthorizationFailedProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/authorization-failed
            status:
              const: 403
    NotFoundProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/not-found
            status:
              const: 404
    ValidationFailedProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/validation-failed
            status:
              const: 400
    InvalidManifestProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/invalid-manifest
            status:
              const: 400
    InvalidArchiveProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/invalid-archive
            status:
              const: 400
    IdentityMismatchProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/identity-mismatch
            status:
              const: 409
    VersionConflictProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/version-conflict
            status:
              const: 409
    DigestMismatchProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/digest-mismatch
            status:
              const: 400
    SubjectBindingMismatchProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/subject-binding-mismatch
            status:
              const: 400
    InconsistentRegistryStateProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/inconsistent-registry-state
            status:
              const: 409
    UploadExpiredProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/upload-expired
            status:
              const: 410
    MissingUploadedBytesProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/missing-uploaded-bytes
            status:
              const: 400
    InvalidUploadStateProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/invalid-upload-state
            status:
              const: 409
    IdempotencyConflictProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/idempotency-conflict
            status:
              const: 409
    PayloadTooLargeProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/payload-too-large
            status:
              const: 413
    UnsupportedMediaTypeProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/unsupported-media-type
            status:
              const: 415
    PermissionEscalationProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/permission-escalation
            status:
              const: 400
    RateLimitedProblem:
      allOf:
        - $ref: '#/components/schemas/ProblemDetailsBase'
        - type: object
          properties:
            type:
              const: https://agentvolumes.org/problems/rate-limited
            status:
              const: 429
    externalDependencyDeclarationKey:
      type: string
      pattern: ^av-extdep-v1:sha256:[a-f0-9]{64}$
    ProblemDetailsBase:
      type: object
      additionalProperties: true
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
        title:
          type: string
          minLength: 1
        status:
          type: integer
          minimum: 100
          maximum: 599
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
  responses:
    BadRequest:
      description: Bad request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            validationFailed:
              summary: Request or metadata validation failed
              value:
                type: https://agentvolumes.org/problems/validation-failed
                title: Validation failed
                status: 400
            invalidManifest:
              summary: Submitted volume.toml is invalid
              value:
                type: https://agentvolumes.org/problems/invalid-manifest
                title: Invalid manifest
                status: 400
            invalidArchive:
              summary: Submitted archive violates the transport profile
              value:
                type: https://agentvolumes.org/problems/invalid-archive
                title: Invalid archive
                status: 400
            digestMismatch:
              summary: Submitted bytes do not match the declared digest
              value:
                type: https://agentvolumes.org/problems/digest-mismatch
                title: Digest mismatch
                status: 400
            subjectBindingMismatch:
              summary: Trust artifact subject does not match the release
              value:
                type: https://agentvolumes.org/problems/subject-binding-mismatch
                title: Subject binding mismatch
                status: 400
            missingUploadedBytes:
              summary: Finalize was requested before upload bytes were available
              value:
                type: https://agentvolumes.org/problems/missing-uploaded-bytes
                title: Missing uploaded bytes
                status: 400
    Unauthorized:
      description: Authentication needed or invalid bearer token
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            authenticationRequired:
              value:
                type: https://agentvolumes.org/problems/authentication-required
                title: Authentication required
                status: 401
    Forbidden:
      description: Request is refused by authorization or access policy
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            authorizationFailed:
              value:
                type: https://agentvolumes.org/problems/authorization-failed
                title: Authorization failed
                status: 403
    NotFound:
      description: Resource not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            notFound:
              value:
                type: https://agentvolumes.org/problems/not-found
                title: Not found
                status: 404
    Conflict:
      description: Resource conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            versionConflict:
              value:
                type: https://agentvolumes.org/problems/version-conflict
                title: Version conflict
                status: 409
            identityMismatch:
              value:
                type: https://agentvolumes.org/problems/identity-mismatch
                title: Identity mismatch
                status: 409
            idempotencyConflict:
              value:
                type: https://agentvolumes.org/problems/idempotency-conflict
                title: Idempotency conflict
                status: 409
            invalidUploadState:
              value:
                type: https://agentvolumes.org/problems/invalid-upload-state
                title: Invalid upload state
                status: 409
            inconsistentRegistryState:
              value:
                type: https://agentvolumes.org/problems/inconsistent-registry-state
                title: Inconsistent registry state
                status: 409
    Gone:
      description: Resource no longer available, such as an expired upload intent
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            uploadExpired:
              value:
                type: https://agentvolumes.org/problems/upload-expired
                title: Upload expired
                status: 410
    PayloadTooLarge:
      description: Submitted payload or declared upload size is too large
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            payloadTooLarge:
              value:
                type: https://agentvolumes.org/problems/payload-too-large
                title: Payload too large
                status: 413
    UnsupportedMediaType:
      description: Unsupported media type
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            unsupportedMediaType:
              value:
                type: https://agentvolumes.org/problems/unsupported-media-type
                title: Unsupported media type
                status: 415
    TooManyRequests:
      description: Rate limited
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            rateLimited:
              value:
                type: https://agentvolumes.org/problems/rate-limited
                title: Rate limited
                status: 429
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````