Skip to main content

​
Installation

npm install @avala/sdk

​
Quick Start

import Avala from "@avala/sdk";

const avala = new Avala({ apiKey: "your-api-key" });

const datasets = await avala.datasets.list();
for (const dataset of datasets.items) {
  console.log(dataset.name, dataset.uid);
}

​
Authentication

The SDK authenticates using your Avala API key, which is sent via the X-Avala-Api-Key header on every request. You can provide the key directly or let the SDK read it from the environment. Option 1: Pass the key directly 
import Avala from "@avala/sdk";

const avala = new Avala({ apiKey: "your-api-key" });
Option 2: Use an environment variable 
export AVALA_API_KEY="your-api-key"

import Avala from "@avala/sdk";

// Automatically reads AVALA_API_KEY from the environment
const avala = new Avala();

​
Working with Datasets

​
List Datasets

const datasets = await avala.datasets.list();

for (const dataset of datasets.items) {
  console.log(`${dataset.name} (${dataset.uid})`);
  console.log(`  Items: ${dataset.itemCount}`);
  console.log(`  Created: ${dataset.createdAt}`);
}

​
Get a Dataset

const dataset = await avala.datasets.get("550e8400-e29b-41d4-a716-446655440000");

console.log(dataset.name);
console.log(dataset.slug);
console.log(dataset.itemCount);

​
Working with Projects

​
List Projects

const projects = await avala.projects.list();

for (const project of projects.items) {
  console.log(`${project.name} (${project.uid})`);
  console.log(`  Status: ${project.status}`);
  console.log(`  Created: ${project.createdAt}`);
}

​
Get a Project

const project = await avala.projects.get("770a9600-g40d-63f6-c938-668877660000");

console.log(project.name);
console.log(project.status);

​
Working with Tasks

​
List Tasks

const tasks = await avala.tasks.list({
  project: "770a9600-g40d-63f6-c938-668877660000",
  status: "pending",
});

for (const task of tasks.items) {
  console.log(`${task.uid} — ${task.name} (${task.status})`);
}

​
Get a Task

const task = await avala.tasks.get("990c1800-i62f-85h8-e150-880099880000");

console.log(task.name);
console.log(task.status);

​
Working with Exports

​
Create an Export

const exportJob = await avala.exports.create({
  project: "770a9600-g40d-63f6-c938-668877660000",
});

console.log(`Export started: ${exportJob.uid}`);
console.log(`Status: ${exportJob.status}`);

​
Poll for Completion

let exportJob = await avala.exports.create({
  project: "770a9600-g40d-63f6-c938-668877660000",
});

while (exportJob.status !== "completed") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  exportJob = await avala.exports.get(exportJob.uid);
  console.log(`Status: ${exportJob.status}`);
}

console.log(`Download: ${exportJob.downloadUrl}`);

​
TypeScript Types

The SDK exports full TypeScript interfaces for all API objects. Use them to type your functions and variables. 
import Avala from "@avala/sdk";
import type { Dataset, Project, Export, Task, CursorPage } from "@avala/sdk";

function processDataset(dataset: Dataset): void {
  console.log(dataset.name);       // string
  console.log(dataset.uid);        // string
  console.log(dataset.itemCount);  // number
  console.log(dataset.createdAt);  // string | null
}

function processTask(task: Task): void {
  console.log(task.uid);           // string
  console.log(task.name);          // string | null
  console.log(task.status);        // string | null
  console.log(task.project);       // string | null
}

​
Error Handling

The SDK throws typed errors so you can handle different failure modes precisely. 
import Avala, { AvalaError, NotFoundError, RateLimitError } from "@avala/sdk";

const avala = new Avala();

try {
  const dataset = await avala.datasets.get("nonexistent");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`Dataset not found: ${error.message}`);
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds.`);
  } else if (error instanceof AvalaError) {
    console.log(`API error (${error.statusCode}): ${error.message}`);
  } else {
    throw error;
  }
}
ExceptionDescription
AvalaErrorBase error class for all Avala API errors.
AuthenticationErrorInvalid or missing API key (HTTP 401).
NotFoundErrorThe requested resource does not exist (HTTP 404).
RateLimitErrorYou have exceeded the API rate limit (HTTP 429). Includes a retryAfter property.
ValidationErrorThe request payload failed validation (HTTP 400/422).
ServerErrorThe server returned an internal error (HTTP 5xx).

​
Pagination

List methods return a CursorPage<T> object with cursor-based pagination. 
// Access items on the current page
const page = await avala.datasets.list({ limit: 10 });
for (const dataset of page.items) {
  console.log(dataset.name);
}

// Fetch the next page
if (page.hasMore) {
  const nextPage = await avala.datasets.list({
    limit: 10,
    cursor: page.nextCursor!,
  });
}

​
Configuration

You can customize the client behavior at initialization time. 
import Avala from "@avala/sdk";

const avala = new Avala({
  apiKey: "your-api-key",
  baseUrl: "https://server.avala.ai/api/v1", // Default
  timeout: 60_000,    // Request timeout in ms (default: 30000)
  maxRetries: 3,      // Number of retries on transient errors (default: 2)
});
ParameterTypeDefaultDescription
apiKeystringAVALA_API_KEY env varYour Avala API key.
baseUrlstringhttps://server.avala.ai/api/v1The API base URL.
timeoutnumber30000Request timeout in milliseconds.
maxRetriesnumber2Number of automatic retries on transient failures (5xx, timeouts).

​
Zero Dependencies

The @avala/sdk package has zero runtime dependencies. It uses the native fetch API available in Node.js 18+, Deno, and Bun.

​
Framework Examples

​
Next.js (App Router)

// app/api/datasets/route.ts
import Avala from "@avala/sdk";
import { NextResponse } from "next/server";

const avala = new Avala({ apiKey: process.env.AVALA_API_KEY! });

export async function GET() {
  const datasets = await avala.datasets.list();
  return NextResponse.json(datasets);
}

​
Express

import express from "express";
import Avala from "@avala/sdk";

const app = express();
const avala = new Avala(); // Reads AVALA_API_KEY from env

app.get("/datasets", async (req, res) => {
  try {
    const datasets = await avala.datasets.list();
    res.json(datasets);
  } catch (error) {
    res.status(500).json({ error: "Failed to fetch datasets" });
  }
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});