Getting Started with Synqly

Learn the basics of integrating Synqly into your application

By Synqly Team•Updated December 2025

Synqly is a unified API gateway that makes it easy to integrate AI into your product without locking you into a single provider. Instead of learning (and maintaining) different SDKs, auth methods, error shapes, and model names, you make one clean request format through Synqly. In this guide you’ll: • Install the SDK in your language • Configure API-key auth safely • Make your first request • Understand the response/usage metadata • Learn common gotchas (rate limits, invalid keys, environment variables) By the end, you should be able to send a request in under 5 minutes and have a solid foundation for production integration.

Prerequisites

Before you begin, ensure you have: • A Synqly account (sign up at synqly.com) • Node.js 16+ or Python 3.8+ installed • Basic knowledge of REST APIs • Your preferred AI provider credentials (OpenAI, Anthropic, etc.)

Installation

Install the Synqly SDK for your preferred language. We recommend pinning versions in production so upgrades are deliberate and testable:

# Using npm
npm install @synqly/sdk

# Using yarn
yarn add @synqly/sdk

# Using pnpm
pnpm add @synqly/sdk

Authentication Setup

Synqly uses API keys for authentication. You can find your API key in the dashboard under Settings > API Keys. Recommended setup: 1) Add the key to environment variables 2) Load env vars in your runtime (Next.js, Node, Python, etc.) 3) Initialize the client once and reuse it (don’t re-create per request)

Pro Tip

Store your API key in environment variables, never commit it to version control. Use `.env.local` locally and a secret manager (Vercel, AWS, GCP, Vault) in production.

import { Synqly } from '@synqly/sdk';

// Initialize the client
const synqly = new Synqly({
  apiKey: process.env.SYNQLY_API_KEY,
  // Optional: Set default provider
  defaultProvider: 'openai',
  // Optional: Enable request logging
  debug: process.env.NODE_ENV === 'development'
});

// Verify connection
const health = await synqly.health();
console.log('Connected:', health.status);
console.log('Available providers:', health.providers);

Making Your First Request

Let’s make a simple chat completion request. Synqly normalizes requests across providers and returns a consistent shape, so you can swap providers without rewriting your integration. Tips: • Keep prompts short while testing • Log usage details (tokens/cost where available) • Start with a single model/provider, then expand

// Basic chat completion
const response = await synqly.chat.completions.create({
  model: 'gpt-4',
  provider: 'openai', // optional, auto-selected if omitted
  messages: [
    {
      role: 'user',
      content: 'Hello! How does Synqly work?'
    }
  ],
  temperature: 0.7,
  max_tokens: 150
});

console.log(response.choices[0].message.content);

// Access metadata
console.log('Provider used:', response.provider);
console.log('Model used:', response.model);
console.log('Tokens used:', response.usage);

Basic Error Handling

Production integrations should wrap API calls in try/catch and classify failures. Most errors fall into these buckets: • 401/403: invalid or missing API key • 429: rate limiting (retry with backoff) • 400: validation issues (wrong model/provider/request shape) • 5xx: provider or gateway problems (retry + fallback) Start simple: log the error, show a friendly message to users, and add retries for transient errors.

try {
  const response = await synqly.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
  });
  console.log(response.choices[0].message.content);
} catch (error: any) {
  if (error.status === 429) {
    console.error('Rate limit exceeded');
    console.error('Retry after:', error.headers?.['retry-after']);
  } else if (error.status === 401) {
    console.error('Authentication failed - check your API key');
  } else if (error.status === 400) {
    console.error('Invalid request:', error.message);
  } else if (error.status >= 500) {
    console.error('Server error - please retry');
  } else {
    console.error('Request failed:', error.message);
  }
}

Production Checklist

Before shipping: • Rotate API keys and remove old keys • Add timeouts and retries (with backoff + jitter) • Track usage per user/workspace • Add provider fallback for critical paths • Sanitize logs (never log secrets or raw user PII) • Set spending limits and alerts

Next Steps

Now that you've made your first request, explore these topics: • Learn about streaming responses for real-time output • Implement proper error handling and retries • Explore multi-provider fallback strategies • Set up monitoring and analytics • Review security best practices

Back to Guides Next Guide