Integrations API

Base URL: https://api.sparbz.cloud/api/v1

Overview

The Integrations API allows you to connect Sparbz Cloud with third-party services and platforms. Configure integrations with GitHub, Cloudflare, Datadog, PagerDuty, Slack, and other services for enhanced automation and monitoring.

All endpoints require authentication via Bearer token or API key.

---

Integration Management

GET /integrations

List all integrations in your organization.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Description
type	string	Filter by type: github, cloudflare, datadog, pagerduty, slack
status	string	Filter by status: connected, disconnected, error, expired
limit	integer	Number of results (default: 20, max: 100)
offset	integer	Pagination offset

Response (200 OK):

[
  {
    "id": "uuid",
    "name": "github-main",
    "type": "github",
    "status": "connected",
    "configuration": {
      "organization": "company",
      "repositories": ["repo1", "repo2"]
    },
    "last_sync": "2024-11-29T15:45:00Z",
    "created_at": "2024-10-15T10:30:00Z"
  }
]

---

POST /integrations

Create a new integration.

Request Body:

{
  "name": "string",
  "type": "github | cloudflare | datadog | pagerduty | slack",
  "credentials": {},
  "configuration": {}
}

Response (201 Created):

{
  "id": "uuid",
  "name": "github-main",
  "type": "github",
  "status": "pending",
  "configuration": {},
  "created_at": "2024-11-29T10:30:00Z"
}

---

GET /integrations/:id

Get details of a specific integration.

Response (200 OK):

{
  "id": "uuid",
  "name": "github-main",
  "type": "github",
  "status": "connected",
  "configuration": {
    "organization": "company",
    "repositories": ["repo1", "repo2"],
    "webhook_id": "12345",
    "webhook_events": ["push", "pull_request"]
  },
  "credentials_valid": true,
  "last_sync": "2024-11-29T15:45:00Z",
  "last_error": null,
  "error_count": 0,
  "created_at": "2024-10-15T10:30:00Z",
  "updated_at": "2024-11-29T15:45:00Z"
}

---

PATCH /integrations/:id

Update integration settings.

Request Body:

{
  "name": "string",
  "configuration": {},
  "enabled": boolean
}

Response (200 OK):

{
  "id": "uuid",
  "name": "github-main-updated",
  "updated_at": "2024-11-29T15:45:00Z"
}

---

DELETE /integrations/:id

Delete an integration.

Response (204 No Content)

---

Integration Testing

POST /integrations/:id/test

Test the connectivity and validity of an integration.

Response (202 Accepted):

{
  "test_id": "test-xxx",
  "integration_id": "integration-xxx",
  "status": "in-progress",
  "started_at": "2024-11-29T15:45:00Z"
}

---

GET /integrations/:id/test/:test_id

Get the result of an integration test.

Response (200 OK):

{
  "test_id": "test-xxx",
  "integration_id": "integration-xxx",
  "status": "passed | failed",
  "result": {
    "connection": "success",
    "authentication": "valid",
    "permissions": "sufficient",
    "latency_ms": 125
  },
  "errors": [],
  "started_at": "2024-11-29T15:45:00Z",
  "completed_at": "2024-11-29T15:45:05Z"
}

---

GitHub Integration

POST /integrations/github

Create a GitHub integration.

Request Body:

{
  "name": "string",
  "installation_id": "string",
  "repositories": ["owner/repo1", "owner/repo2"],
  "events": ["push", "pull_request", "release"]
}

Response (201 Created):

{
  "id": "uuid",
  "name": "github-main",
  "type": "github",
  "status": "connected",
  "webhook_url": "https://api.sparbz.cloud/webhooks/github/uuid",
  "webhook_secret": "whsec_xxx",
  "created_at": "2024-11-29T10:30:00Z"
}

---

POST /integrations/:id/github/sync

Sync repository data from GitHub.

Request Body:

{
  "repositories": ["owner/repo1", "owner/repo2"],
  "full_sync": false
}

Response (202 Accepted):

{
  "sync_id": "sync-xxx",
  "status": "in-progress"
}

---

Cloudflare Integration

POST /integrations/cloudflare

Create a Cloudflare integration.

Request Body:

{
  "name": "string",
  "api_token": "string",
  "zones": ["zone-id-1", "zone-id-2"]
}

Response (201 Created):

{
  "id": "uuid",
  "name": "cloudflare-main",
  "type": "cloudflare",
  "status": "connected",
  "zones": ["zone-id-1", "zone-id-2"],
  "created_at": "2024-11-29T10:30:00Z"
}

