Uploading Files

NoCloud uses a two-step upload process:

Get a signed URL from the Generate Signed URL endpoint
Upload the file directly to the signed URL

There are two modes depending on whether you provide query parameters:

Non-allocated: No query parameters — returns a signed URL. Upload with a POST request using form data.
Pre-allocated: Pass contentType and size as query parameters to pre-allocate storage — returns a signed URL along with mediaId and mediaUrl. Upload with a PUT request.

This approach allows for efficient, direct-to-storage uploads without proxying through your backend.

Simple Upload (Non-allocated)

# Step 1: Get signed URL
SIGNED_URL_RESPONSE=$(curl -s -X GET \
  "https://api.nonefivem.com/cloud/storage/signed-url" \
  -H "Authorization: Bearer your-api-key")

# Extract the signed URL

UPLOAD_URL=$(echo $SIGNED_URL_RESPONSE | jq -r '.url')

# Step 2: Upload file via POST with form data

curl -X POST "$UPLOAD_URL" \
 -F "file=@./screenshot.png" \
 -F 'metadata={"category":"screenshots"}'

async function uploadFile(file) {
  // Step 1: Get signed URL
  const signedUrlResponse = await fetch(
    "https://api.nonefivem.com/cloud/storage/signed-url",
    {
      headers: {
        Authorization: "Bearer your-api-key"
      }
    }
  );

  if (!signedUrlResponse.ok) {
    throw new Error("Failed to get signed URL");
  }

  const { url } = await signedUrlResponse.json();

  // Step 2: Upload file via POST with form data
  const formData = new FormData();
  formData.append("file", file);
  // Optionally attach metadata
  formData.append("metadata", JSON.stringify({ category: "screenshots" }));

  const uploadResponse = await fetch(url, {
    method: "POST",
    body: formData
  });

  if (!uploadResponse.ok) {
    throw new Error("Failed to upload file");
  }

  return await uploadResponse.json();
}

// Usage
const file = document.querySelector('input[type="file"]').files[0];
const result = await uploadFile(file);
console.log("File uploaded:", result);

async function uploadFile(file: File | Blob): Promise<unknown> {
  // Step 1: Get signed URL
  const signedUrlResponse = await fetch(
    "https://api.nonefivem.com/cloud/storage/signed-url",
    {
      headers: {
        Authorization: "Bearer your-api-key"
      }
    }
  );

  if (!signedUrlResponse.ok) {
    throw new Error("Failed to get signed URL");
  }

  const { url } = await signedUrlResponse.json();

  // Step 2: Upload file via POST with form data
  const formData = new FormData();
  formData.append("file", file);
  // Optionally attach metadata
  formData.append("metadata", JSON.stringify({ category: "screenshots" }));

  const uploadResponse = await fetch(url, {
    method: "POST",
    body: formData
  });

  if (!uploadResponse.ok) {
    throw new Error("Failed to upload file");
  }

  return await uploadResponse.json();
}

Pre-allocated Upload

Pass contentType and size to pre-allocate storage. The response includes mediaId and mediaUrl so you know the file’s location before uploading.

# Step 1: Get signed URL with pre-allocation
SIGNED_URL_RESPONSE=$(curl -s -X GET \
  "https://api.nonefivem.com/cloud/storage/signed-url?contentType=image/png&size=1048576" \
  -H "Authorization: Bearer your-api-key")

# Extract the signed URL

UPLOAD_URL=$(echo $SIGNED_URL_RESPONSE | jq -r '.url')

# Step 2: Upload file to signed URL via PUT

curl -X PUT "$UPLOAD_URL" \
 -H "Content-Type: image/png" \
 --data-binary @./screenshot.png

