^^

Presigned URLs

Presigned URLs are an essential part of Uploadjoy and S3. They allow you to securely share the ability access and upload objects, operations that would otherwise be private. You can read more about presigned URLs in the S3 documentation.

The Uploadjoy API provides a number of endpoints that allow you to generate presigned URLs for uploading and downloading objects. You can use these endpoints to generate presigned URLs on behalf of your users so they can upload and download objects without having to share their API token.

Presigned URL options model

You can configure the presigned URL returned by the API by passing an object to the optional presignedUrlOptions parameter to any of the endpoints below. The following properties are available:

  • Name
    expiresIn
    Type
    integer
    Description

    The number of seconds before the presigned URL expires. Defaults to 3600 seconds (1 hour).

POST/v1/presigned-url/get-private-object

Access private objects

This endpoint allows you to get presigned URLs to access and download private objects stored in S3.

Required attributes

  • Name
    keys
    Type
    string[]
    Description

    Keys of the objects to get presigned URLs for.

Optional attributes

Request

POST
/v1/presigned-url/get-private-object
import { Uploadjoy } from "@uploadjoy/client";

const ujClient = new Uploadjoy({
  apiToken: process.env.UPLOADJOY_API_TOKEN,
});

const keys = ["my-private-file.jpg"];
const response = await ujClient.presignedUrl
  .downloadPrivateObjects(
    {
      keys,
      presignedUrlOptions: { expiresIn: 3600 },
    }
  );

Response

type Response {
  data?: {
    presignedUrls: {
      key: string;
      // presigned URL for key
      url?: string;
      // error getting presigned URL for specific key
      error?: string;
    }[];
  }
  httpError?: HTTPError
}
POST/v1/presigned-url/put-objects

Upload an object

This endpoint allows you to get presigned URLs to upload objects.

Required attributes

  • Name
    objects
    Type
    Object[]
    Description

    List of Object to create presigned URLs for.

Object

type Object {
  key: string;
  visibility: "public" | "private";
  presignedUrlOptions?: PresignedUrlOptions;
}

Optional attributes

Request

POST
/v1/presigned-url/put-objects
import { Uploadjoy } from "@uploadjoy/client";

const ujClient = new Uploadjoy({
  apiToken: process.env.UPLOADJOY_API_TOKEN,
});

const response = await ujClient.presignedUrl
  .uploadObjects(
    {
      objects: [
        { key: "new.jpg", visibility: "private", },
      ]
    }
  );

Response

type Response {
  data?: {
    presignedUrls: {
      key: string;
      visibility: Visibility;
      url?: string;
      fields?: Record<string, string>;
      error?: string;
    }[];
  }
  httpError?: HTTPError;
}
POST/v1/presigned-url/multipart-upload-objects

Multipart upload an object

This endpoint allows you to get presigned URLs to upload objects using multipart upload. Read about S3 multipart upload here.

Required attributes

  • Name
    key
    Type
    string
    Description

    Key of the object.

  • Name
    visibility
    Type
    string
    Description

    "public" | "private"

  • Name
    filePartNames
    Type
    string[]
    Description

    List of names for each part of the file, in order.

Optional attributes

Request

POST
/v1/presigned-url/multipart-upload-objects
import { Uploadjoy } from "@uploadjoy/client";

const ujClient = new Uploadjoy({
  apiToken: process.env.UPLOADJOY_API_TOKEN,
});

const response = await ujClient.presignedUrl
  .multipartUploadObject({
    key: "key.jpg",
    filePartNames: ["part-1.jpg", "part-2.jpg"],
    visibility: "private",
  });

Response

type Response {
  data?: {
    key: string;
    visibility: "public" | "private";
    /*
      ID of the multi-part upload.
      Required for completing or aborting the upload.
    */
    uploadId: string;
    // presigned URLs to upload each part of the file
    presignedUrls:
    | {
        filePartName: string;
        url?: string;
        fields?: Record<string, string>;
        partNumber?: number;
        error?: string;
      }[];
    }
  httpError?: HTTPError;
}