Terminal / CLI SDK

Installation

npm install @gravity-ai/api

Set GRAVITY_API_KEY in your server environment.

How the pieces fit together

Initialize the pixel

gravityPixel() handles session and visitor tracking automatically. Initialize it once when your app starts.

Prepare context

gravityContext() captures device signals and session info. Pass the pixel’s visitor and session IDs to link tracking with ad requests.

Fetch ads

gravity.getAds(req, messages, placements) reads the context, adds the client IP, and returns matched ads. Runs in parallel with your LLM call.

Initialize the pixel

import { gravityPixel } from '@gravity-ai/api';

const pixel = gravityPixel({ pixelId: 'YOUR_PIXEL_ID' });
await pixel.start();

Find YOUR_PIXEL_ID in your dashboard under Settings → Platform Settings. The pixel automatically manages sessions, visitor IDs, and attribution — same as the browser pixel (gr-pix.js), but using local file storage instead of cookies. Session state is persisted and cleaned up automatically on process exit.

Parameter	Type	Default	Description
`pixelId`	`string`	—	Required. Your Gravity pixel ID.
`appName`	`string`	`'terminal'`	Application label, used as page title in events.
`eventEndpoint`	`string`	`'https://api.trygravity.ai/track/gr-events'`	Event endpoint URL.
`sessionEndpoint`	`string`	`'https://api.trygravity.ai/track/gr-session'`	Session endpoint URL.
`sessionTimeoutMinutes`	`number`	`30`	Session idle timeout in minutes.
`attrMaxAgeDays`	`number`	`180`	Max age for persisted attribution in days.
`sessionMaxPages`	`number`	`50`	Max entries in invocation history.
`hashIdentityFields`	`boolean`	`true`	Hash identity fields with SHA-256 before sending.
`storageDir`	`string`	`'~/.gravity'`	Custom storage directory for session and attribution data.

Prepare context

import { gravityContext } from '@gravity-ai/api';

const gravity_context = gravityContext({
  sessionId: pixel.getSessionId()!,
  user: {
    userId: currentUser.id,
    gruid: pixel.getVisitorId(),
    grclid: pixel.getClickId(),
    graid: pixel.getGraid(),
  },
});

gravityContext() auto-detects terminal device signals (OS, timezone, locale). Required parameters:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes	From `pixel.getSessionId()`
`user.userId`	`string`	Yes	Stable per-user identifier

Fetch ads

import { Gravity } from '@gravity-ai/api';

const gravity = new Gravity({ production: true });

const { ads } = await gravity.getAds(
  { body: { gravity_context }, headers: {} },
  messages,
  [{ placement: 'inline_response', placement_id: 'main' }],
);

gravity.getAds() never throws. On any failure, it returns { ads: [] } silently. Safe to fire-and-forget.

Full example

import { gravityPixel, gravityContext, Gravity } from '@gravity-ai/api';

// 1. Initialize pixel
const pixel = gravityPixel({ pixelId: 'YOUR_PIXEL_ID' });
await pixel.start();

// 2. Set up ad client
const gravity = new Gravity({ production: true });

// 3. On each user interaction
async function handleQuery(userId: string, messages: any[]) {
  const ctx = gravityContext({
    sessionId: pixel.getSessionId()!,
    user: {
      userId,
      gruid: pixel.getVisitorId(),
      grclid: pixel.getClickId(),
    },
  });

  const { ads } = await gravity.getAds(
    { body: { gravity_context: ctx }, headers: {} },
    messages,
    [{ placement: 'inline_response', placement_id: 'main' }],
  );

  return ads;
}

FAQ

Do I need a separate package?

No. gravityPixel ships inside @gravity-ai/api. Just npm install @gravity-ai/api and import it.

Does this work in Bun and Deno?

Yes. It uses standard APIs and falls back gracefully when Node-specific modules aren’t available.

Does the ad request block my LLM response?

No. Fire gravity.getAds() in parallel with your LLM call. It never throws, so failures are silent.

Where does the API key go?

Set GRAVITY_API_KEY as an environment variable. The Gravity class reads it automatically. You can also pass it via new Gravity({ apiKey: '...' }).

​Installation

​How the pieces fit together

​Initialize the pixel

​Prepare context

​Fetch ads

​Full example

​FAQ

Installation

How the pieces fit together

Initialize the pixel

Prepare context

Fetch ads

Full example

FAQ