REST API v1

API Reference

Complete reference for every endpoint in the Genius Cloud Solutions API. All requests require a valid API key and return JSON responses.

Overview

Base URL: https://api.geniuscloudsolution.ca/v1
API Version: v1
Content-Type: application/json
Authentication: Bearer token (API key)

The API is versioned. The current stable version is v1. All breaking changes will be introduced under a new version prefix with a minimum 6-month deprecation window.

Authentication

Every request must include your API key as a Bearer token in the Authorization header. Requests without a valid key will receive a 401 Unauthorized response.

Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx

Security tip: Never expose API keys in client-side code or public repositories. Use environment variables and server-side proxies for production integrations.

API Keys

Generate and manage API keys via the Dashboard or the API itself. To create a key manually: Dashboard → Settings → API Keys → Generate New Key. The full key value is shown only once — store it securely.

Available Scopes

read:pipelineswrite:pipelinesread:jobsread:metricsadmin

Property	Type	Description
`name`	`string`	Human-readable label for the key.
`prefix`	`string`	Key prefix — gcs_live_sk_ or gcs_test_sk_.
`scopes`	`string[]`	List of permissions granted to this key.
`created_at`	`ISO 8601`	Timestamp when the key was created.
`last_used`	`ISO 8601`	Timestamp of the most recent authenticated request.
`expires_at`	`ISO 8601 \| null`	Expiry timestamp, or null if the key never expires.

GET/v1/api-keys

Returns a list of all API keys associated with your account. The full key value is not returned — only the prefix and metadata.

Query Parameters

Name	Type	Required	Description
`page`	`integer`	No	Page number, default 1.
`limit`	`integer`	No	Items per page (max 100, default 20).

curl -X GET "https://api.geniuscloudsolution.ca/v1/api-keys" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "id": "key_06o3pc4e7rkl8m9s0t1u2v3x",
      "name": "Production Integration",
      "prefix": "gcs_live_sk_",
      "scopes": ["read:pipelines", "write:pipelines", "read:jobs"],
      "created_at": "2026-01-10T09:00:00Z",
      "last_used": "2026-05-25T19:47:00Z",
      "expires_at": null
    }
  ]
}

POST/v1/api-keys

Create a new API key. The generated key value is returned only in this response — it cannot be retrieved again.

Body Parameters

Name	Type	Required	Description
`name`	`string`	Yes	A descriptive name for the key (e.g. 'CI/CD Key').
`scopes`	`string[]`	Yes	Array of permission scopes to grant.
`expires_in_days`	`integer`	No	Number of days until the key expires. Omit for no expiry.

curl -X POST "https://api.geniuscloudsolution.ca/v1/api-keys" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline Key",
    "scopes": ["read:pipelines", "read:jobs"],
    "expires_in_days": 90
  }'

Example Response

{
  "data": {
    "id": "key_07p4qd5f8slm9n0t1u2v3w4y",
    "name": "CI Pipeline Key",
    "key": "gcs_live_sk_yyyyyyyyyyyyyyyyyyyy",
    "prefix": "gcs_live_sk_",
    "scopes": ["read:pipelines", "read:jobs"],
    "created_at": "2026-05-25T20:15:00Z",
    "expires_at": "2026-08-23T20:15:00Z"
  },
  "note": "The full key value is shown only once. Store it securely."
}

DELETE/v1/api-keys/{id}

Permanently revoke an API key. All in-flight requests using this key will be rejected immediately.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	The ID of the API key to revoke.

curl -X DELETE "https://api.geniuscloudsolution.ca/v1/api-keys/key_06o3pc4e7rkl8m9s0t1u2v3x" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx"

Example Response

// HTTP 204 No Content
// (empty response body)

Pipelines

Manage data, ETL, and automation pipelines. Pipelines can be scheduled, manually triggered, or paused/resumed via the API.

GET/v1/pipelines

Returns a paginated list of all pipelines in your account. Filter by status or type using query parameters.

Query Parameters

Name	Type	Required	Description
`page`	`integer`	No	Page number, default 1.
`limit`	`integer`	No	Items per page (max 100, default 20).
`status`	`string`	No	Filter by status: active \| paused \| error.
`type`	`string`	No	Filter by type: etl \| automation \| saas.

