Create file

POST

core

files

curl --request POST \
  --url https://api.enterprise.sandbox.uphold.com/core/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "category": "image",
  "contentType": "image/png"
}'

{
  "file": {
    "id": "38cce774-b225-41ed-a9fd-f9c9777a13de",
    "status": "pending",
    "category": "image",
    "contentType": "image/png",
    "upload": {
      "url": "https://example.com/upload",
      "formData": {
        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
        "X-Amz-Credential": "ASIE4FQORBNQHNQD5CG6/20240801/us-east-1/s3/aws4_request",
        "X-Amz-Date": "20240801T102500Z",
        "X-Amz-Security-Token": "IQoJb3JpZ2luX2VjEIv//////////...JBr6h2HkzH/aFSArQcs=",
        "X-Amz-Signature": "b4da8cf1a59327988a8108c965a4789fc8ba2d20f5bffda076106b2b254def29",
        "Key": "4c13b6f5-987e-43df-bc12-042b58307a80",
        "Policy": "eyJjb25kaXRpb25zIjpbeyJidWN...TA6MjU6MDAuMjAyWiJ9"
      },
      "expiresAt": "2024-03-13T20:20:39Z"
    }
  }
}

Uploading a file is a two step process. You start by creating a placeholder for the file and then using the upload details of the response to actually upload the file. Each file has a unique id which is used across our API when you need to reference it.

Below you will find examples in several programming languages to do the upload:

The following example uses file-type package to determine the content-type of the file.

import { fileTypeFromFile } from 'file-type';
import fs from 'node:fs';

// Function to upload file.
// Takes `file` record from the response and `filePath` which points to the file on disk that needs to be uploaded.
const uploadFile = async (file, filePath) => {
  const { url, formData } =  file.upload;

  // Add form data.
  const form = new FormData();

  for (const [key, value] of Object.entries(formData)) {
    form.append(key, value);
  }

  // Add content type, determined by file-type package.
  // This must match the `contentType` of the file record.
  const { mime } = await fileTypeFromFile(filePath);

  form.append('Content-Type', mime);

  // Add file blob.
  const blob = await fs.openAsBlob(filePath)

  form.append('File', blob);

  const response = await fetch(url, {
    method: 'POST',
    body: form,
  });

  if (!response.ok) {
    throw new Error(`Failed to upload file: ${response.statusText}`);
  }

  console.log('File uploaded!')
};

Authorizations

Authorization

string

header

required

OAuth 2.0 authentication.

Body

application/json

Response

201

application/json

File created.

file

object

required

Accept terms of service Get file

curl --request POST \
  --url https://api.enterprise.sandbox.uphold.com/core/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "category": "image",
  "contentType": "image/png"
}'

{
  "file": {
    "id": "38cce774-b225-41ed-a9fd-f9c9777a13de",
    "status": "pending",
    "category": "image",
    "contentType": "image/png",
    "upload": {
      "url": "https://example.com/upload",
      "formData": {
        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
        "X-Amz-Credential": "ASIE4FQORBNQHNQD5CG6/20240801/us-east-1/s3/aws4_request",
        "X-Amz-Date": "20240801T102500Z",
        "X-Amz-Security-Token": "IQoJb3JpZ2luX2VjEIv//////////...JBr6h2HkzH/aFSArQcs=",
        "X-Amz-Signature": "b4da8cf1a59327988a8108c965a4789fc8ba2d20f5bffda076106b2b254def29",
        "Key": "4c13b6f5-987e-43df-bc12-042b58307a80",
        "Policy": "eyJjb25kaXRpb25zIjpbeyJidWN...TA6MjU6MDAuMjAyWiJ9"
      },
      "expiresAt": "2024-03-13T20:20:39Z"
    }
  }
}

Core API

Widgets API

Authorizations

Body

Response