Getting Started with Cloud

1. Create an Account

2. Create a Storage

In the dashboard, go to Storages and create a new storage. This is where your uploaded files will be stored. Note your Storage ID — you’ll need it for the client configuration.

3. Get Your API Key

Go to Settings > API Keys and create an API key. You’ll need this on your backend to exchange credentials with Uploadista Cloud.

UPLOADISTA_API_KEY=upl_sk_...

4. Set Up Your Backend Auth Endpoint

Your backend needs a single endpoint that exchanges your API key for a short-lived JWT token. This is the bridge between your auth system and Uploadista Cloud.

import { getAuthCredentials } from '@uploadista/server/auth';

export const GET = async (req: Request, ctx: { params: Promise<{ clientId: string }> }) => {
  const { clientId } = await ctx.params;

  // Optional: verify the user is authenticated with YOUR auth system
  // const session = await getSession(req);
  // if (!session) return new Response("Unauthorized", { status: 401 });

  const response = await getAuthCredentials({
    uploadistaClientId: clientId,
    uploadistaApiKey: process.env.UPLOADISTA_API_KEY!,
  });

  if (!response.isValid) {
    return Response.json({ error: response.error }, { status: 500 });
  }

  return Response.json(response.data);
};

import express from 'express';
import { getAuthCredentials } from '@uploadista/server/auth';

const app = express();

app.get('/api/auth/token/:clientId', async (req, res) => {
  const { clientId } = req.params;

  // Optional: verify user is authenticated
  // if (!req.session?.user) return res.status(401).json({ error: "Unauthorized" });

  const response = await getAuthCredentials({
    uploadistaClientId: clientId,
    uploadistaApiKey: process.env.UPLOADISTA_API_KEY!,
  });

  if (!response.isValid) {
    return res.status(500).json({ error: response.error });
  }

  res.json(response.data);
});

import { Hono } from 'hono';
import { getAuthCredentials } from '@uploadista/server/auth';

const app = new Hono();

app.get('/api/auth/token/:clientId', async (c) => {
  const clientId = c.req.param('clientId');

  // Optional: verify user is authenticated
  // const session = c.get('session');
  // if (!session) return c.json({ error: "Unauthorized" }, 401);

  const response = await getAuthCredentials({
    uploadistaClientId: clientId,
    uploadistaApiKey: c.env.UPLOADISTA_API_KEY,
  });

  if (!response.isValid) {
    return c.json({ error: response.error }, 500);
  }

  return c.json(response.data);
});

Install the auth helper:

npm install @uploadista/server

pnpm add @uploadista/server

yarn add @uploadista/server

5. Set Up the Client

Install the client SDK for your framework and configure it in uploadista-cloud mode:

import { UploadistaProvider } from "@uploadista/react";

function App() {
  return (
    <UploadistaProvider
      storageId="your-storage-id"
      auth={{
        mode: 'uploadista-cloud',
        authServerUrl: '/api/auth/token',
        clientId: process.env.NEXT_PUBLIC_UPLOADISTA_CLIENT_ID!
      }}
    >
      {/* Your app */}
    </UploadistaProvider>
  );
}

import { createUploadistaPlugin } from "@uploadista/vue";

app.use(createUploadistaPlugin({
  storageId: "your-storage-id",
  auth: {
    mode: 'uploadista-cloud',
    authServerUrl: '/api/auth/token',
    clientId: import.meta.env.VITE_UPLOADISTA_CLIENT_ID
  }
}));

import { createUploadistaClient } from "@uploadista/expo";

const client = createUploadistaClient({
  storageId: "your-storage-id",
  auth: {
    mode: 'uploadista-cloud',
    authServerUrl: 'https://api.yourapp.com/auth/token',
    clientId: 'your-client-id'
  }
});

6. Upload a File

That’s it — you’re ready to upload files through Uploadista Cloud:

Upload component
useUpload hook

import { Upload } from "@uploadista/react";

function FileUploader() {
  return (
    <Upload onSuccess={(result) => console.log("Uploaded:", result)}>
      <Upload.DropZone accept="image/*">
        {({ isDragging, getRootProps, getInputProps }) => (
          <div {...getRootProps()}>
            <input {...getInputProps()} />
            {isDragging ? "Drop your file here" : "Click or drag to upload"}
          </div>
        )}
      </Upload.DropZone>

      <Upload.Progress>
        {({ progress, isUploading }) =>
          isUploading && <progress value={progress} max={100} />
        }
      </Upload.Progress>

      <Upload.Error>
        {({ hasError, failedItems, reset }) =>
          hasError && (
            <div>
              <p>Upload failed: {failedItems[0]?.state.error?.message}</p>
              <button onClick={reset}>Dismiss</button>
            </div>
          )
        }
      </Upload.Error>
    </Upload>
  );
}

import { useUpload } from "@uploadista/react";

function UploadButton() {
  const upload = useUpload({
    onSuccess: (result) => console.log("Uploaded:", result),
  });

  return (
    <div>
      <input
        type="file"
        onChange={(e) => {
          const file = e.target.files?.[0];
          if (file) upload.upload(file);
        }}
      />
      {upload.isUploading && <progress value={upload.state.progress} max={100} />}
    </div>
  );
}

7. Create a Flow (Optional)

To process files after upload, create a flow in the dashboard:

Go to Flows in the dashboard
Click Create Flow
Build your processing pipeline with the visual editor
Save and activate the flow
Use it from the client:

Flow component
useFlow hook

import { Flow } from "@uploadista/react";

function ImageUploader() {
  return (
    <Flow
      flowId="your-flow-id"
      storageId="your-storage-id"
      onSuccess={(outputs) => console.log("Processed:", outputs)}
    >
      <Flow.DropZone accept="image/*">
        {({ isDragging, getRootProps, getInputProps }) => (
          <div {...getRootProps()}>
            <input {...getInputProps()} />
            {isDragging ? "Drop your image here" : "Click or drag to upload"}
          </div>
        )}
      </Flow.DropZone>

      <Flow.Status>
        {({ status, currentNodeName }) => (
          <p>{status === "processing" ? `Processing: ${currentNodeName}` : status}</p>
        )}
      </Flow.Status>

      <Flow.Error>
        {({ hasError, message, reset }) =>
          hasError && (
            <div>
              <p>Error: {message}</p>
              <button onClick={reset}>Try again</button>
            </div>
          )
        }
      </Flow.Error>
    </Flow>
  );
}

import { useFlow } from "@uploadista/react";

function ImageUploader() {
  const flow = useFlow({
    flowConfig: {
      flowId: "your-flow-id",
      storageId: "your-storage-id",
    },
    onSuccess: (outputs) => console.log("Processed:", outputs),
  });

  return (
    <div>
      <input
        type="file"
        accept="image/*"
        onChange={(e) => {
          const file = e.target.files?.[0];
          if (file) flow.upload(file);
        }}
      />
      {flow.isUploading && (
        <div>
          <progress value={flow.state.progress} max={100} />
          {flow.state.currentNodeName && <p>Processing: {flow.state.currentNodeName}</p>}
        </div>
      )}
    </div>
  );
}

Next Steps

Integration Guide — Detailed setup for each framework with full examples
Flows Engine — Understand how flows work under the hood
React Client — Full React SDK reference
Vue Client — Full Vue SDK reference
Expo Client — Full Expo SDK reference