> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/api-reference/ar/registry-v3-files.md).

# Registry V3 Files

V3 files endpoints

## Search Files

> List files.

```json
{"openapi":"3.0.0","info":{"title":"Harness Artifact Registry API","version":"1.0.0"},"tags":[{"description":"V3 files endpoints","name":"Registry V3 - Files"}],"servers":[{"url":"/api"}],"paths":{"/v3/files":{"get":{"description":"List files.","operationId":"ListFilesV3","parameters":[{"$ref":"#/components/parameters/AccountIdentifierV3"},{"$ref":"#/components/parameters/OrgIdentifierV3"},{"$ref":"#/components/parameters/ProjectIdentifierV3"},{"$ref":"#/components/parameters/RegistryIdOptionalParamV3"},{"$ref":"#/components/parameters/PackageIdOptionalParamV3"},{"$ref":"#/components/parameters/VersionIdOptionalParamV3"},{"$ref":"#/components/parameters/ConanRecipeRevisionOptionalParamV3"},{"$ref":"#/components/parameters/ConanPackageRevisionOptionalParamV3"},{"$ref":"#/components/parameters/PageNumberV3"},{"$ref":"#/components/parameters/PageSizeV3"},{"$ref":"#/components/parameters/SortV3"},{"$ref":"#/components/parameters/SearchTermV3"}],"responses":{"200":{"$ref":"#/components/responses/ListFilesResponseV3"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorV3"}}},"description":"Error response."}},"summary":"Search Files","tags":["Registry V3 - Files"]}}},"components":{"parameters":{"AccountIdentifierV3":{"description":"Unique identifier for the Harness account.\n","in":"query","name":"account_identifier","required":true,"schema":{"type":"string"}},"OrgIdentifierV3":{"description":"Unique identifier for the organization within the account.\n\nExample: `default` or `engineering_org`\n","in":"query","name":"org_identifier","schema":{"type":"string"}},"ProjectIdentifierV3":{"description":"Unique identifier for the project within the organization.\n\nExample: `my_project` or `frontend_services`\n","in":"query","name":"project_identifier","schema":{"type":"string"}},"RegistryIdOptionalParamV3":{"description":"Unique id for the registry.\n","in":"query","name":"registry_id","schema":{"type":"string"}},"PackageIdOptionalParamV3":{"description":"Unique identifier for the package.\n","in":"query","name":"package_id","schema":{"type":"string"}},"VersionIdOptionalParamV3":{"description":"Unique identifier for the version.\n","in":"query","name":"version_id","schema":{"type":"string"}},"ConanRecipeRevisionOptionalParamV3":{"description":"Internal UUID of the Conan recipe revision (RREV) row. Resolves file paths via\nnode_entity_mapping. Requires version_id.\nMutually exclusive with package_revision_id.\n","in":"query","name":"recipe_revision_id","schema":{"type":"string"}},"ConanPackageRevisionOptionalParamV3":{"description":"Internal UUID of the Conan package revision (PREV) row. Resolves file paths via\nnode_entity_mapping. Requires version_id.\nMutually exclusive with recipe_revision_id.\n","in":"query","name":"package_revision_id","schema":{"type":"string"}},"PageNumberV3":{"description":"The page number for pagination (0-indexed).\n\nUsed to navigate through large result sets. Combined with `size` parameter\nto control which subset of results to return.\n\nExample: `page=0` returns the first page, `page=1` returns the second page\n","in":"query","name":"page","schema":{"default":0,"format":"int64","type":"integer"}},"PageSizeV3":{"description":"The number of items to return per page.\n\nControls the page size for paginated results. \n\nExample: `size=50` returns up to 50 items per page\n","in":"query","name":"size","schema":{"default":20,"format":"int64","maximum":100,"minimum":1,"type":"integer"}},"SortV3":{"description":"The sort for the results.\nAccepted pattern: `sort_field:sort_order` where sort_field is the field name\nand sort_order is either `asc` or `desc`.\n\nExamples: `name:asc`, `modifiedAt:desc`\n","in":"query","name":"sort","schema":{"type":"string"}},"SearchTermV3":{"description":"Search term for filtering results.\n\nExample: `search_term=prod` might match keys like \"production\", \"prod-env\", etc.\n","in":"query","name":"search_term","schema":{"type":"string"}}},"responses":{"ListFilesResponseV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListFilesResponseBodyV3"}}},"description":"response for list files"}},"schemas":{"ListFilesResponseBodyV3":{"allOf":[{"$ref":"#/components/schemas/PageInfoV3"},{"properties":{"items":{"items":{"$ref":"#/components/schemas/FileMetadataV3"},"type":"array"},"meta":{"$ref":"#/components/schemas/MetaV3"}},"required":["items"],"type":"object"}]},"PageInfoV3":{"description":"Pagination metadata.\n- `page` selects which page of results to return (0 = first page).\n- `size` controls how many items are returned per page.\n- `hasMore` is true if more results exist after this page.\n","properties":{"hasMore":{"description":"True if more results exist after this page.","type":"boolean"},"page":{"description":"The current page (0-indexed)","format":"int64","type":"integer"},"size":{"description":"Number of items per page","format":"int64","type":"integer"}},"required":["page","size","hasMore"],"type":"object"},"FileMetadataV3":{"description":"File Metadata","properties":{"createdAt":{"$ref":"#/components/schemas/CreatedAtMsV3"},"createdBy":{"$ref":"#/components/schemas/UserInfoV3"},"downloadCmd":{"type":"string"},"downloadUrl":{"type":"string"},"id":{"type":"string"},"md5":{"type":"string"},"name":{"type":"string"},"path":{"type":"string"},"sha1":{"type":"string"},"sha256":{"type":"string"},"sha512":{"type":"string"},"size":{"type":"string"}},"required":["id","name","path","createdAt","sha1","sha256","sha512","md5","size","downloadCmd"],"type":"object"},"CreatedAtMsV3":{"description":"Unix timestamp in milliseconds when the resource was created","format":"int64","nullable":true,"type":"integer"},"UserInfoV3":{"description":"Structured user information for a principal","properties":{"display_name":{"description":"Human-readable display name","type":"string"},"email":{"description":"Email address","type":"string"},"type":{"description":"Principal type (user, service, service_account)","type":"string"},"uid":{"description":"Principal unique identifier (username)","type":"string"}},"type":"object"},"MetaV3":{"description":"Metadata about the list response","properties":{"activeCount":{"description":"Count of active (non-deleted) entities","format":"int64","type":"integer"},"deletedCount":{"description":"Count of soft-deleted entities","format":"int64","type":"integer"}},"required":["activeCount","deletedCount"],"type":"object"},"ErrorV3":{"description":"An error response","properties":{"error":{"$ref":"#/components/schemas/ApiErrorsV3"}},"required":["error"],"type":"object"},"ApiErrorsV3":{"properties":{"code":{"description":"For some errors that could be handled programmatically, a short string indicating the [error code](https://docs.stripe.com/error-codes) reported.","maxLength":5000,"type":"string"},"message":{"description":"A human-readable message providing more details about the error. These messages can be shown to users.","maxLength":40000,"type":"string"},"param":{"description":"If the error is parameter-specific, the parameter related to the error. For example, we can use this to display a message near the correct form field.","maxLength":5000,"type":"string"},"type":{"description":"The type of error returned.","enum":["INVALID_REQUEST_ERROR","AUTHENTICATION_ERROR","PERMISSION_ERROR","API_ERROR"],"type":"string"}},"required":["type"],"title":"APIErrors","type":"object"}}}}
```

