Quickstart

This guide takes you from zero to your first uploaded file. It should take about five minutes.

Step 1 — Create a project

Sign up at apulodi.com/sign-up.
Create an organization.
Create a project inside the organization.

Every project is fully isolated — files, folders and API keys are scoped to it and nothing else.

Step 2 — Create an API key

Open your project and go to API Keys. Create a key for the test environment while you experiment.

The raw key looks like apk_live_... (or apk_test_...). It is shown exactly once — copy it into your environment immediately. Anyone with this key has full access to the project's files.

env

APULODI_API_KEY=apk_test_your_key_here

Step 3 — Install the SDK

bash

npm install @apulodi/sdk

Or with your preferred package manager:

bash

pnpm add @apulodi/sdk

bash

yarn add @apulodi/sdk

Step 4 — Upload a file

import { readFile } from "node:fs/promises";
import { Apulodi } from "@apulodi/sdk";

const apulodi = new Apulodi({
  apiKey: process.env.APULODI_API_KEY!,
});

const data = await readFile("avatar.jpg");

const file = await apulodi.files.upload({
  file: data,
  fileName: "avatar.jpg",
  contentType: "image/jpeg",
  path: "users/avatars",        // optional logical folder
  metadata: { userId: "u_123" } // optional custom metadata
});

console.log(file.id);    // file_…
console.log(file.status); // "uploaded"

The same flow over the raw API:

bash

# 1. Request a presigned upload URL
curl -X POST https://api.apulodi.com/v1/files/upload \
  -H "Authorization: Bearer $APULODI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "avatar.jpg",
    "contentType": "image/jpeg",
    "size": 245123,
    "path": "users/avatars",
    "metadata": { "userId": "u_123" }
  }'

The response includes an upload.url — PUT your bytes there directly:

bash

# 2. Upload straight to storage (never through APULODI's servers)
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @avatar.jpg

# 3. Tell APULODI the upload is done
curl -X POST https://api.apulodi.com/v1/files/file_xxxxxx/complete \
  -H "Authorization: Bearer $APULODI_API_KEY"

Step 5 — Retrieve the file

const file = await apulodi.files.get("file_xxxxxx");

file.filename;    // "avatar.jpg"
file.contentType; // "image/jpeg"
file.size;        // 245123
file.version;     // 1
file.metadata;    // { userId: "u_123" }

Step 6 — Generate a download URL

const { url } = await apulodi.files.downloadUrl("file_xxxxxx", {
  expiresInSeconds: 300, // 5 minutes
});

The URL points directly at storage and expires automatically. Your users download from there, not from APULODI's application servers.

Next: understand how authentication works in Authentication, or jump straight into the Files API.

← Introduction

Authentication →