Getting Started

Introduction

How Voyager Works

Voyager is a server that maintains authenticated LinkedIn sessions and proxies API calls through LinkedIn’s internal Voyager API. Your agents talk to Voyager via REST; Voyager talks to LinkedIn via their internal APIs.

Your Agent --> Voyager REST API --> LinkedIn Voyager API --> LinkedIn Data

Architecture

  • Multi-tenant: Each LinkedIn account is an isolated tenant with its own browser context, cookies, and rate limits
  • API-first: 33 of 37 automation workflows use direct API calls (no DOM/page navigation)
  • Self-healing: Each operation tries multiple API strategies, falling back gracefully if LinkedIn deprecates an endpoint
  • SalesNav: Full SalesNav API support — search leads, get profiles, send InMail, track alerts

Key Concepts

Sessions

A session is an authenticated LinkedIn connection. You provide cookies from your LinkedIn browser session; Voyager maintains them in a headless browser that makes API calls on your behalf. Sessions are validated on sync and monitored by background polling.

Tenants

Each organization is a tenant. A tenant can have multiple LinkedIn accounts (users). Tenants are isolated — separate browser contexts, rate limiters, and data directories. One Voyager instance can manage dozens of tenants with hundreds of users.

Users

Within a tenant, each LinkedIn account is a user identified by a userId string (e.g., "charis", "harry"). The X-User-Id header routes requests to the correct LinkedIn session.

API Keys

Tenant-scoped API keys (voy_ prefix) authenticate requests. Each key is bound to a specific tenant. Users within a tenant are identified by the X-User-Id header. Keys can be created and revoked via the API or admin dashboard.

Async Jobs

Some operations (company scraping, employee export, batch reads) take longer than a typical request timeout. These return a 202 Accepted response with a jobId. Poll GET /api/jobs/:jobId until the job completes. See Async Jobs for details.

Webhooks

Instead of polling for new messages or connection requests, configure webhooks to receive real-time events. Voyager signs payloads with HMAC-SHA256 and auto-formats messages for Slack. See Webhooks for setup.

API Design Principles

Consistent Response Format

Every endpoint returns JSON with a top-level success boolean:

1{
2  "success": true,
3  "profile": { ... }
4}

Errors include a human-readable error field:

1{
2  "success": false,
3  "error": "Profile not found"
4}

Rate Limiting as Metering

Voyager does not enforce rate limits. It records and reports usage — messages sent, connections requested, profiles viewed, account age. Your orchestrating agent has the full context (campaign strategy, account trust score, test vs. production) to decide policy. See Rate Limiting.

Multi-Strategy Fallbacks

LinkedIn deprecates internal APIs without notice. Voyager tries multiple strategies for each operation:

  1. REST API (fastest, most reliable)
  2. GraphQL API (fallback)
  3. DOM automation (last resort, only for operations with no API)

If strategy 1 fails, Voyager automatically tries strategy 2, then 3. Your agent code never changes.