## Download file using file id

> Download a file using its id. When \`preview=true\` is supplied the response is a \`302\` redirect to an inline-preview URL for the file instead of the file bytes.<br>

```json
{"openapi":"3.0.0","info":{"title":"Harness Artifact Registry API","version":"1.0.0"},"tags":[{"description":"V3 files endpoints","name":"Registry V3 - Files"}],"servers":[{"url":"/api"}],"paths":{"/v3/files/{id}/content":{"get":{"description":"Download a file using its id. When `preview=true` is supplied the response is a `302` redirect to an inline-preview URL for the file instead of the file bytes.\n","operationId":"GetFileV3","parameters":[{"$ref":"#/components/parameters/AccountIdentifierV3"},{"$ref":"#/components/parameters/IdPathParamV3"},{"$ref":"#/components/parameters/FilePreviewQueryParamV3"}],"responses":{"200":{"$ref":"#/components/responses/DownloadFileResponseV3"},"302":{"$ref":"#/components/responses/RedirectV3"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorV3"}}},"description":"Error response."}},"summary":"Download file using file id","tags":["Registry V3 - Files"]}}},"components":{"parameters":{"AccountIdentifierV3":{"description":"Unique identifier for the Harness account.\n","in":"query","name":"account_identifier","required":true,"schema":{"type":"string"}},"IdPathParamV3":{"in":"path","name":"id","required":true,"schema":{"type":"string"}},"FilePreviewQueryParamV3":{"description":"When `true`, the endpoint responds with a `302` redirect to an inline-preview URL for the file (presigned URL for cloud deployments, or a protocol-API URL with `preview=true` for filesystem deployments) instead of streaming the file for download. The file must satisfy the preview allowlist and size limit, otherwise an error is returned. Defaults to `false` (download).\n","in":"query","name":"preview","schema":{"default":false,"type":"boolean"}}},"responses":{"DownloadFileResponseV3":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"Response containing file content"},"RedirectV3":{"description":"Temporary Redirect","headers":{"Location":{"description":"The URL of the redirected resource","schema":{"format":"uri","type":"string"}}}}},"schemas":{"ErrorV3":{"description":"An error response","properties":{"error":{"$ref":"#/components/schemas/ApiErrorsV3"}},"required":["error"],"type":"object"},"ApiErrorsV3":{"properties":{"code":{"description":"For some errors that could be handled programmatically, a short string indicating the [error code](https://docs.stripe.com/error-codes) reported.","maxLength":5000,"type":"string"},"message":{"description":"A human-readable message providing more details about the error. These messages can be shown to users.","maxLength":40000,"type":"string"},"param":{"description":"If the error is parameter-specific, the parameter related to the error. For example, we can use this to display a message near the correct form field.","maxLength":5000,"type":"string"},"type":{"description":"The type of error returned.","enum":["INVALID_REQUEST_ERROR","AUTHENTICATION_ERROR","PERMISSION_ERROR","API_ERROR"],"type":"string"}},"required":["type"],"title":"APIErrors","type":"object"}}}}
```

## Get File Metadata

> Retrieves all metadata for a file.

```json
{"openapi":"3.0.0","info":{"title":"Harness Artifact Registry API","version":"1.0.0"},"tags":[{"description":"V3 files endpoints","name":"Registry V3 - Files"}],"servers":[{"url":"/api"}],"paths":{"/v3/files/{id}/metadata":{"get":{"description":"Retrieves all metadata for a file.","operationId":"GetFileMetadataV3","parameters":[{"$ref":"#/components/parameters/AccountIdentifierV3"},{"$ref":"#/components/parameters/IdPathParamV3"}],"responses":{"200":{"$ref":"#/components/responses/MetadataResponseV3"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorV3"}}},"description":"Error response."}},"summary":"Get File Metadata","tags":["Registry V3 - Files"]}}},"components":{"parameters":{"AccountIdentifierV3":{"description":"Unique identifier for the Harness account.\n","in":"query","name":"account_identifier","required":true,"schema":{"type":"string"}},"IdPathParamV3":{"in":"path","name":"id","required":true,"schema":{"type":"string"}}},"responses":{"MetadataResponseV3":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"Array of metadata entries","items":{"$ref":"#/components/schemas/MetadataV3"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"Response containing all metadata entries for the requested entity"}},"schemas":{"MetadataV3":{"description":"Metadata entry","properties":{"id":{"description":"Unique identifier for this metadata entry","format":"uuid","type":"string"},"key":{"description":"The metadata key name","type":"string"},"type":{"$ref":"#/components/schemas/MetadataTypeV3"},"value":{"description":"The metadata value","type":"string"}},"required":["id","key","value","type"],"type":"object"},"MetadataTypeV3":{"description":"Indicates if metadata was manually added (MANUAL) or system-generated (AUTO)","enum":["MANUAL","AUTO"],"type":"string"},"ErrorV3":{"description":"An error response","properties":{"error":{"$ref":"#/components/schemas/ApiErrorsV3"}},"required":["error"],"type":"object"},"ApiErrorsV3":{"properties":{"code":{"description":"For some errors that could be handled programmatically, a short string indicating the [error code](https://docs.stripe.com/error-codes) reported.","maxLength":5000,"type":"string"},"message":{"description":"A human-readable message providing more details about the error. These messages can be shown to users.","maxLength":40000,"type":"string"},"param":{"description":"If the error is parameter-specific, the parameter related to the error. For example, we can use this to display a message near the correct form field.","maxLength":5000,"type":"string"},"type":{"description":"The type of error returned.","enum":["INVALID_REQUEST_ERROR","AUTHENTICATION_ERROR","PERMISSION_ERROR","API_ERROR"],"type":"string"}},"required":["type"],"title":"APIErrors","type":"object"}}}}
```

## Upsert File Metadata

> Creates or overwrites metadata for a file.

```json
{"openapi":"3.0.0","info":{"title":"Harness Artifact Registry API","version":"1.0.0"},"tags":[{"description":"V3 files endpoints","name":"Registry V3 - Files"}],"servers":[{"url":"/api"}],"paths":{"/v3/files/{id}/metadata":{"post":{"description":"Creates or overwrites metadata for a file.","operationId":"UpsertFileMetadataV3","parameters":[{"$ref":"#/components/parameters/AccountIdentifierV3"},{"$ref":"#/components/parameters/IdPathParamV3"}],"requestBody":{"$ref":"#/components/requestBodies/MetadataRequestV3"},"responses":{"200":{"$ref":"#/components/responses/MetadataResponseV3"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorV3"}}},"description":"Error response."}},"summary":"Upsert File Metadata","tags":["Registry V3 - Files"]}}},"components":{"parameters":{"AccountIdentifierV3":{"description":"Unique identifier for the Harness account.\n","in":"query","name":"account_identifier","required":true,"schema":{"type":"string"}},"IdPathParamV3":{"in":"path","name":"id","required":true,"schema":{"type":"string"}}},"requestBodies":{"MetadataRequestV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataInputV3"}}},"description":"Request body containing metadata key-value pairs to add or update"}},"schemas":{"MetadataInputV3":{"description":"Request payload containing metadata key-value pairs to add or update.\n","properties":{"metadata":{"description":"Array of metadata key-value pairs","items":{"$ref":"#/components/schemas/MetadataItemInputV3"},"maxItems":50,"minItems":1,"type":"array"}},"required":["metadata"],"type":"object"},"MetadataItemInputV3":{"description":"Metadata key-value pair for create/update operations","properties":{"key":{"description":"The metadata key name (case-sensitive)","maxLength":128,"minLength":1,"type":"string"},"value":{"description":"The metadata value","maxLength":256,"minLength":1,"type":"string"}},"required":["key","value"],"type":"object"},"MetadataV3":{"description":"Metadata entry","properties":{"id":{"description":"Unique identifier for this metadata entry","format":"uuid","type":"string"},"key":{"description":"The metadata key name","type":"string"},"type":{"$ref":"#/components/schemas/MetadataTypeV3"},"value":{"description":"The metadata value","type":"string"}},"required":["id","key","value","type"],"type":"object"},"MetadataTypeV3":{"description":"Indicates if metadata was manually added (MANUAL) or system-generated (AUTO)","enum":["MANUAL","AUTO"],"type":"string"},"ErrorV3":{"description":"An error response","properties":{"error":{"$ref":"#/components/schemas/ApiErrorsV3"}},"required":["error"],"type":"object"},"ApiErrorsV3":{"properties":{"code":{"description":"For some errors that could be handled programmatically, a short string indicating the [error code](https://docs.stripe.com/error-codes) reported.","maxLength":5000,"type":"string"},"message":{"description":"A human-readable message providing more details about the error. These messages can be shown to users.","maxLength":40000,"type":"string"},"param":{"description":"If the error is parameter-specific, the parameter related to the error. For example, we can use this to display a message near the correct form field.","maxLength":5000,"type":"string"},"type":{"description":"The type of error returned.","enum":["INVALID_REQUEST_ERROR","AUTHENTICATION_ERROR","PERMISSION_ERROR","API_ERROR"],"type":"string"}},"required":["type"],"title":"APIErrors","type":"object"}},"responses":{"MetadataResponseV3":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"Array of metadata entries","items":{"$ref":"#/components/schemas/MetadataV3"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"Response containing all metadata entries for the requested entity"}}}}
```

## Replace File Metadata

> Replaces all metadata for a file.

```json
{"openapi":"3.0.0","info":{"title":"Harness Artifact Registry API","version":"1.0.0"},"tags":[{"description":"V3 files endpoints","name":"Registry V3 - Files"}],"servers":[{"url":"/api"}],"paths":{"/v3/files/{id}/metadata":{"put":{"description":"Replaces all metadata for a file.","operationId":"SaveFileMetadataV3","parameters":[{"$ref":"#/components/parameters/AccountIdentifierV3"},{"$ref":"#/components/parameters/IdPathParamV3"}],"requestBody":{"$ref":"#/components/requestBodies/MetadataRequestV3"},"responses":{"200":{"$ref":"#/components/responses/MetadataResponseV3"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorV3"}}},"description":"Error response."}},"summary":"Replace File Metadata","tags":["Registry V3 - Files"]}}},"components":{"parameters":{"AccountIdentifierV3":{"description":"Unique identifier for the Harness account.\n","in":"query","name":"account_identifier","required":true,"schema":{"type":"string"}},"IdPathParamV3":{"in":"path","name":"id","required":true,"schema":{"type":"string"}}},"requestBodies":{"MetadataRequestV3":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataInputV3"}}},"description":"Request body containing metadata key-value pairs to add or update"}},"schemas":{"MetadataInputV3":{"description":"Request payload containing metadata key-value pairs to add or update.\n","properties":{"metadata":{"description":"Array of metadata key-value pairs","items":{"$ref":"#/components/schemas/MetadataItemInputV3"},"maxItems":50,"minItems":1,"type":"array"}},"required":["metadata"],"type":"object"},"MetadataItemInputV3":{"description":"Metadata key-value pair for create/update operations","properties":{"key":{"description":"The metadata key name (case-sensitive)","maxLength":128,"minLength":1,"type":"string"},"value":{"description":"The metadata value","maxLength":256,"minLength":1,"type":"string"}},"required":["key","value"],"type":"object"},"MetadataV3":{"description":"Metadata entry","properties":{"id":{"description":"Unique identifier for this metadata entry","format":"uuid","type":"string"},"key":{"description":"The metadata key name","type":"string"},"type":{"$ref":"#/components/schemas/MetadataTypeV3"},"value":{"description":"The metadata value","type":"string"}},"required":["id","key","value","type"],"type":"object"},"MetadataTypeV3":{"description":"Indicates if metadata was manually added (MANUAL) or system-generated (AUTO)","enum":["MANUAL","AUTO"],"type":"string"},"ErrorV3":{"description":"An error response","properties":{"error":{"$ref":"#/components/schemas/ApiErrorsV3"}},"required":["error"],"type":"object"},"ApiErrorsV3":{"properties":{"code":{"description":"For some errors that could be handled programmatically, a short string indicating the [error code](https://docs.stripe.com/error-codes) reported.","maxLength":5000,"type":"string"},"message":{"description":"A human-readable message providing more details about the error. These messages can be shown to users.","maxLength":40000,"type":"string"},"param":{"description":"If the error is parameter-specific, the parameter related to the error. For example, we can use this to display a message near the correct form field.","maxLength":5000,"type":"string"},"type":{"description":"The type of error returned.","enum":["INVALID_REQUEST_ERROR","AUTHENTICATION_ERROR","PERMISSION_ERROR","API_ERROR"],"type":"string"}},"required":["type"],"title":"APIErrors","type":"object"}},"responses":{"MetadataResponseV3":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"Array of metadata entries","items":{"$ref":"#/components/schemas/MetadataV3"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"Response containing all metadata entries for the requested entity"}}}}
```