Services API

The Services API provides methods to discover and connect to services exposed through your Private Connect infrastructure. Get connection strings, ports, and service metadata programmatically.

Overview

Access the Services API through the services property:

import { PrivateConnect } from '@privateconnect/sdk';

const pc = new PrivateConnect({ apiKey: 'your-api-key' });
const services = await pc.services.list();

Or use the convenience method:

const db = await pc.connect('postgres-prod');
console.log(db.connectionString);

Methods

list()

List all services in the workspace.

list(): Promise<Service[]>

Service[]

Array of all services

Show Service properties

string

Unique service identifier

name

string

Service name

targetHost

string

Target hostname or IP address

targetPort

number

Target port number

tunnelPort

number | undefined

Local tunnel port (if active)

protocol

string

Service protocol (e.g., ‘postgres’, ‘mysql’, ‘http’)

status

string

Service status

agentLabel

string | undefined

Label of the agent exposing this service

Example

const services = await pc.services.list();

services.forEach(service => {
  console.log(`${service.name}:`);
  console.log(`  Protocol: ${service.protocol}`);
  console.log(`  Target: ${service.targetHost}:${service.targetPort}`);
  console.log(`  Agent: ${service.agentLabel || 'unknown'}`);
  console.log(`  Status: ${service.status}`);
});

get()

Get a specific service by name.

get(name: string): Promise<Service | null>

name

string

required

Service name (case-insensitive)

Service | null

Service object if found, null otherwise

Example

const service = await pc.services.get('postgres-prod');

if (service) {
  console.log(`Found service: ${service.name}`);
  console.log(`Protocol: ${service.protocol}`);
  console.log(`Port: ${service.tunnelPort || service.targetPort}`);
} else {
  console.log('Service not found');
}

getConnection()

Get connection details for a service.

getConnection(serviceName: string): Promise<Connection>

serviceName

string

required

Service name to connect to

Connection

Connection details for the service

Show Connection properties

service

string

Service name

host

string

Connection host (typically ‘localhost’)

port

number

Connection port

connectionString

string

Protocol-specific connection string

envVar

string

Suggested environment variable name

Connection String Formats

The SDK automatically generates connection strings based on the service protocol:

PostgreSQL (port 5432): postgres://localhost:5432/postgres
MySQL (port 3306): mysql://localhost:3306
Redis (port 6379): redis://localhost:6379
MongoDB (port 27017): mongodb://localhost:27017
HTTP/HTTPS: http://localhost:PORT
Other: tcp://localhost:PORT

Example

PostgreSQL
MySQL
Redis
HTTP API

const db = await pc.services.getConnection('postgres-prod');

console.log(db.connectionString);
// postgres://localhost:5432/postgres

console.log(db.envVar);
// DATABASE_URL

// Use with pg client
import { Client } from 'pg';
const client = new Client({ connectionString: db.connectionString });
await client.connect();

const db = await pc.services.getConnection('mysql-prod');

console.log(db.connectionString);
// mysql://localhost:3306

// Use with mysql2
import mysql from 'mysql2/promise';
const connection = await mysql.createConnection(db.connectionString);

const cache = await pc.services.getConnection('redis-prod');

console.log(cache.connectionString);
// redis://localhost:6379

// Use with ioredis
import Redis from 'ioredis';
const redis = new Redis(cache.connectionString);

const api = await pc.services.getConnection('internal-api');

console.log(api.connectionString);
// http://localhost:8080

// Use with fetch
const response = await fetch(`${api.connectionString}/health`);
const data = await response.json();

Convenience Methods

connect()

The main PrivateConnect class provides a convenience method for quick connections:

connect(serviceName: string): Promise<Connection>

This is equivalent to pc.services.getConnection(serviceName).

Example

import { PrivateConnect } from '@privateconnect/sdk';

const pc = new PrivateConnect({ apiKey: 'your-api-key' });

// Quick connection
const db = await pc.connect('postgres-prod');
console.log(db.connectionString);

Standalone connect()

For even simpler usage, import the standalone function:

import { connect } from '@privateconnect/sdk';

// Uses PRIVATECONNECT_API_KEY from environment
const db = await connect('postgres-prod');

// Or provide config
const cache = await connect('redis-prod', { 
  apiKey: 'your-api-key' 
});

Complete Examples

Database Connection

import { PrivateConnect } from '@privateconnect/sdk';
import { Client } from 'pg';

const pc = new PrivateConnect({ 
  apiKey: process.env.PRIVATECONNECT_API_KEY! 
});

