Genius Cloud Solutions API Docs

Introduction

The Genius Cloud Solutions API gives you programmatic access to every layer of your cloud operations — data pipelines, scheduled jobs, ETL workflows, and automation rules. Whether you are building internal tooling, integrating with third-party systems, or orchestrating complex multi-step processes, our REST API is the single interface to get it done.

All API responses are returned as JSON. The API is versioned; breaking changes will always be released under a new version prefix.

Authentication

The API uses API key authentication. Include your key in every request as an Authorization header using the Bearer scheme:

Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx

API keys come in two flavours:

• gcs_live_sk_* — Production keys. All writes are permanent and billable.
• gcs_test_sk_* — Sandbox keys. Safe for development; data is isolated.

You can generate and revoke API keys in the Dashboard → Settings → API Keys.

Quick Start

Make your first API call in seconds. The GET /v1/status endpoint requires no parameters and confirms your key is valid:

curl -X GET "https://api.geniuscloudsolution.ca/v1/status" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

A successful response returns 200 OK with a JSON body confirming the API version and current system status.

Rate Limits

Rate limits are enforced per API key. When you exceed your plan's limit, the API returns a 429 Too Many Requests response.

Every response includes the following headers so you can track your usage:

• X-RateLimit-Limit — Your plan's maximum requests per minute.
• X-RateLimit-Remaining — Requests remaining in the current window.
• X-RateLimit-Reset — Unix timestamp when the window resets.

Pipelines

A Pipeline is a named, repeatable sequence of steps that move, transform, or act on data. Pipelines are the central building block of the platform and come in three varieties:

• Data Pipelines

  Ingest data from source systems, apply transformations, and deliver it to target destinations — databases, data warehouses, or object storage.

• ETL Pipelines

  Extract, Transform, and Load workflows optimised for structured and semi-structured data. Supports CDC, full-load, and incremental strategies.

• Automation Pipelines

  Trigger business logic in response to events, schedules, or webhook signals. Compose multi-step workflows with branching and retry semantics.

Pipelines can be scheduled using cron expressions, triggered via API, or started by webhook events. Each run creates a Job that tracks execution state and logs.

Jobs & Tasks

When a Pipeline runs, the platform creates a Job to represent that execution. A Job progresses through the following states:

Each Job is composed of one or more Tasks — atomic units of work that execute in sequence or in parallel depending on your pipeline configuration. Task-level logs, durations, and error traces are available via the Jobs API.

ETL Workflows

ETL Workflows provide a declarative interface for defining Extract, Transform, and Load processes. Configure sources (databases, APIs, files), apply transformations (mapping, filtering, enrichment), and deliver clean data to your target systems — all without writing infrastructure code.

Workflows support both scheduled batch runs and real-time streaming ingestion. Built-in connectors cover popular databases (PostgreSQL, MySQL, Snowflake, BigQuery) and SaaS platforms (Salesforce, HubSpot, Stripe).

Automation Rules

Automation Rules let you define event-driven logic: “when X happens, do Y.” Rules listen for platform events (job completion, data thresholds, API signals) and trigger actions such as notifications, downstream pipeline runs, or external webhook calls.

Rules are composed of a trigger, optional conditions, and one or more actions. They can be activated and deactivated via the API without redeploying.

Making Requests

The Genius Cloud Solutions API follows REST principles. All requests are made over HTTPS to:

Every request must include the following headers:

• Authorization: Bearer YOUR_API_KEY
• Content-Type: application/json
• Accept: application/json

Pagination

List endpoints use cursor-based pagination. Pass page and limit as query parameters:

• page — Page number, starting at 1.
• limit — Items per page. Default: 20, max: 100.

Every paginated response includes a meta object:

{
  "meta": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "total_pages": 8
  }
}

Error Handling

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "docs_url": "https://geniuscloudsolution.ca/docs#authentication"
  }
}

HTTP status codes used:

Webhooks

Webhooks allow the platform to push real-time notifications to your server when key events occur — no polling required. Supported events include:

• job.completed — A pipeline job finished successfully.
• job.failed — A pipeline job encountered an error.
• pipeline.paused — A pipeline was paused (manually or by an alert rule).
• etl.run.completed — An ETL workflow run finished.

Configure webhook endpoints in the Dashboard or via the Webhooks API endpoint. Each delivery includes an X-GCS-Signature header for payload verification.

Python SDK

The official Python SDK wraps the REST API with a typed, Pythonic interface. Requires Python 3.8+.

pip install genius-cloud-sdk

from genius_cloud import GeniusCloudClient

client = GeniusCloudClient(api_key="gcs_live_sk_xxxxxxxxxxxxxxxxxxxx")

# List all active pipelines
pipelines = client.pipelines.list(status="active")
for p in pipelines.data:
    print(p.name, p.status)

# Trigger a pipeline run
job = client.pipelines.trigger("pipe_01j8kx9z2mfg3h4n5p6q7r8s")
print(f"Job started: {job.id}")

Node.js SDK

The official Node.js SDK supports both CommonJS and ESM. Requires Node.js 18+.

npm install @genius-cloud/sdk

import { GeniusCloudClient } from "@genius-cloud/sdk";

const client = new GeniusCloudClient({
  apiKey: "gcs_live_sk_xxxxxxxxxxxxxxxxxxxx",
});

// List all pipelines
const { data: pipelines } = await client.pipelines.list({ status: "active" });
console.log(pipelines);

// Trigger a pipeline run
const job = await client.pipelines.trigger("pipe_01j8kx9z2mfg3h4n5p6q7r8s");
console.log(`Job started: ${job.id}`);

Changelog