Skip to main content

Getting Started

Get up and running with the Nosible API Client in just a few minutes!

Prerequisites​

  • Node.js v20+ or Bun v1.0+
  • TypeScript v5+ (for TypeScript projects)
  • A Nosible API key (sign up at nosible.ai)

Installation​

# Using npm
npm install nosible

# Using yarn
yarn add nosible

# Using bun
bun add nosible

# Using pnpm
pnpm add nosible

API Key Setup​

info

Important: If you are using version 2 API keys (nos_sk_...), please upgrade to nosible version 0.2.16 or later.

You can provide your API key in several ways:

Set environment variables:

# On macOS/Linux
export NOSIBLE_API_KEY="basic|your-api-key-here"
export LLM_API_KEY="sk-..."  # Optional, for LLM features

# On Windows (PowerShell)
$Env:NOSIBLE_API_KEY="basic|your-api-key-here"
$Env:LLM_API_KEY="sk-..."  # Optional

Then the client will automatically use them:

import {NosibleClient} from "nosible";

const client = new NosibleClient();

Option 2: Direct Initialization​

Pass the API key directly when creating the client:

import {NosibleClient} from "nosible";

// Simple string API key
const client = new NosibleClient("basic|your-api-key-here");

// Or with full configuration
const client = new NosibleClient({
  apiKey: "basic|your-api-key-here",
  llmApiKey: "sk-...", // Optional, for AI-powered features
});

Option 3: With Default Search Parameters​

Set default parameters to apply to all searches:

import {NosibleClient} from "nosible";

const client = new NosibleClient({
  searchDefaults: {
    nResults: 50,
    algorithm: "hybrid-2",
    continent: "North America",
  },
});

Quick Example​

Here's a simple example to get you started:

import {NosibleClient} from "nosible";

// Initialize the client
const client = new NosibleClient();

// Perform a fast search
const results = await client.fastSearch({
  question: "Who has invested in Nosible?",
  nResults: 15,
});

// Display results
console.log(`Found ${results.length} results`);
for (const result of results) {
  console.log(`Title: ${result.title}`);
  console.log(`URL: ${result.url}`);
  console.log(`Similarity: ${result.semantics.similarity.toFixed(4)}`);
  console.log(`Published: ${result.published}`);
  console.log();
}

Understanding Search Types​

Optimized for quick results with configurable limits:

const results = await client.fastSearch({
  question: "What is artificial intelligence?",
  nResults: 20, // 10-100 results
});
  • Speed: Fastest (typically < 1 second)
  • Use case: Real-time applications, interactive search, dashboards
  • Result range: 10-100 results

Advanced search with custom instructions and AI agents:

const results = await client.aiSearch({
  prompt: "Find recent technical blogs about machine learning optimization",
  agent: "research",
});
  • Speed: Moderate (2-5 seconds)
  • Use case: Research, in-depth analysis, complex queries
  • Features: Custom instructions, AI agents, context-aware results

Large-scale data retrieval for comprehensive analysis:

const results = await client.bulkSearch({
  question: "AI market trends",
  nResults: 5000, // 1000-10000 results
});

console.log(`Retrieved ${results.length} results`);
  • Speed: Slower (varies by size)
  • Use case: Data analysis, market research, batch processing
  • Result range: 1000-10000 results

Response Structure​

All search methods return a ResultSet object that is iterable:

const results = await client.fastSearch({
  question: "Your query",
});

// ResultSet is iterable and has array-like methods
console.log(`Total results: ${results.length}`);

// Iterate through results
for (const result of results) {
  console.log(result.title); // Article/page title
  console.log(result.url); // Source URL
  console.log(result.description); // Brief description
  console.log(result.content); // Full text content
  console.log(result.best_chunk); // Most relevant excerpt
  console.log(result.published); // Publication date (ISO 8601)
  console.log(result.author); // Author name
  console.log(result.netloc); // Domain name
  console.log(result.language); // Language code

  // Semantic search information
  console.log(result.semantics.similarity); // Relevance score (0-1)
  console.log(result.semantics.chunks_total); // Total chunks
  console.log(result.semantics.chunks_matched); // Matched chunks

  // Geographic and industry classifications
  console.log(result.continent); // Continent
  console.log(result.country); // Country code
  console.log(result.industry); // Industry classification
}

// Array methods work too
const highQuality = results.filter((r) => r.semantics.similarity > 0.8);
const titles = results.map((r) => r.title);

Error Handling​

Always wrap API calls in try-catch blocks:

import {NosibleClient} from "nosible";

const client = new NosibleClient();

try {
  const results = await client.fastSearch({
    question: "Your question here",
    nResults: 20,
  });

  // Process results
  console.log(`Found ${results.length} results`);
  for (const result of results) {
    console.log(result.title);
  }
} catch (error) {
  if (error instanceof Error) {
    console.error("Search failed:", error.message);
  }
}

Type-Safe Filtering with Enums​

The client exports Zod-backed enum types for every filterable field. Importing them gives you full IntelliSense autocomplete and a compile-time error if you pass an invalid value.

import {
  NosibleClient,
  languageEnum,
  countryEnum,
  continentEnum,
  regionEnum,
  sectorEnum,
  industryGroupEnum,
  industryEnum,
  subIndustryEnum,
  iabTier1Enum,
  iabTier2Enum,
  iabTier3Enum,
  iabTier4Enum,
  algorithmEnum,
  brandSafetyEnum,
} from "nosible";

Use the .enum values directly for autocomplete, or pass the string literal — both work at runtime:

const client = new NosibleClient();

const results = await client.fastSearch({
  question: "clean energy investment",
  nResults: 20,
  language: "en", // LanguageEnum — ISO 639-1 code
  country: "United States", // CountryEnum — full country name
  sector: "Energy", // SectorEnum — GICS sector
  iabTier1: "Science", // IabTier1Enum — IAB content category
  brandSafety: "Safe", // BrandSafetyEnum — "Safe" | "Sensitive" | "Unsafe"
});
tip

The enum values are sourced directly from the Nosible OpenAPI spec. If an invalid value is passed (e.g. brandSafety: "safe" instead of "Safe"), TypeScript will report an error at compile time.

See the Filtering Reference for the complete list of accepted values for every enum.

Additional Features​

URL Scraping​

Extract structured content from any web page:

const webpage = await client.scrapeUrl("https://example.com/article");

console.log(webpage.title);
console.log(webpage.author);
console.log(webpage.content);
console.log(webpage.published);

Analyze topic popularity over time:

const trends = await client.topicTrend("artificial intelligence");

console.log(`Topic: ${trends.data.query.query}`);
// trends.data.response is an object with dates as keys and popularity as values
Object.entries(trends.data.response).forEach(([date, popularity]) => {
  console.log(`${date}: ${popularity}`);
});

Parallel Searches​

Execute multiple searches concurrently:

const results = await client.fastSearches({
  questions: ["AI in healthcare", "AI in finance", "AI in education"],
  nResults: 20,
});

results.forEach((resultSet, index) => {
  console.log(`Query ${index + 1}: ${resultSet.length} results`);
});

Next Steps​

  • Check out Examples for more use cases
  • Explore the API Reference for detailed documentation
  • Learn about advanced filtering and configuration options

Need Help?​