async function uploadFile(file) {
  // Step 1: Get signed URL with pre-allocation
  const params = new URLSearchParams({
    contentType: file.type,
    size: file.size.toString()
  });

  const signedUrlResponse = await fetch(
    `https://api.nonefivem.com/cloud/storage/signed-url?${params}`,
    {
      headers: {
        Authorization: "Bearer your-api-key"
      }
    }
  );

  if (!signedUrlResponse.ok) {
    throw new Error("Failed to get signed URL");
  }

  const { url, mediaId, mediaUrl } = await signedUrlResponse.json();

  // Step 2: Upload file directly to signed URL via PUT
  const uploadResponse = await fetch(url, {
    method: "PUT",
    body: file
  });

  if (!uploadResponse.ok) {
    throw new Error("Failed to upload file");
  }

  // Return the file info
  return { id: mediaId, url: mediaUrl };
}

// Usage
const file = document.querySelector('input[type="file"]').files[0];
const { id, url } = await uploadFile(file);
console.log("File uploaded:", url);

interface SignedUrlResponse {
  url: string;
  expiresAt: string;
  mediaId: string;
  mediaUrl: string;
}

interface UploadResult {
  id: string;
  url: string;
}

async function uploadFile(file: File | Blob): Promise<UploadResult> {
  // Step 1: Get signed URL with pre-allocation
  const params = new URLSearchParams({
    contentType: file.type,
    size: file.size.toString()
  });

  const signedUrlResponse = await fetch(
    `https://api.nonefivem.com/cloud/storage/signed-url?${params}`,
    {
      headers: {
        Authorization: "Bearer your-api-key"
      }
    }
  );

  if (!signedUrlResponse.ok) {
    throw new Error("Failed to get signed URL");
  }

  const { url, mediaId, mediaUrl }: SignedUrlResponse =
    await signedUrlResponse.json();

  // Step 2: Upload file directly to signed URL via PUT
  const uploadResponse = await fetch(url, {
    method: "PUT",
    body: file
  });

  if (!uploadResponse.ok) {
    throw new Error("Failed to upload file");
  }

  return { id: mediaId, url: mediaUrl };
}

Upload with Metadata (Pre-allocated)

When using the pre-allocated flow, you can attach metadata via query parameters:

const params = new URLSearchParams({
  contentType: "image/png",
  size: file.size.toString(),
  // Metadata as JSON string
  metadata: JSON.stringify({
    oderId: "order_123",
    visitorId: 456,
    isPublic: true
  })
});

const response = await fetch(
  `https://api.nonefivem.com/cloud/storage/signed-url?${params}`,
  {
    headers: { Authorization: "Bearer your-api-key" }
  }
);

Metadata constraints: - Maximum 10 keys - Key names: alphanumeric, underscores, hyphens only (max 128 chars) - Values: string (max 512 chars), number, or boolean - Total metadata size: max 2KB

Upload with Progress Tracking

For larger files, you may want to track upload progress. This example uses the pre-allocated flow:

async function uploadWithProgress(file, onProgress) {
  // Get signed URL with pre-allocation
  const { url, mediaId, mediaUrl } = await getSignedUrl(file);

  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();

    xhr.upload.addEventListener("progress", (event) => {
      if (event.lengthComputable) {
        const percentComplete = (event.loaded / event.total) * 100;
        onProgress(percentComplete);
      }
    });

    xhr.addEventListener("load", () => {
      if (xhr.status >= 200 && xhr.status < 300) {
        resolve({ mediaId, mediaUrl });
      } else {
        reject(new Error(`Upload failed with status ${xhr.status}`));
      }
    });

    xhr.addEventListener("error", () => reject(new Error("Upload failed")));

    xhr.open("PUT", url);
    xhr.setRequestHeader("Content-Type", file.type);
    xhr.send(file);
  });
}

// Usage
await uploadWithProgress(file, (progress) => {
  console.log(`Upload progress: ${progress.toFixed(1)}%`);
});

Signed URLs expire after 15 minutes. Generate a new URL if the upload doesn’t complete in time.

API Reference

Storage

Uploading Files

Simple Upload (Non-allocated)

Pre-allocated Upload

Upload with Metadata (Pre-allocated)

Upload with Progress Tracking

​Simple Upload (Non-allocated)

​Pre-allocated Upload

​Upload with Metadata (Pre-allocated)

​Upload with Progress Tracking

Simple Upload (Non-allocated)

Pre-allocated Upload

Upload with Metadata (Pre-allocated)

Upload with Progress Tracking