Getting Started

Getting started with the SYNQ Developer API

Overview

The SYNQ API enables you to programmatically manage data quality monitors, custom entities, and other platform features. The API is built on gRPC, making it easy to integrate with your existing data infrastructure.

Recommended approach: Use our pre-generated SDKs from buf.build/getsynq/api - no proto compilation required!

Quick Start

1. Get API Credentials

   Generate client credentials from the SYNQ application.

   Select the appropriate scope for your use case (e.g., read-only, write access, admin).

2. Choose Your Integration Method

   Option 1 (Recommended): Use pre-generated SDKs from buf.build

   Option 2: Generate client code from protos

   Option 3: Check out our reference implementations

3. Authenticate

   Fetch an access token using OAuth2 client credentials flow

4. Start Building

   Initialize gRPC clients and call API methods from your code

Reference Implementations

The best way to learn the SYNQ API is to see it in action. We’ve built two production-ready integrations that demonstrate best practices:

Google Cloud Storage

Sync GCS buckets as custom entities

Demonstrates:

• OAuth2 authentication
• Creating custom entity types
• Entity groups for auto-cleanup
• Regional deployment handling

View source →

Google Cloud Pub/Sub

Sync Pub/Sub topics and subscriptions

Demonstrates:

• Managing multiple entity types
• Creating relationships between entities
• Advanced filtering patterns
• Dry-run mode implementation

View source →

Both integrations are:

• Production-ready with pre-built binaries
• Well-documented with configuration examples
• Built using Go with the official buf.build SDKs
• Available as open source

Using Pre-Generated SDKs (Recommended)

The simplest way to use the SYNQ API is through our pre-generated SDKs available on buf.build/getsynq/api/sdks.

Go

# Install the SDK
go get buf.build/gen/go/getsynq/api/protocolbuffers/go
go get buf.build/gen/go/getsynq/api/grpc/go

import (
    synqv1 "buf.build/gen/go/getsynq/api/protocolbuffers/go/getsynq/v1"
    synqv1connect "buf.build/gen/go/getsynq/api/grpc/go/getsynq/v1/synqv1connect"
)

See our Go examples for complete implementations.

Python

# Install the SDK
pip install betterproto
pip install buf-build-getsynq-api

from getsynq.v1 import synq_service

TypeScript

# Install the SDK
npm install @buf/getsynq_api.connectrpc_es

import { SynqService } from "@buf/getsynq_api.connectrpc_es/getsynq/v1/synq_service_pb";

Other Languages

Buf.build supports many languages including Java, Rust, C#, and more.

Visit buf.build/getsynq/api/sdks to see all available options.

Using buf.build SDKs means you don’t need to install protoc, manage proto files, or generate code yourself.

Authentication

All API calls require an access token obtained via OAuth2 client credentials flow.

1. Generate Client Credentials

1. Go to SYNQ Settings → API
2. Create new client credentials
3. Note your CLIENT_ID and CLIENT_SECRET
4. Select the appropriate scope for your use case

Store your credentials securely. Never commit them to version control.

2. Fetch Access Token

EU Region (Default)

curl -X POST https://developer.synq.io/oauth2/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

US Region

curl -X POST https://api.us.synq.io/oauth2/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

3. Use the Access Token

Include the access token in your gRPC metadata:

// Go example
ctx := metadata.AppendToOutgoingContext(
    context.Background(),
    "authorization", "Bearer "+accessToken,
)

Most OAuth2 libraries handle token refresh automatically. See our reference implementations for examples.

API Endpoints

Use the appropriate endpoint for your region:

EU Region (Default)

• gRPC API: developer.synq.io:443
• OAuth2: https://developer.synq.io/oauth2/token
• App: https://app.synq.io

US Region

• gRPC API: api.us.synq.io:443
• OAuth2: https://api.us.synq.io/oauth2/token
• App: https://app.us.synq.io

Complete Example

Here’s a minimal working example in Go:

package main

import (
    "context"
    "log"

    synqv1 "buf.build/gen/go/getsynq/api/protocolbuffers/go/getsynq/v1"
    "golang.org/x/oauth2/clientcredentials"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/credentials/oauth"
)

func main() {
    // Configure OAuth2
    config := clientcredentials.Config{
        ClientID:     "your_client_id",
        ClientSecret: "your_client_secret",
        TokenURL:     "https://developer.synq.io/oauth2/token",
    }

    // Create gRPC connection
    conn, err := grpc.Dial(
        "developer.synq.io:443",
        grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
        grpc.WithPerRPCCredentials(oauth.TokenSource{TokenSource: config.TokenSource(context.Background())}),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    // Use the client
    // ... initialize your service clients and make calls
}

For complete, production-ready examples, see:

• Google Cloud Storage Integration
• Google Cloud Pub/Sub Integration

Advanced: Generating Client Code from Protos

If you prefer to generate client code yourself, you can clone the protos from our GitHub repository.

Manual Code Generation

Prerequisites

• Install protoc
• Install language-specific plugins
• Install protovalidate

Clone the Repository

git clone https://github.com/getsynq/api.git
cd api

Generate Go Code

# Install Go plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Generate code
protoc --proto_path=./protos \
  --go_out=./gen \
  --go-grpc_out=./gen \
  protos/**/*.proto

Generate Python Code

# Install Python tools
pip install grpcio grpcio-tools

# Generate code
python -m grpc_tools.protoc \
  -Iprotos \
  --python_out=./gen \
  --pyi_out=./gen \
  --grpc_python_out=./gen \
  protos/**/*.proto

For other languages, see the gRPC documentation.

Manual code generation requires maintaining your build pipeline and keeping protos up to date. We recommend using buf.build SDKs instead.

Common Use Cases

Custom Entity Management

Create and manage custom entity types to track cloud resources, data pipelines, or any data assets.

See GCS example →

Data Lineage

Create relationships between entities to build cross-platform data lineage.

See Pub/Sub example →

Monitor Management

Programmatically create and manage data quality monitors.

View gRPC API →

Webhooks

Receive real-time notifications about incidents and alerts.

View webhook docs →

Additional Resources

• API Reference: gRPC API Documentation
• Protos: github.com/getsynq/api
• SDKs: buf.build/getsynq/api
• Examples:
  • Go Examples
  • GCS Integration
  • Pub/Sub Integration

Troubleshooting

Slow gRPC connection

If you experience slow connections, especially behind a VPN, try flushing your DNS cache:

# macOS
dscacheutil -flushcache
killall -HUP mDNSResponder

# Linux
sudo systemd-resolve --flush-caches

# Windows
ipconfig /flushdns

Authentication errors

• Verify your client credentials are correct
• Ensure you’re using the correct OAuth2 endpoint for your region (EU or US)
• Check that your credentials have the required scope
• Verify the access token hasn’t expired

Connection refused errors

• Verify you’re using the correct API endpoint for your region
• Check your firewall allows outbound HTTPS/gRPC connections (port 443)
• If behind a corporate proxy, configure your gRPC client accordingly

Proto compilation issues

Consider using pre-generated SDKs from buf.build instead of generating code manually. This avoids:

• Installing and configuring protoc
• Managing proto dependencies
• Keeping generated code in sync with API updates

Need Help?

• Documentation: Browse our full API reference
• Support: Contact us through the support page
• Examples: Check our reference implementations