Connections API

The Connections API manages platform connections for both inbound (sync/pull) and outbound (push/activation) integrations. Connections are the unified abstraction for external platform integrations -- each stores platform-specific configuration and encrypted credentials. Supported platforms include LiveRamp, Trade Desk, Index Exchange, and custom REST APIs.

List Connections

Retrieve all connections for your organization with optional filters.

GET /api/connections

Auth: API key with sync scope, or Clerk session

Query Parameters

Parameter	Type	Description
direction	string	Filter by direction: inbound, outbound, bidirectional
platform	string	Filter by platform: liveramp, tradedesk, indexexchange, custom_api

Response (200)

[
  {
    "id": "conn_01...",
    "name": "LiveRamp Production",
    "platform": "liveramp",
    "direction": "outbound",
    "config": {
      "api_base_url": "https://api.liveramp.com",
      "data_source_location": "US",
      "default_cpm": 2.50,
      "currency": "USD"
    },
    "status": "active",
    "lastTestedAt": "2026-02-25T10:00:00.000Z",
    "createdAt": "2026-02-01T08:00:00.000Z",
    "updatedAt": "2026-02-25T10:00:00.000Z"
  }
]

curl Example

curl "https://app.audiencegpt.com/api/connections?direction=outbound" \
  -H "Authorization: Bearer txadv_your_api_key"

---

Create a Connection

Create a new platform connection. Requires a Clerk session (not API key) because credentials are involved.

POST /api/connections

Auth: Clerk session only (credential management requires interactive session)

Request Body

{
  "name": "LiveRamp Production",
  "platform": "liveramp",
  "direction": "outbound",
  "config": {
    "api_base_url": "https://api.liveramp.com",
    "token_url": "https://serviceaccounts.liveramp.com/authn/v1/oauth2/token",
    "data_source_location": "US",
    "default_cpm": 2.50,
    "currency": "USD"
  },
  "credentials": {
    "client_id": "lr_client_...",
    "client_secret": "lr_secret_..."
  }
}

Field	Type	Required	Description
name	string	Yes	Connection display name
platform	string	Yes	liveramp, tradedesk, indexexchange, custom_api
direction	string	Yes	inbound, outbound, bidirectional
config	object	Yes	Platform-specific configuration (see below)
credentials	object	No	Platform credentials (encrypted at rest via pgcrypto)

Inbound Connection Config

For inbound (sync/pull) connections:

Field	Type	Required	Description
base_url	string	Yes	API base URL for fetching data
items_path	string	No	JSON path to items array in response
count_path	string	No	JSON path to total count
page_param	string	No	Query parameter name for pagination
page_size_param	string	No	Query parameter name for page size
auth_type	string	No	bearer, basic, api_key
field_mappings	object	No	Map external field names to AudienceGPT fields

Outbound Connection Config

For outbound (push/activation) connections:

Field	Type	Required	Description
api_base_url	string	No	Platform API base URL
token_url	string	No	OAuth token endpoint
data_source_location	string	No	Geographic data location (e.g., "US")
default_cpm	number	No	Default CPM pricing
currency	string	No	Currency code (e.g., "USD")
template_key	string	No	Output template key for segment naming

Response (201)

{
  "id": "conn_01...",
  "name": "LiveRamp Production",
  "platform": "liveramp",
  "direction": "outbound",
  "status": "active",
  "createdAt": "2026-02-25T10:00:00.000Z"
}

warning

There is a maximum of 20 connections per organization across all platforms and directions.

---

Get a Connection

GET /api/connections/:id

Auth: API key with sync scope, or Clerk session

Response (200)

Returns the full connection record (credentials are never included in responses).

---

Update a Connection

PATCH /api/connections/:id

Auth: Clerk session only

Request Body

Partial update -- only provided fields are changed.

{
  "name": "LiveRamp Production (Updated)",
  "config": {
    "default_cpm": 3.00
  }
}

Response (200)

Returns the updated connection record.

---

Delete a Connection

DELETE /api/connections/:id

Auth: Clerk session only

Response (200)

{
  "deleted": true
}

---

Test a Connection

Test connectivity to the external platform. For inbound connections, this fetches a single item to verify configuration. For outbound connections, this calls the platform's test endpoint.

POST /api/connections/:id/test

Auth: Clerk session only

Max duration: 30 seconds

Response (200) -- Success

Inbound test:

{
  "success": true,
  "itemCount": 1,
  "sampleItem": {
    "name": "Sample Segment",
    "id": "ext_123"
  }
}

Outbound test:

{
  "success": true,
  "message": "Connected to LiveRamp API"
}

Response (200) -- Failure

{
  "success": false,
  "error": "Connection timed out after 30 seconds"
}

info

Test failures return 200 status with success: false rather than an HTTP error status. This allows the client to display the error message to the user.

---

Sync Routes (Inbound Pull)

These routes implement client-orchestrated, page-by-page syncing from inbound connections.

Create a Sync Run

POST /api/connections/:id/sync/run

Creates a new sync run and fetches the total item count from the external API.

Auth: API key with sync scope, or Clerk session

Response (200)

{
  "runId": "run_01...",
  "totalItems": 500,
  "status": "running"
}

Process a Sync Page

POST /api/connections/:id/sync/run/:runId/page

Fetches one page of items from the external API, classifies them, deduplicates, and inserts into the database.

Auth: API key with sync scope, or Clerk session

Check Sync Status

GET /api/connections/:id/sync/run/:runId/status

Returns sync run progress and status.

Auth: API key with sync scope, or Clerk session

Response (200)

{
  "runId": "run_01...",
  "status": "running",
  "processedPages": 5,
  "totalPages": 10,
  "successCount": 450,
  "errorCount": 5,
  "duplicateCount": 45
}

---

Push Routes (Outbound Activation)

These routes implement client-orchestrated segment pushing to outbound platform connections.

Create a Push Run

POST /api/connections/:id/push/run

Creates a new push run with pending activation records for the selected segments.

Auth: API key with activations scope, or Clerk session

Push a Batch

POST /api/connections/:id/push/run/:runId/push

Pushes a batch of segments to the platform (batch size: 25).

Auth: API key with activations scope, or Clerk session

Check Push Status

GET /api/connections/:id/push/run/:runId/status

Returns push run progress and status.

Auth: API key with activations scope, or Clerk session

---

TypeScript Example

// Create and test a new connection
async function setupConnection() {
  // Create the connection
  const createRes = await fetch("https://app.audiencegpt.com/api/connections", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      // Clerk session cookie is sent automatically in browser context
    },
    body: JSON.stringify({
      name: "My Custom API",
      platform: "custom_api",
      direction: "inbound",
      config: {
        base_url: "https://api.example.com/segments",
        items_path: "data.segments",
        count_path: "data.total",
        auth_type: "bearer",
      },
      credentials: {
        api_key: "ext_api_key_...",
      },
    }),
  });
  const connection = await createRes.json();

  // Test the connection
  const testRes = await fetch(
    `https://app.audiencegpt.com/api/connections/${connection.id}/test`,
    { method: "POST" }
  );
  const testResult = await testRes.json();

  if (!testResult.success) {
    throw new Error(`Connection test failed: ${testResult.error}`);
  }

  return connection;
}

Next Steps

• Activations API -- Manage activated segments
• Topics API -- View synced topics in your library
• Import API -- Alternative bulk import via CSV
• Rate Limits -- Connection and sync limits