Uploadcare File metadata API

openapi: 3.2.0
info:
  title: REST API Reference File metadata API
  version: '0.7'
  description: 'REST API provides low-level access to Uploadcare features. You can access files and their metadata, application data, file groups, add-ons, projects, webhooks, document conversion and video encoding.


    The REST API root is `https://api.uploadcare.com/`. Send data via query strings and POST request bodies, and receive JSON responses. All URLs MUST end with a forward slash `/`.


    Check out our API clients that cover most of the popular programming languages and frameworks.


    # Authentication

    -->'
  contact:
    name: API support
    email: help@uploadcare.com
  x-logo:
    url: https://ucarecdn.com/06bc72fb-3a5a-4ee7-a19c-b1d02fb9e711/logorestapi.svg
    backgroundColor: '#fafafa'
    altText: Uploadcare REST API Reference
  x-meta:
    title: REST API 0.7 Reference — Uploadcare
    description: Complete reference documentation for the Uploadcare REST API 0.7. Covers endpoints, requests, their params, and response examples.
servers:
- url: https://api.uploadcare.com
  description: Production server
security:
- apiKeyAuth: []
tags:
- name: File Metadata
  description: File metadata is additional, arbitrary data, associated with uploaded file.
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:
  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.
  responses:
    simpleAuthHTTPForbiddenResponse:
      description: Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/simpleAuthHTTPForbidden'
    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.
    fileMetadataResponse:
      description: File metadata in JSON.
      content:
        application/json:
          schema:
            type: object
            example:
              subsystem: uploader
              pet: cat
    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.
  parameters:
    acceptHeader:
      in: header
      name: Accept
      description: Version header.
      schema:
        type:
        - string
        - 'null'
        example: application/vnd.uploadcare-v0.7+json
      required: true
    fileUUID:
      in: path
      name: uuid
      description: File UUID.
      required: true
      schema:
        type: string
        format: uuid
        example: 21975c81-7f57-4c7a-aef9-acfe28779f78
    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
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Every request made to `https://api.uploadcare.com/` MUST be signed. HTTPS SHOULD be used with any authorization scheme.


        Requests MUST contain the `Authorization` header defining `auth-scheme` and `auth-param`: `Authorization: auth-scheme auth-param`.


        Every request MUST contain the `Accept` header identifying the REST API version: `Accept: application/vnd.uploadcare-v0.7+json`.


        There are two available authorization schemes:

        * For production: `Uploadcare`, a scheme where a `signature`, not your Secret API Key MUST be specified. Signatures SHOULD be generated on backend.

        * For quick tests: `Uploadcare.Simple`, a simple scheme where your [Secret API Key](https://app.uploadcare.com/projects/-/api-keys/) MUST be specified in every request''s `auth-param`.

        '
    Uploadcare:
      type: apiKey
      in: header
      name: Uploadcare
      description: "With the `Uploadcare` authentication method:\n* `auth-param` is a `public_key:signature` pair, where your `secret_key` is used to derive `signature` but is _not included in every request_ itself.\n* You MUST also provide the `Date` header in [RFC2822](https://datatracker.ietf.org/doc/html/rfc2822#section-3.3) format with the time zone set to `GMT` (see the example below).\n* The date you provide MUST NOT exceed the 15-minute offset from the server time of the API endpoint.\n\n```http\nAccept: application/vnd.uploadcare-v0.7+json\nDate: Fri, 30 Sep 2016 11:10:54 GMT\nAuthorization: Uploadcare public_key:6ff75027649aadd4dc98c1f784444445d1e6ed82\n```\n\nThe `signature` part of the `Uploadcare` authentication method `auth-param` MUST be constructed from the following components:\n* Request type (`POST`, `GET`, `HEAD`, `OPTIONS`)\n* Hex md5 hash of the request body\n* `Content-Type` header value\n* `Date` header value\n* URI including path and parameters\n\nThe parameters are then concatenated in textual order using LF: every value sits in a separate line. The result is then signed with [HMAC/SHA1](https://en.wikipedia.org/wiki/HMAC) using your project's `secret_key`.\n\nTake a look at the Python example of deriving `signature`; the example request is made to get a list of files:\n\n```py\nimport time\nimport hashlib\nimport hmac\nfrom email import utils\n\n# Specifying the project’s key\nSECRET_KEY = 'YOUR_SECRET_KEY'\n\n# Specifying request type\nverb = 'GET'\n\n# Calculate [md5](https://en.wikipedia.org/wiki/MD5) checksum for the request's HTTP body.\n# Note: Taking into account that in our example, we are sending an HTTP GET request,\n# and the request does not have anything in its HTTP body, we use an empty string as an input to the md5 hash function.\n# If we were to send an HTTP POST request with, for example, JSON in the request's body,\n# we would have to pass the JSON as the input to the md5 hash function.\ncontent_md5 = hashlib.md5(b'').hexdigest()\n\n# Content-Type header\ncontent_type = 'application/json'\n\n# Current time, e.g. 1541423681\ntimestamp = int(time.time())\n# Date header ('Mon, 05 Nov 2018 13:14:41 GMT')\ndate_header = utils.formatdate(timestamp, usegmt=True)\n\n# The request URI\nuri = '/files/?limit=1&stored=true'\n\n# Forming the final string: concatenating\nsign_string = '\\n'.join([verb, content_md5, content_type, date_header, uri])\n\n# Calculating the signature,\n# the result may look like this: \"3cbc4d2cf91f80c1ba162b926f8a975e8bec7995\"\nsignature = hmac.new(SECRET_KEY.encode(), sign_string.encode(), hashlib.sha1).hexdigest()\n```\n\nOnce `signature` is derived, it SHOULD be implemented into the request body:\n\n```bash\ncurl  \\\n    -H 'Content-Type: application/json' \\\n    -H 'Accept: application/vnd.uploadcare-v0.7+json' \\\n    -H 'Date: Mon, 05 Nov 2018 13:14:41 GMT' \\\n    -H 'Authorization: Uploadcare YOUR_PUBLIC_KEY:SIGNATURE' \\\n    'https://api.uploadcare.com/files/?limit=1&stored=true'\n```\n"
    Uploadcare.Simple:
      type: apiKey
      in: header
      name: Uploadcare.Simple
      description: 'Note: We DO NOT recommend using this authentication method in production.


        With the `Uploadcare.Simple` authentication method, `auth-param` is your `public_key:secret_key` pair. Note that in this scheme, your Uploadcare project `secret_key` is  _included in every request as plain text_.


        ```http

        Accept: application/vnd.uploadcare-v0.7+json

        Authorization: Uploadcare.Simple public_key:secret_key

        ```

        '