---

Datadog Integration

POST /integrations/datadog

Create a Datadog integration.

Request Body:

{
  "name": "string",
  "api_key": "string",
  "app_key": "string",
  "site": "datadoghq.com | datadoghq.eu",
  "tags": ["environment:production", "team:platform"]
}

Response (201 Created):

{
  "id": "uuid",
  "name": "datadog-prod",
  "type": "datadog",
  "status": "connected",
  "tags": ["environment:production", "team:platform"],
  "created_at": "2024-11-29T10:30:00Z"
}

---

Slack Integration

POST /integrations/slack

Create a Slack integration.

Request Body:

{
  "name": "string",
  "webhook_url": "string",
  "channels": {
    "deployments": "#deployments",
    "alerts": "#alerts",
    "logs": "#logs"
  }
}

Response (201 Created):

{
  "id": "uuid",
  "name": "slack-notifications",
  "type": "slack",
  "status": "connected",
  "channels": {
    "deployments": "#deployments",
    "alerts": "#alerts"
  },
  "created_at": "2024-11-29T10:30:00Z"
}

---

PagerDuty Integration

POST /integrations/pagerduty

Create a PagerDuty integration.

Request Body:

{
  "name": "string",
  "integration_key": "string",
  "service_id": "string"
}

Response (201 Created):

{
  "id": "uuid",
  "name": "pagerduty-alerts",
  "type": "pagerduty",
  "status": "connected",
  "service_id": "service-xxx",
  "created_at": "2024-11-29T10:30:00Z"
}

---

Event Forwarding

GET /integrations/:id/events

Get recent events sent to an integration.

Query Parameters:

Parameter	Type	Description
event_type	string	Filter by event type
status	string	Filter by status: success, failed, pending
limit	integer	Number of results (default: 50, max: 200)

Response (200 OK):

[
  {
    "id": "event-xxx",
    "event_type": "deployment.completed",
    "status": "success",
    "payload": {...},
    "sent_at": "2024-11-29T15:45:00Z",
    "response_status": 200
  }
]

---

Integration Health

GET /integrations/:id/health

Get the health status of an integration.

Response (200 OK):

{
  "integration_id": "uuid",
  "status": "healthy | degraded | unhealthy",
  "last_sync": "2024-11-29T15:45:00Z",
  "sync_status": "success | failed | in-progress",
  "error_count": 0,
  "recent_errors": [],
  "uptime_percent": 99.9,
  "average_response_time_ms": 125,
  "event_queue_size": 0
}

---

Webhook Management

GET /integrations/:id/webhooks

List webhooks for an integration.

Response (200 OK):

[
  {
    "id": "webhook-xxx",
    "url": "https://api.sparbz.cloud/webhooks/github/uuid",
    "events": ["push", "pull_request"],
    "enabled": true,
    "created_at": "2024-11-29T10:30:00Z"
  }
]

---

POST /integrations/:id/webhooks/delivery-attempts

Get webhook delivery attempts.

Query Parameters:

Parameter	Type	Description
status	string	Filter by status: success, failed
limit	integer	Number of results (default: 50)

Response (200 OK):

[
  {
    "id": "attempt-xxx",
    "webhook_id": "webhook-xxx",
    "event": "push",
    "status": "success",
    "status_code": 200,
    "duration_ms": 125,
    "timestamp": "2024-11-29T15:45:00Z"
  }
]

---

Error Responses

Code	Description
400	Bad Request - Invalid configuration or credentials
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Integration doesn't exist
409	Conflict - Integration already exists
422	Unprocessable Entity - Invalid integration type or configuration
500	Internal Server Error

---

Common Use Cases

Setting Up GitHub CI/CD Integration

POST /integrations/github
{
  "name": "github-deployments",
  "installation_id": "12345",
  "repositories": ["company/api", "company/web"],
  "events": ["push", "pull_request", "release"]
}

Sending Alerts to Slack

POST /integrations/slack
{
  "name": "slack-alerts",
  "webhook_url": "https://hooks.slack.com/services/...",
  "channels": {
    "alerts": "#production-alerts",
    "deployments": "#deployments"
  }
}

Monitoring with Datadog

POST /integrations/datadog
{
  "name": "datadog-prod",
  "api_key": "dd-api-key",
  "app_key": "dd-app-key",
  "site": "datadoghq.com",
  "tags": ["environment:production", "team:platform"]
}

Testing Integration Connectivity

POST /integrations/{integration_id}/test