openapi: 3.0.0
info:
title: URL API Reference Add-Ons File metadata API
version: '2022-11-28'
description: 'Every uploaded file is immediately available on the Uploadcare CDN.
The CDN includes on-the-fly processing features and can work as a proxy.
## API endpoints
Access files in Uploadcare CDN at `ucarecdn.com` over HTTP/HTTPS like this:
```https://ucarecdn.com/:uuid/```
You can add CDN operations by including directives in the CDN URL:
```https://ucarecdn.com/:uuid/-/:operation/:params/:filename```
* `:uuid` stands for the unique file identifier, UUID, assigned on upload.
* `/-/` is a mandatory parsing delimiter to divide operations and other path components.
* `:operation/:params/` is a CDN operation directive with parameters.
* `:filename` is an optional filename you can add after a trailing slash /.
You can stack two and more operations like this:
```-/:operation/:params/-/:operation/:params/```
'
contact:
name: API support
email: help@uploadcare.com
x-logo:
url: https://ucarecdn.com/12e3af14-392d-416f-8542-f210c2eb6ec4/logourlapi.svg
backgroundColor: '#fafafa'
altText: Uploadcare URL API Reference
x-meta:
title: URL API Reference — Uploadcare
description: A reference documentation for the Uploadcare's URL API.
servers:
- url: https://ucarecdn.com
description: Production server
tags:
- name: File metadata
description: 'File metadata is additional, arbitrary data, associated with uploaded file. As an example, you could store unique file identifier from your system.
Metadata is key-value data. You can specify up to 50 keys, with key names up to 64 characters long and values up to 512 characters long.
Read more in the [docs](https://uploadcare.com/docs/file-metadata/).
**Notice:** Do not store any sensitive information (bank account numbers, card details, etc.) as metadata.
**Notice:** File metadata is provided by the end-users uploading the files and can contain symbols unsafe in, for example, HTML context. Please escape the metadata before use according to the rules of the target runtime context (HTML browser, SQL query parameter, etc).
'
paths:
/files/{uuid}/metadata/:
get:
summary: Get file's metadata
description: Get file's metadata keys and values.
tags:
- File metadata
operationId: _fileMetadata
parameters:
- $ref: '#/components/parameters/acceptHeader'
- in: path
name: uuid
description: File UUID.
required: true
schema:
type: string
format: uuid
example: 21975c81-7f57-4c7a-aef9-acfe28779f78
responses:
'200':
$ref: '#/components/responses/fileMetadataResponse'
'400':
$ref: '#/components/responses/simpleAuthHTTPForbiddenResponse'
'401':
$ref: '#/components/responses/authorizationProblemsResponse'
'406':
$ref: '#/components/responses/invalidAcceptHeader'
x-codeSamples:
- lang: JavaScript
label: JS
source: "import {\n getMetadata,\n UploadcareSimpleAuthSchema,\n} from '@uploadcare/rest-client';\n\nconst uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({\n publicKey: 'YOUR_PUBLIC_KEY',\n secretKey: 'YOUR_SECRET_KEY',\n});\n\nconst result = await getMetadata(\n {\n uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',\n },\n { authSchema: uploadcareSimpleAuthSchema }\n)\n"
- lang: PHP
label: PHP
source: "<?php\n$configuration = Uploadcare\\Configuration::create((string) $_ENV['UPLOADCARE_PUBLIC_KEY'], (string) $_ENV['UPLOADCARE_SECRET_KEY']);\n\n$api = (new Uploadcare\\Api($configuration))->file();\n$fileInfo = $api->fileInfo('1bac376c-aa7e-4356-861b-dd2657b5bfd2');\necho \\sprintf(\"File %s metadata:\\n\", $fileInfo->getUuid());\nforeach ($fileInfo->getMetadata() as $metaKey => $metaItem) {\n echo \\sprintf(\"%s: %s\\n\", $metaKey, $metaItem);\n}\n"
- lang: Python
label: Python
source: 'from pyuploadcare import Uploadcare
uploadcare = Uploadcare(public_key=''YOUR_PUBLIC_KEY'', secret_key=''YOUR_SECRET_KEY'')
value = uploadcare.metadata_api.get_all_metadata("1bac376c-aa7e-4356-861b-dd2657b5bfd2")
print(value)
'
- lang: Ruby
label: Ruby
source: 'require ''uploadcare''
Uploadcare.config.public_key = ''YOUR_PUBLIC_KEY''
Uploadcare.config.secret_key = ''YOUR_SECRET_KEY''
uuid = ''1bac376c-aa7e-4356-861b-dd2657b5bfd2''
puts Uploadcare::FileMetadata.show(uuid, ''pet'')
'
- lang: Swift
label: Swift
source: 'import Uploadcare
let uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")
let metadata = try await uploadcare.fileMetadata(withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2")
print(metadata)
'
- lang: Kotlin
label: Kotlin
source: 'import com.uploadcare.android.library.api.UploadcareClient
val uploadcare = UploadcareClient(publicKey = "YOUR_PUBLIC_KEY", secretKey = "YOUR_SECRET_KEY")
val metadata = uploadcare.getFileMetadata(fileId = "1bac376c-aa7e-4356-861b-dd2657b5bfd2")
Log.d("TAG", metadata.toString())
'
/files/{uuid}/metadata/{key}/:
get:
summary: Get metadata key's value
description: Get the value of a single metadata key.
tags:
- File metadata
operationId: fileMetadataKey
parameters:
- $ref: '#/components/parameters/acceptHeader'
- $ref: '#/components/parameters/fileUUID'
- $ref: '#/components/parameters/fileMetadataKey'
responses:
'200':
description: Value of a file's metadata key.
content:
application/json:
schema:
$ref: '#/components/schemas/metadataItemValue'
'400':
$ref: '#/components/responses/simpleAuthHTTPForbiddenResponse'
'401':
$ref: '#/components/responses/authorizationProblemsResponse'
'406':
$ref: '#/components/responses/invalidAcceptHeader'
x-codeSamples:
- lang: JavaScript
label: JS
source: "import {\n getMetadataValue,\n UploadcareSimpleAuthSchema,\n} from '@uploadcare/rest-client';\n\nconst uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({\n publicKey: 'YOUR_PUBLIC_KEY',\n secretKey: 'YOUR_SECRET_KEY',\n});\n\nconst result = await getMetadataValue(\n {\n uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',\n key: 'pet'\n },\n { authSchema: uploadcareSimpleAuthSchema }\n)\n"
- lang: PHP
label: PHP
source: '<?php
$configuration = Uploadcare\Configuration::create((string) $_ENV[''UPLOADCARE_PUBLIC_KEY''], (string) $_ENV[''UPLOADCARE_SECRET_KEY'']);
$api = (new Uploadcare\Api($configuration))->metadata();
$metadata = $api->getMetadata(''1bac376c-aa7e-4356-861b-dd2657b5bfd2'');
echo \sprintf(''Value for key \''pet\'' %s'', $metadata[''pet''] ?? ''does not exists'');
'
- lang: Python
label: Python
source: 'from pyuploadcare import Uploadcare
uploadcare = Uploadcare(public_key=''YOUR_PUBLIC_KEY'', secret_key=''YOUR_SECRET_KEY'')
value = uploadcare.metadata_api.get_key("1bac376c-aa7e-4356-861b-dd2657b5bfd2", "pet")
print(value)
'
- lang: Ruby
label: Ruby
source: 'require ''uploadcare''
Uploadcare.config.public_key = ''YOUR_PUBLIC_KEY''
Uploadcare.config.secret_key = ''YOUR_SECRET_KEY''
uuid = ''1bac376c-aa7e-4356-861b-dd2657b5bfd2''
puts Uploadcare::FileMetadata.index(uuid).inspect
'
- lang: Swift
label: Swift
source: 'import Uploadcare
let uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")
let value = try await uploadcare.fileMetadataValue(forKey: "pet", withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2")
print(value)
'
- lang: Kotlin
label: Kotlin
source: "import com.uploadcare.android.library.api.UploadcareClient\n\nval uploadcare = UploadcareClient(publicKey = \"YOUR_PUBLIC_KEY\", secretKey = \"YOUR_SECRET_KEY\")\n\nval value = uploadcare.getFileMetadataKeyValue(\n fileId = \"1bac376c-aa7e-4356-861b-dd2657b5bfd2\",\n key = \"pet\"\n)\nLog.d(\"TAG\", value)\n"
put:
summary: Update metadata key's value
description: Update the value of a single metadata key. If the key does not exist, it will be created.
tags:
- File metadata
operationId: updateFileMetadataKey
parameters:
- $ref: '#/components/parameters/acceptHeader'
- $ref: '#/components/parameters/fileUUID'
- $ref: '#/components/parameters/fileMetadataKey'
requestBody:
required: true
content:
application/json:
schema:
type: string
minLength: 1
maxLength: 512
responses:
'200':
description: Value of a file's metadata key successfully updated.
content:
application/json:
schema:
$ref: '#/components/schemas/metadataItemValue'
'201':
description: Key of a file metadata successfully added.
content:
application/json:
schema:
$ref: '#/components/schemas/metadataItemValue'
'400':
$ref: '#/components/responses/simpleAuthHTTPForbiddenResponse'
'401':
$ref: '#/components/responses/authorizationProblemsResponse'
'406':
$ref: '#/components/responses/invalidAcceptHeader'
x-codeSamples:
- lang: JavaScript
label: JS
source: "import {\n updateMetadata,\n UploadcareSimpleAuthSchema,\n} from '@uploadcare/rest-client';\n\nconst uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({\n publicKey: 'YOUR_PUBLIC_KEY',\n secretKey: 'YOUR_SECRET_KEY',\n});\n\nconst result = await updateMetadata(\n {\n uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',\n key: 'pet',\n value: 'dog',\n },\n { authSchema: uploadcareSimpleAuthSchema }\n)\n"
- lang: PHP
label: PHP
source: '<?php
$configuration = Uploadcare\Configuration::create((string) $_ENV[''UPLOADCARE_PUBLIC_KEY''], (string) $_ENV[''UPLOADCARE_SECRET_KEY'']);
$api = (new Uploadcare\Api($configuration))->metadata();
$result = $api->setKey(''1bac376c-aa7e-4356-861b-dd2657b5bfd2'', ''pet'', ''dog'');
echo \sprintf(''Metadata key \''pet\'' is set to %s'', $result[''pet'']);
'
- lang: Python
label: Python
source: 'from pyuploadcare import Uploadcare
uploadcare = Uploadcare(public_key=''YOUR_PUBLIC_KEY'', secret_key=''YOUR_SECRET_KEY'')
file_uuid = ''1bac376c-aa7e-4356-861b-dd2657b5bfd2''
key, value = "pet", "dog"
uploadcare.metadata_api.update_or_create_key(file_uuid, key, value)
'
- lang: Ruby
label: Ruby
source: 'require ''uploadcare''
Uploadcare.config.public_key = ''YOUR_PUBLIC_KEY''
Uploadcare.config.secret_key = ''YOUR_SECRET_KEY''
uuid = ''1bac376c-aa7e-4356-861b-dd2657b5bfd2''
key = ''pet''
value = ''dog''
Uploadcare::FileMetadata.update(uuid, key, value)
'
- lang: Swift
label: Swift
source: "import Uploadcare\n\nlet uploadcare = Uploadcare(withPublicKey: \"YOUR_PUBLIC_KEY\", secretKey: \"YOUR_SECRET_KEY\")\n\nlet response = try await uploadcare.updateFileMetadata(\n withUUID: \"1bac376c-aa7e-4356-861b-dd2657b5bfd2\", \n key: \"pet\", \n value: dog\n)\n print(response)\n"
- lang: Kotlin
label: Kotlin
source: "import com.uploadcare.android.library.api.UploadcareClient\n\nval uploadcare = UploadcareClient(publicKey = \"YOUR_PUBLIC_KEY\", secretKey = \"YOUR_SECRET_KEY\")\n\nval value = uploadcare.updateFileMetadataKeyValue(\n fileId = \"1bac376c-aa7e-4356-861b-dd2657b5bfd2\",\n key = \"pet\",\n value = \"dog\"\n)\nLog.d(\"TAG\", value)\n"
delete:
summary: Delete metadata key
description: Delete a file's metadata key.
tags:
- File metadata
operationId: deleteFileMetadataKey
parameters:
- $ref: '#/components/parameters/acceptHeader'
- $ref: '#/components/parameters/fileUUID'
- $ref: '#/components/parameters/fileMetadataKey'
responses:
'204':
description: Key of a file metadata successfully deleted.
'400':
$ref: '#/components/responses/simpleAuthHTTPForbiddenResponse'
'401':
$ref: '#/components/responses/authorizationProblemsResponse'
'406':
$ref: '#/components/responses/invalidAcceptHeader'
x-codeSamples:
- lang: JavaScript
label: JS
source: "import {\n deleteMetadata,\n UploadcareSimpleAuthSchema,\n} from '@uploadcare/rest-client';\n\nconst uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({\n publicKey: 'YOUR_PUBLIC_KEY',\n secretKey: 'YOUR_SECRET_KEY',\n});\n\nconst result = await deleteMetadata(\n {\n uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',\n key: 'delete_key',\n },\n { authSchema: uploadcareSimpleAuthSchema }\n)\n"
- lang: PHP
label: PHP
source: "<?php\n$configuration = Uploadcare\\Configuration::create((string) $_ENV['UPLOADCARE_PUBLIC_KEY'], (string) $_ENV['UPLOADCARE_SECRET_KEY']);\n\n$metadataApi = (new Uploadcare\\Api($configuration))->metadata();\ntry {\n $metadataApi->removeKey('1bac376c-aa7e-4356-861b-dd2657b5bfd2', 'pet');\n} catch (\\Throwable $e) {\n echo \\sprintf('Error while key removing: %s', $e->getMessage());\n}\necho 'Key was successfully removed';\n"
- lang: Python
label: Python
source: 'from pyuploadcare import Uploadcare
uploadcare = Uploadcare(public_key=''YOUR_PUBLIC_KEY'', secret_key=''YOUR_SECRET_KEY'')
file_uuid = ''1bac376c-aa7e-4356-861b-dd2657b5bfd2''
uploadcare.metadata_api.delete_key(file_uuid, mkey=''pet'')
'
- lang: Ruby
label: Ruby
source: 'require ''uploadcare''
Uploadcare.config.public_key = ''YOUR_PUBLIC_KEY''
Uploadcare.config.secret_key = ''YOUR_SECRET_KEY''
puts Uploadcare::FileMetadata.delete(''1bac376c-aa7e-4356-861b-dd2657b5bfd2'', ''pet'')
'
- lang: Swift
label: Swift
source: 'import Uploadcare
let uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")
try await uploadcare.deleteFileMetadata(forKey: "pet", withUUID: "1bac376c-aa7e-4356-861b-dd2657b5bfd2")
'
- lang: Kotlin
label: Kotlin
source: 'import com.uploadcare.android.library.api.UploadcareClient
val uploadcare = UploadcareClient(publicKey = "YOUR_PUBLIC_KEY", secretKey = "YOUR_SECRET_KEY")
uploadcare.deleteFileMetadataKey(fileId = "1bac376c-aa7e-4356-861b-dd2657b5bfd2", key = "pet")
'
components:
parameters:
fileUUID:
in: path
name: uuid
description: File UUID.
required: true
schema:
type: string
format: uuid
example: 21975c81-7f57-4c7a-aef9-acfe28779f78
acceptHeader:
in: header
name: Accept
description: Version header.
schema:
type: string
nullable: true
example: application/vnd.uploadcare-v0.7+json
required: true
fileMetadataKey:
in: path
name: key
description: "Key of file metadata.\nList of allowed characters for the key:\n - Latin letters in lower or upper case (a-z,A-Z)\n - digits (0-9)\n - underscore `_`\n - a hyphen `-`\n - dot `.`\n - colon `:`\n"
required: true
schema:
type: string
minLength: 1
maxLength: 64
pattern: '[\w\-\.\:]+'
example: subsystem
responses:
simpleAuthHTTPForbiddenResponse:
description: Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.
content:
application/json:
schema:
$ref: '#/components/schemas/simpleAuthHTTPForbidden'
fileMetadataResponse:
description: File metadata in JSON.
content:
application/json:
schema:
type: object
example:
subsystem: uploader
pet: cat
invalidAcceptHeader:
description: Invalid version header `Accept` for this endpoint.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: Incorrect Accept header provided. Make sure to specify API version. Refer to REST API docs for details.
default: Incorrect Accept header provided. Make sure to specify API version. Refer to REST API docs for details.
authorizationProblemsResponse:
description: Authorization errors.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
enum:
- Incorrect authentication credentials.
- Public key {public_key} not found.
- Secret key not found.
- Invalid signature. Please check your Secret key.
example: Incorrect authentication credentials.
schemas:
metadataItemValue:
type: string
minLength: 1
maxLength: 512
description: Value of metadata key.
example: uploader
simpleAuthHTTPForbidden:
type: object
properties:
detail:
type: string
default: Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.
example:
detail: Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.