// Get connection details
const db = await pc.connect('postgres-prod');

// Connect to database
const client = new Client({ 
  connectionString: db.connectionString 
});

await client.connect();

// Run query
const result = await client.query('SELECT NOW()');
console.log('Database time:', result.rows[0].now);

await client.end();

Multi-Service Application

import { PrivateConnect } from '@privateconnect/sdk';
import { Client as PgClient } from 'pg';
import Redis from 'ioredis';

const pc = new PrivateConnect({ 
  apiKey: process.env.PRIVATECONNECT_API_KEY! 
});

// Connect to multiple services
const [database, cache] = await Promise.all([
  pc.connect('postgres-prod'),
  pc.connect('redis-prod'),
]);

// Initialize clients
const pg = new PgClient({ connectionString: database.connectionString });
const redis = new Redis(cache.connectionString);

await Promise.all([
  pg.connect(),
  redis.ping(),
]);

console.log('Connected to database and cache');

// Use in application
const userId = '12345';

// Check cache
let user = await redis.get(`user:${userId}`);

if (!user) {
  // Query database
  const result = await pg.query(
    'SELECT * FROM users WHERE id = $1',
    [userId]
  );
  
  user = result.rows[0];
  
  // Store in cache
  await redis.setex(`user:${userId}`, 3600, JSON.stringify(user));
}

console.log('User:', user);

// Cleanup
await pg.end();
await redis.quit();

Dynamic Service Discovery

import { PrivateConnect } from '@privateconnect/sdk';

const pc = new PrivateConnect({ 
  apiKey: process.env.PRIVATECONNECT_API_KEY! 
});

// List all available services
const services = await pc.services.list();

console.log('Available services:');
services.forEach(service => {
  console.log(`  ${service.name} (${service.protocol})`);
});

// Find databases
const databases = services.filter(s => 
  ['postgres', 'mysql', 'mongodb'].includes(s.protocol)
);

console.log(`\nFound ${databases.length} databases:`);

for (const db of databases) {
  const connection = await pc.services.getConnection(db.name);
  console.log(`  ${db.name}: ${connection.connectionString}`);
}

Error Handling

import { PrivateConnect } from '@privateconnect/sdk';

const pc = new PrivateConnect({ 
  apiKey: process.env.PRIVATECONNECT_API_KEY! 
});

try {
  const db = await pc.connect('nonexistent-service');
  console.log(db.connectionString);
} catch (error) {
  if (error instanceof Error) {
    console.error('Connection failed:', error.message);
    // Service "nonexistent-service" not found
  }
}

// Check before connecting
const service = await pc.services.get('maybe-exists');

if (service) {
  const connection = await pc.services.getConnection(service.name);
  console.log('Connected:', connection.connectionString);
} else {
  console.log('Service not available');
}

Environment Variables

The SDK suggests environment variable names based on the service protocol:

const db = await pc.connect('postgres-prod');
console.log(db.envVar); // DATABASE_URL

const cache = await pc.connect('redis-prod');
console.log(cache.envVar); // REDIS_URL

const api = await pc.connect('internal-api');
console.log(api.envVar); // API_URL

const custom = await pc.connect('my-service');
console.log(custom.envVar); // MY_SERVICE_URL

Use these in your application:

// Set environment variables
const db = await pc.connect('postgres-prod');
process.env[db.envVar] = db.connectionString;

// Now your app can use DATABASE_URL
console.log(process.env.DATABASE_URL);

Overview

REST API

SDK

Overview

Methods

list()

Example

get()

Example

getConnection()

Connection String Formats

Example

Convenience Methods

connect()

Example

Standalone connect()

Complete Examples

Database Connection

Multi-Service Application

Dynamic Service Discovery

Error Handling

Environment Variables

Next Steps

Agents API

Sessions API

Build docs developers (and LLMs) love

Overview

REST API

SDK

​Overview

​Methods

​list()

​Example

​get()

​Example

​getConnection()

​Connection String Formats

​Example

​Convenience Methods

​connect()

​Example

​Standalone connect()

​Complete Examples

​Database Connection

​Multi-Service Application

​Dynamic Service Discovery

​Error Handling

​Environment Variables

​Next Steps

Agents API

Sessions API

Build docs developers (and LLMs) love

Overview

Methods

list()

Example

get()

Example

getConnection()

Connection String Formats

Example

Convenience Methods

connect()

Example

Standalone connect()

Complete Examples

Database Connection

Multi-Service Application

Dynamic Service Discovery

Error Handling

Environment Variables

Next Steps