Skip to main content

TypeScript SDK Quickstart

The @alien/data-api-client package provides a fully typed TypeScript client for the Data API. It is auto-generated from the OpenAPI specification and includes TypeScript interfaces for all request and response types.

Requirements​

  • Node.js 18 or later
  • npm, yarn, or pnpm

Installation​

The package is published to the Alien Intelligence GitLab npm registry under the @alien scope.

Step 1: Configure the Registry​

Set up npm to use the GitLab registry for the @alien scope (one-time setup):

npm config set @alien:registry https://gitlab.com/api/v4/projects/75857874/packages/npm/

Or add to your project's .npmrc file (recommended for teams):

@alien:registry=https://gitlab.com/api/v4/projects/75857874/packages/npm/

Step 2: Install​

npm install @alien/data-api-client

Or with yarn/pnpm:

yarn add @alien/data-api-client
# or
pnpm add @alien/data-api-client
info

Configuration​

Alien Hosted (Default)​

For Alien Hosted deployments, requests go through the platform proxy:

import { Configuration, DatasetsApi, EntriesApi } from "@alien/data-api-client";

const config = new Configuration({
  basePath: "https://api.alien.club/clusters/YOUR_CLUSTER_ID/proxy",
  headers: {
    Authorization: "Bearer oat_YOUR_API_TOKEN",
  },
});

Get your API token from the Keys section in the platform dashboard. See Manage Your Organization for details.

On-Premise (Direct Access)​

For on-premise deployments where you have direct access to the data cluster:

const config = new Configuration({
  basePath: "https://your-data-cluster.internal.example.com",
  headers: {
    Authorization: "Bearer YOUR_SERVICE_API_KEY",
  },
});

Basic Operations​

List Datasets​

import { Configuration, DatasetsApi } from "@alien/data-api-client";

const config = new Configuration({
  basePath: "https://api.alien.club/clusters/YOUR_CLUSTER_ID/proxy",
  headers: { Authorization: "Bearer oat_YOUR_API_TOKEN" },
});

const datasetsApi = new DatasetsApi(config);

const datasets = await datasetsApi.listDatasets();
for (const dataset of datasets) {
  console.log(`${dataset.id}: ${dataset.name} (${dataset.entryCount} entries)`);
}

Get a Dataset​

const dataset = await datasetsApi.getDataset({ id: 1 });
console.log(`Name: ${dataset.name}`);
console.log(`Schema: ${JSON.stringify(dataset.schema)}`);
console.log(`Entries: ${dataset.entryCount}`);

Batch Get Entries​

Efficiently retrieve multiple entries in a single request:

import { EntriesApi } from "@alien/data-api-client";

const entriesApi = new EntriesApi(config);

const response = await entriesApi.batchGetEntries({
  entryBatchRequest: {
    dataset_id: 1,
    limit: 50,
  },
});

console.log(`Retrieved ${response.entries.length} entries`);
for (const entry of response.entries) {
  console.log(`  ${entry.id}: ${entry.name} — ${entry.status}`);
}
import { SearchApi } from "@alien/data-api-client";

const searchApi = new SearchApi(config);

const results = await searchApi.keywordSearch({
  keywordSearchRequest: {
    query: "protein folding",
    dataset_ids: [1, 2],
    limit: 20,
  },
});

for (const hit of results.hits) {
  console.log(`${hit.name} — score: ${hit.score}`);
}

Vector Search (Semantic)​

const results = await searchApi.vectorSearchChunks({
  vectorSearchRequest: {
    query: "novel approaches to protein structure prediction",
    dataset_ids: [1],
    score_threshold: 0.7,
    limit: 10,
  },
});

for (const chunk of results.results) {
  console.log(`Score: ${chunk.score.toFixed(2)}`);
  console.log(`Text: ${chunk.chunkText.slice(0, 150)}...`);
  console.log();
}

Health Check​

import { HealthApi } from "@alien/data-api-client";

const healthApi = new HealthApi(config);

const health = await healthApi.healthCheck();
console.log(`Status: ${health.status}`);
console.log(`Database: ${health.database}`);

Error Handling​

API errors throw ResponseError with the full HTTP response:

import { ResponseError } from "@alien/data-api-client";

try {
  const dataset = await datasetsApi.getDataset({ id: 999 });
} catch (error) {
  if (error instanceof ResponseError) {
    console.error(`API Error: ${error.response.status}`);
    const body = await error.response.json();
    console.error("Details:", body);
  } else {
    console.error("Unexpected error:", error);
  }
}

Common error codes:

StatusMeaning
401Authentication failed — check your API token
403Insufficient permissions — check your role and token abilities
404Resource not found — verify the ID exists
422Validation error — check request parameters
503Data cluster unavailable — the cluster may be offline or unreachable

Advanced Configuration​

Custom Middleware​

Add request/response middleware for logging, metrics, or header injection:

const config = new Configuration({
  basePath: "https://api.alien.club/clusters/YOUR_CLUSTER_ID/proxy",
  headers: { Authorization: "Bearer oat_YOUR_API_TOKEN" },
  middleware: [
    {
      pre: async (context) => {
        console.log(`Request: ${context.url}`);
        return context;
      },
      post: async (context) => {
        console.log(`Response: ${context.response.status}`);
        return context.response;
      },
    },
  ],
});

Custom Fetch Implementation​

If you need to use a custom HTTP client (e.g., for proxy support or custom TLS):

const config = new Configuration({
  basePath: "https://api.alien.club/clusters/YOUR_CLUSTER_ID/proxy",
  headers: { Authorization: "Bearer oat_YOUR_API_TOKEN" },
  fetchApi: customFetchImplementation,
});

Next Steps​