curl -X GET "https://api.geniuscloudsolution.ca/v1/pipelines?page=1&limit=20" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": "pipe_01j8kx9z2mfg3h4n5p6q7r8s",
      "name": "Customer Data ETL",
      "type": "etl",
      "status": "active",
      "schedule": "0 2 * * *",
      "last_run_at": "2026-05-25T02:00:00Z",
      "next_run_at": "2026-05-26T02:00:00Z",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "limit": 20,
    "total_pages": 3
  }
}

GET/v1/pipelines/{id}

Retrieve detailed information about a single pipeline, including source, destination, and scheduling configuration.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	The unique pipeline ID (e.g. pipe_01j8kx9z…).

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

Example Response

{
  "data": {
    "id": "pipe_01j8kx9z2mfg3h4n5p6q7r8s",
    "name": "Customer Data ETL",
    "type": "etl",
    "status": "active",
    "schedule": "0 2 * * *",
    "source": { "type": "postgresql", "host": "db.example.com" },
    "destination": { "type": "snowflake", "warehouse": "analytics" },
    "last_run_at": "2026-05-25T02:00:00Z",
    "next_run_at": "2026-05-26T02:00:00Z",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-05-20T14:22:00Z"
  }
}

Jobs

Jobs represent individual pipeline executions. Query jobs to track status, retrieve logs, or investigate failures.

GET/v1/jobs

List all jobs across all pipelines. Filter by status, pipeline, or date range.

Query Parameters

Name	Type	Required	Description
`page`	`integer`	No	Page number, default 1.
`limit`	`integer`	No	Items per page (max 100, default 20).
`pipeline_id`	`string`	No	Filter jobs by pipeline ID.
`status`	`string`	No	Filter by status: pending \| running \| completed \| failed \| cancelled.
`from_date`	`ISO 8601`	No	Return jobs started after this date.
`to_date`	`ISO 8601`	No	Return jobs started before this date.

curl -X GET "https://api.geniuscloudsolution.ca/v1/jobs?status=completed&limit=20" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": "job_02k9ly0a3ngh4i5o6p7q8r9t",
      "pipeline_id": "pipe_01j8kx9z2mfg3h4n5p6q7r8s",
      "status": "completed",
      "started_at": "2026-05-25T02:00:05Z",
      "completed_at": "2026-05-25T02:04:38Z",
      "duration_ms": 273000,
      "error": null
    }
  ],
  "meta": { "total": 312, "page": 1, "limit": 20, "total_pages": 16 }
}

GET/v1/jobs/{id}

Get full details for a single job, including duration, error message (if failed), and a link to the raw logs.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	The unique job ID (e.g. job_02k9ly0a…).

curl -X GET "https://api.geniuscloudsolution.ca/v1/jobs/job_02k9ly0a3ngh4i5o6p7q8r9t" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "data": {
    "id": "job_02k9ly0a3ngh4i5o6p7q8r9t",
    "pipeline_id": "pipe_01j8kx9z2mfg3h4n5p6q7r8s",
    "status": "completed",
    "started_at": "2026-05-25T02:00:05Z",
    "completed_at": "2026-05-25T02:04:38Z",
    "duration_ms": 273000,
    "error": null,
    "logs_url": "https://api.geniuscloudsolution.ca/v1/jobs/job_02k9ly0a3ngh4i5o6p7q8r9t/logs"
  }
}

ETL Workflows

Manage ETL workflow definitions and their run history. Trigger workflow runs on demand or monitor scheduled executions.

GET/v1/etl/workflows

List all ETL workflow definitions in your account.

Query Parameters

Name	Type	Required	Description
`page`	`integer`	No	Page number, default 1.
`limit`	`integer`	No	Items per page (max 100, default 20).

curl -X GET "https://api.geniuscloudsolution.ca/v1/etl/workflows?page=1&limit=20" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "id": "wf_03l0mz1b4ohi5j6p7q8r9s0u",
      "name": "Salesforce → Snowflake Sync",
      "status": "active",
      "source_type": "salesforce",
      "destination_type": "snowflake",
      "schedule": "0 */6 * * *",
      "last_run_at": "2026-05-25T18:00:00Z"
    }
  ],
  "meta": { "total": 12, "page": 1, "limit": 20, "total_pages": 1 }
}

