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](https://uploadcare.com/docs/integrations/) that cover most of the popular programming languages and frameworks.


    # Authentication

    <!-- ReDoc-Inject: <security-definitions> -->

    '
  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. 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:
  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:
    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.
    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.
    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
  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
        - 'null'
        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
  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

        ```

        '