Class Client

constructor

• new Client(token, tenantId, baseUrl?, options?): Client

• create new albatross sdk client instance

  initializes client with authentication credentials and optional custom configurations.

  Parameters

  • token: string

    api authentication bearer token
  • tenantId: string

    tenant/instance identifier (same value used for both auth header types)
  • baseUrl: string = hostDefault

    api base url (default: https://app.usealbatross.ai/api)
  • options: Partial<{
        makeRequest: (<A, B>(inputs: MakeRequestInputs<B>) => Promise<A>);
        predictionPreProcessing: ((data: PredictionPayload) => PredictionPayload);
    }> = {}

    optional client configuration

  Returns Client

  Example

  const client = new Client(
    "your-api-token",
    "tenant-uuid-123"
  );
  Copy

  Example

  // with custom base url
  const client = new Client(
    "token",
    "tenant-id",
    "https://custom.api.com"
  );
  Copy

makeRequest

predictionPreProcessing

token

tenantId

baseUrl

contentSelection

• contentSelection(request): Promise<ContentSelectionResponse>

• perform content selection (core method)

  low-level content selection method that all convenience methods use internally. supports all search modes: text, image, vector, item similarity, user recommendations. use specific convenience methods (search, searchByImage, etc.) for common use cases.

  Parameters

  • request: ContentSelectionRequest

    content selection request configuration

  Returns Promise<ContentSelectionResponse>

  promise resolving to search results with items, metadata, and optional debug info

  Throws

  if request validation fails

  Throws

  if image in options exceeds 50mb

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  const results = await client.contentSelection({
    use_case: "product-search",
    search: "red shoes",
    limit: 20
  });
  Copy

search

• search(query, useCase, options?): Promise<ContentSelectionResponse>

• perform text-based content search

  searches content using semantic text matching. ideal for product search, document retrieval, or any text-based similarity search. supports filtering, pagination, and performance tuning.

  Parameters

  • query: string

    search query text
  • useCase: string

    use case identifier for search
  • Optionaloptions: {
        limit?: number;
        filters?: ContentSelectionFilter;
        hnsw_ef?: number;
        with_payload?: boolean;
        with_vectors?: boolean;
        debug?: boolean;
    }

    optional search configuration

    • Optionallimit?: number

      max results to return (1-1000, default: varies)

    • Optionalfilters?: ContentSelectionFilter

      filter conditions to apply (use FilterBuilder to create)

    • Optionalhnsw_ef?: number

      hnsw search parameter for speed/accuracy tradeoff (higher = more accurate but slower)

    • Optionalwith_payload?: boolean

      include item metadata in results (default: false)

    • Optionalwith_vectors?: boolean

      include embedding vectors in results (default: false)

    • Optionaldebug?: boolean

      enable debug info in response (default: false)

  Returns Promise<ContentSelectionResponse>

  promise resolving to search results with matching items and metadata

  Throws

  if query is empty or useCase is invalid

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  const results = await client.search("red shoes", "product-search", {
    limit: 20,
    filters: new FilterBuilder().match("category", "footwear").build()
  });
  Copy

getRecommendations

• getRecommendations(useCase, params): Promise<ContentSelectionResponse>

• get personalized recommendations for user

  retrieves content recommendations based on user behavior and action history. can use user_id/session_id context or action sequence.

  Parameters

  • useCase: string

    use case identifier
  • params: {
        user_id?: string;
        session_id?: string;
        action_sequence?: string[];
        limit?: number;
        filters?: ContentSelectionFilter;
        with_payload?: boolean;
        with_vectors?: boolean;
        hnsw_ef?: number;
        debug?: boolean;
    }

    recommendation parameters

    • Optionaluser_id?: string

      user identifier (optional, pairs with session_id)

    • Optionalsession_id?: string

      session identifier (optional, pairs with user_id)

    • Optionalaction_sequence?: string[]

      array of item ids representing user actions (optional)

    • Optionallimit?: number

      max results to return (1-1000, default: 100)

    • Optionalfilters?: ContentSelectionFilter

      filter conditions to apply

    • Optionalwith_payload?: boolean

      include item metadata in results (default: true)

    • Optionalwith_vectors?: boolean

      include embedding vectors in results (default: true)

    • Optionalhnsw_ef?: number

      hnsw parameter (default: 256 when context provided, otherwise not set)

    • Optionaldebug?: boolean

      enable debug info in response (default: false)

  Returns Promise<ContentSelectionResponse>

  promise resolving to personalized recommendations

  Throws

  if useCase is empty or params are invalid

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  const recs = await client.getRecommendations("product-recs", {
    user_id: "user-123",
    session_id: "session-456",
    limit: 10
  });
  Copy

getSimilarItems

• getSimilarItems(itemId, useCase, options?): Promise<ContentSelectionResponse>

• find similar items by item id

  retrieves items similar to a given item. ideal for "similar products", "you may also like", or "related items" features.

  Parameters

  • itemId: string

    id of the reference item to find similarities for
  • useCase: string

    use case identifier
  • Optionaloptions: {
        limit?: number;
        with_payload?: boolean;
        with_vectors?: boolean;
        debug?: boolean;
    }

    optional configuration

    • Optionallimit?: number

      max results to return (1-1000, default: 100)

    • Optionalwith_payload?: boolean

      include item metadata in results (default: true)

    • Optionalwith_vectors?: boolean

      include embedding vectors in results (default: false)

    • Optionaldebug?: boolean

      enable debug info in response (default: false)

  Returns Promise<ContentSelectionResponse>

  promise resolving to similar items

  Throws

  if itemId is empty or useCase is invalid

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  const similar = await client.getSimilarItems("product-123", "product-similarity", {
    limit: 5
  });
  Copy

searchByImage

• searchByImage(image, useCase, options?): Promise<ContentSelectionResponse>

• search by image (visual/multimodal search)

  searches content using image similarity or combined image+text (multimodal). ideal for visual search, "find similar products by photo", or "search by image" features. supports combining image with text query for multimodal search.

  Parameters

  • image: string

    base64-encoded image string (max 50mb)
  • useCase: string

    use case identifier
  • Optionaloptions: {
        query?: string;
        limit?: number;
        filters?: ContentSelectionFilter;
        with_payload?: boolean;
        use_knn?: boolean;
        debug?: boolean;
    }

    optional search configuration

    • Optionalquery?: string

      optional text query for multimodal search (image + text)

    • Optionallimit?: number

      max results to return (1-1000, default: 100)

    • Optionalfilters?: ContentSelectionFilter

      filter conditions to apply

    • Optionalwith_payload?: boolean

      include item metadata in results (default: true)

    • Optionaluse_knn?: boolean

      use knn instead of hnsw for search (slower but potentially more accurate)

    • Optionaldebug?: boolean

      enable debug info in response (default: false)

  Returns Promise<ContentSelectionResponse>

  promise resolving to visually similar items

  Throws

  if image exceeds 50mb

  Throws

  if image is empty or useCase is invalid

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  const results = await client.searchByImage(base64Image, "visual-search", {
    limit: 10
  });
  Copy

searchByVector

• searchByVector(vector, useCase, options?): Promise<ContentSelectionResponse>

• search by embedding vector (direct vector similarity)

  searches content using a provided embedding vector. useful when you have pre-computed embeddings or want direct control over the search vector. bypasses text/image encoding and searches directly in vector space.

  Parameters

  • vector: number[]

    embedding vector (array of numbers, typically 64-1536 dimensions)
  • useCase: string

    use case identifier
  • Optionaloptions: {
        limit?: number;
        filters?: ContentSelectionFilter;
        with_payload?: boolean;
        with_vectors?: boolean;
        debug?: boolean;
    }

    optional search configuration

    • Optionallimit?: number

      max results to return (1-1000, default: 100)

    • Optionalfilters?: ContentSelectionFilter

      filter conditions to apply

    • Optionalwith_payload?: boolean

      include item metadata in results (default: true)

    • Optionalwith_vectors?: boolean

      include embedding vectors in results (default: false)

    • Optionaldebug?: boolean

      enable debug info in response (default: false)

  Returns Promise<ContentSelectionResponse>

  promise resolving to items with similar embeddings

  Throws

  if vector is empty or useCase is invalid

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  const embedding = [0.1, 0.2, 0.3, ...]; // your pre-computed vector
  const results = await client.searchByVector(embedding, "vector-search", {
    limit: 15
  });
  Copy

getVersion

• getVersion(): Promise<unknown>

• get api version information

  retrieves current api version and build info. useful for debugging, compatibility checking, or displaying version information.

  Returns Promise<unknown>

  promise resolving to version information object

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  const version = await client.getVersion();
  console.log(`API version: ${version}`);
  Copy

catalogAdd

• catalogAdd(props): Promise<unknown>

• add items to catalog

  uploads items to the catalog for a specific entity type (e.g., products, articles). automatically flattens nested objects unless formatData is set to false.

  Parameters

  • props: CatalogAddProps

    catalog add configuration

  Returns Promise<unknown>

  promise resolving when catalog add completes

  Throws

  if entity is empty or data is invalid

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  await client.catalogAdd({
    entity: "products",
    data: [
      { id: "1", name: "Product A", price: 99.99 },
      { id: "2", name: "Product B", price: 149.99 }
    ]
  });
  Copy

catalogCSVAdd

• catalogCSVAdd(props): Promise<{}>

• add items to catalog via csv format

  uploads items to catalog using csv format instead of json. more efficient for large bulk uploads. converts data to csv automatically. does not use makeRequest retry logic (uses raw fetch).

  Parameters

  • props: CatalogAddProps

    catalog add configuration

  Returns Promise<{}>

  promise resolving when catalog upload completes

  Throws

  if data is empty

  Throws

  on fetch failures (no automatic retry for csv uploads)

  Example

  await client.catalogCSVAdd({
    entity: "products",
    data: [{ id: "1", name: "A" }, { id: "2", name: "B" }],
    mainUnit: "id"
  });
  Copy

putEvent

• putEvent(data, options?): Promise<any>

• send single event

  tracks user interactions. supports all event types.

  Parameters

  • data: Event

    event data
  • Optionaloptions: {
        notrace?: boolean;
    }

    optional event configuration

    • Optionalnotrace?: boolean

      skip storing event in analytics (default: false)

  Returns Promise<any>

  promise resolving when event is recorded

  Throws

  if eventType is empty or data is invalid

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  await client.putEvent({
    eventType: "click",
    payload: { item_id: "product-123" },
    sessionId: "session-456"
  });
  Copy

putEventBatch

• putEventBatch(events, options?): Promise<any>

• send batch of events

  efficiently tracks multiple events in a single api call. ideal for bulk event uploads, offline event syncing, or high-throughput event tracking. supports up to 500 events per batch.

  Parameters

  • events: Event[]

    array of events to send (max 500)
  • Optionaloptions: {
        notrace?: boolean;
    }

    optional batch configuration

    • Optionalnotrace?: boolean

      skip storing events in analytics (default: false)

  Returns Promise<any>

  promise resolving when all events are recorded

  Throws

  if events array is empty, exceeds 500 items, or contains invalid events

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  await client.putEventBatch([
    { eventType: "view", payload: { item_id: "item-1" } },
    { eventType: "click", payload: { item_id: "item-2" } },
    { eventType: "purchase", payload: { item_id: "item-3", price: 99.99 } }
  ]);
  Copy

ranking

• ranking(payload): Promise<{
      ordering: {
          [key: string]: number;
      };
      datapoint: DataPoint;
      id: string;
  }>

• get content ranking prediction

  requests ranked ordering of content items based on context and user preferences. used for personalized ranking, A/B testing, or contextual bandit scenarios. returns ordered ranking with scores and associated datapoint.

  Parameters

  • payload: PredictionPayload

    prediction request payload

  Returns Promise<{
      ordering: {
          [key: string]: number;
      };
      datapoint: DataPoint;
      id: string;
  }>

  promise resolving to prediction with ordering, datapoint, and prediction id

  Throws

  if useCase uuid is empty or payload is invalid

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  const ranking = await client.ranking({
    useCase: { uuid: "ranking-use-case" },
    context: { user_id: "user-123" },
    actions: [
      { item_id: "item-1", category: "electronics" },
      { item_id: "item-2", category: "books" }
    ]
  });
  Copy

feedback

• feedback(payload): Promise<unknown>

• send feedback for prediction

  submits outcome feedback for a previous prediction.

  Parameters

  • payload: {
        modelUuid?: string;
        predictionUuid: string;
        value: {
            [k: string]: any;
        };
    }

    feedback payload

    • OptionalmodelUuid?: string

      optional specific model uuid to send feedback to

    • predictionUuid: string

      id of the prediction to provide feedback for (from ranking() response)

    • value: {
          [k: string]: any;
      }

      feedback data (e.g., { reward: 1 }, { clicked: true }, { rating: 4.5 })

      • [k: string]: any

  Returns Promise<unknown>

  promise resolving when feedback is recorded

  Throws

  if predictionUuid is empty or payload is invalid

  Throws

  on 4xx client errors (no retry)

  Throws

  on persistent 5xx/network errors after 3 retries

  Example

  const pred = await client.ranking({...});
  // later, after user interaction
  await client.feedback({
    predictionUuid: pred.id,
    value: { clicked: true, purchased: false }
  });
  Copy