GET/v1/etl/workflows/{id}/runs

Get a paginated list of all historical runs for a specific ETL workflow.

Path + Query Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Workflow ID.
`page`	`integer`	No	Page number, default 1.
`limit`	`integer`	No	Items per page (max 100, default 20).

curl -X GET "https://api.geniuscloudsolution.ca/v1/etl/workflows/wf_03l0mz1b4ohi5j6p7q8r9s0u/runs" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "run_id": "run_04m1na2c5pij6k7q8r9s0t1v",
      "workflow_id": "wf_03l0mz1b4ohi5j6p7q8r9s0u",
      "status": "completed",
      "rows_processed": 15420,
      "started_at": "2026-05-25T18:00:02Z",
      "completed_at": "2026-05-25T18:03:47Z"
    }
  ],
  "meta": { "total": 58, "page": 1, "limit": 20, "total_pages": 3 }
}

POST/v1/etl/workflows/{id}/trigger

Manually trigger an immediate run of an ETL workflow, bypassing its configured schedule.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Workflow ID to trigger.

curl -X POST "https://api.geniuscloudsolution.ca/v1/etl/workflows/wf_03l0mz1b4ohi5j6p7q8r9s0u/trigger" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Example Response

{
  "data": {
    "run_id": "run_05n2ob3d6qjk7l8r9s0t1u2w",
    "workflow_id": "wf_03l0mz1b4ohi5j6p7q8r9s0u",
    "status": "pending",
    "triggered_by": "api",
    "created_at": "2026-05-25T20:14:33Z"
  }
}

Metrics

Retrieve time-series platform metrics for dashboards, alerting, or analytics.

GET/v1/metrics

Returns time-series data for a specified metric over a date range. Useful for building usage dashboards or custom alerting.

Query Parameters

Name	Type	Required	Description
`metric`	`string`	Yes	Metric name: jobs_completed \| jobs_failed \| pipeline_runs \| data_processed_gb.
`from`	`ISO 8601`	Yes	Start of the time range (inclusive).
`to`	`ISO 8601`	Yes	End of the time range (inclusive).
`interval`	`string`	No	Granularity of data points: hour \| day \| week. Default: day.

curl -X GET "https://api.geniuscloudsolution.ca/v1/metrics?metric=jobs_completed&from=2026-05-01&to=2026-05-25&interval=day" \
  -H "Authorization: Bearer gcs_live_sk_xxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "metric": "jobs_completed",
  "interval": "day",
  "data": [
    { "timestamp": "2026-05-01T00:00:00Z", "value": 142 },
    { "timestamp": "2026-05-02T00:00:00Z", "value": 158 },
    { "timestamp": "2026-05-03T00:00:00Z", "value": 134 }
  ],
  "summary": { "total": 3847, "average": 153.9, "peak": 214 }
}

Webhooks

Configure webhook endpoints to receive real-time push notifications for platform events. Each delivery includes an X-GCS-Signature HMAC-SHA256 header for payload verification.

Supported Events

job.completed — A pipeline job finished successfully.
job.failed — A pipeline job encountered an unrecoverable error.
pipeline.paused — A pipeline was paused by a rule or manually.
etl.run.completed — An ETL workflow run finished.
etl.run.failed — An ETL workflow run failed.

Webhook endpoints are managed in the Dashboard under Settings → Webhooks, or via the Webhooks API (available in v1.3+). Failed deliveries are retried up to 5 times with exponential backoff.

Error Codes

All errors return a consistent JSON structure:

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

Status	Code	Description
400	`BAD_REQUEST`	The request body or query parameters are invalid or missing required fields.
401	`UNAUTHORIZED`	The API key is missing, malformed, or has been revoked.
403	`FORBIDDEN`	Your API key does not have the required scope for this operation.
404	`NOT_FOUND`	The requested resource (pipeline, job, workflow) does not exist.
429	`RATE_LIMITED`	You have exceeded your plan's request rate limit. Retry after X-RateLimit-Reset.
500	`INTERNAL_ERROR`	An unexpected error occurred on our infrastructure. Contact support if it persists.