# API

Base URL: `https://api.slingdata.io`

## Authentication & Headers

All API requests require authentication using a Sling Project Token in the header:

```
Authorization: Sling-Project-Token xxxxxxxxxxxx
Content-Type: application/json
```

Project tokens can be created and managed through the Sling Data Platform, in the `Settings > API Tokens` section. Each token is associated with a specific project.

## Connections

### List Connections

```
GET /connection/list
```

Returns a list of all connections configured for the project.

**Response**

```json
{
  "connections": [
    {
      "name": "string",
      "type": "string"
    }
  ]
}
```

### Test Connection

```
POST /connection/test
```

Tests if a connection is valid and accessible.

**Request Body**

```json
{
  "name": "string",  // Connection name
}
```

**Response**

```json
{
  "valid": true|false,
  "error": "string"  // Present if valid is false
}
```

## Files

### Get File

```
GET /project/file/get
```

Retrieves contents of a specific project file.

**Query Parameters**

* `name`: File path relative to project root

**Response**

```json
{
  "name": "string",
  "body": "string",
  "is_dir": boolean,
  "updated": "datetime"
}
```

### List Files

```
POST /project/file/list
```

Lists all files in the project.

**Response**

```json
{
  "files": [
    {
      "name": "string",
      "body": "string",
      "is_dir": boolean,
      "updated": "datetime"
    }
  ]
}
```

### Save File

```
POST /project/file/save
```

Creates or updates a project file. If the file is a valid Sling job file (replication, pipeline, monitor, or query), it will be parsed and validated before saving. A default job will be automatically created for new Sling job files.

**Request Body**

```json
{
  "file": {
    "name": "string",  // File path relative to project root
    "body": "string",  // File contents
    "is_dir": false     // Set to true to create a directory (body is ignored)
  }
}
```

**Response**

```json
{
  "file": {
    "name": "string",
    "body": "string",
    "is_dir": false,
    "size": 123,
    "default_job_id": "string",
    "updated": "datetime"
  }
}
```

## Jobs

### List Jobs

```
POST /project/job/list
```

Lists all jobs in the project.

**Request Body**

```json
{
  "name": "string",  // Optional job name
  "file_name": "string",  // Optional file path relative to project root
  "type": "string"  // Optional job type filter (replication, pipeline, monitor)
}
```

**Response**

```json
{
  "jobs": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "status": "string",
      "file_name": "string"
    }
  ]
}
```

### Get Job

```
GET /project/job/get
```

Gets details of a specific job.

**Query Parameters**

* `job_id`: ID of the job

**Response**

```json
{
  "id": "string",
  "name": "string",
  "type": "string",
  "status": "string",
  "file_name": "string",
  "config": {}
}
```

### Save Job

```
POST /project/job/save
```

Creates or updates a job configuration. The job must reference an existing project file.

**Request Body**

```json
{
  "data": {
    "id": "string",         // Optional — omit to create a new job
    "name": "string",       // Job name
    "type": "string",       // Job type: replication, pipeline, monitor, or query
    "file_name": "string",  // File path relative to project root
    "active": false,        // Whether the job schedule is active
    "schedules": [],        // Array of cron expressions
    "timezone": "string",   // Optional timezone for schedules (e.g. "America/New_York")
    "streams": [],          // Optional array of stream names (empty means all)
    "tags": [],             // Optional array of tags
    "group": "string",      // Optional job group for concurrency limiting
    "config": {             // Optional job configuration
      "mode": "string",           // Sync mode (full-refresh, incremental, etc.)
      "threads": 1,               // Number of parallel threads
      "retries": 0,               // Number of retries on failure
      "timeout": 0,               // Timeout in seconds
      "variables": []             // Array of variable maps
    }
  }
}
```

**Response**

```json
{
  "job": {
    "id": "string",
    "name": "string",
    "type": "string",
    "status": "string",
    "file_name": "string",
    "active": false,
    "schedules": [],
    "scheduled": "datetime",
    "config": {}
  }
}
```

### Run Job

```
POST /project/job/run
```

Triggers execution of a job.

**Request Body**

```json
{
  "job_id": "string"
}
```

**Response**

```json
{
  "exec_id": "string"
}
```

## Executions

### Cancel Execution

```
POST /execution/cancel
```

Cancels a running job run / execution.

**Request Body**

```json
{
  "exec_id": "string"
}
```

### List Executions

```
GET /execution/list
```

Returns a list of recent job runs / executions.

**Query Parameters**

* `status` (optional): Filter by execution status: `running` | `success` | `error` | `warning` | `skipped`
* `limit` (optional): Number of records to return (max 100)

**Response**

```json
{
  "executions": [
    {
      "exec_id": "string",
      "status": "string",
      "start_time": "datetime",
      "end_time": "datetime",
      "error": "string",
      ...
    }
  ]
}
```

### Get Execution

```
GET /execution/list
```

Fetches details for a single execution by passing an `exec_id` filter to the list endpoint. The first matching record is the execution.

**Query Parameters**

* `filters` (required): URL-encoded JSON object containing `exec_id`. Example: `filters=%7B%22exec_id%22%3A%22exc_abc123%22%7D` (decodes to `{"exec_id":"exc_abc123"}`)

**Response**

```json
{
  "executions": [
    {
      "exec_id": "string",
      "job_id": "string",
      "status": "string",
      "start_time": "datetime",
      "end_time": "datetime",
      "rows": 0,
      "bytes": 0,
      "error": "string",
      ...
    }
  ]
}
```

If no execution matches the given `exec_id`, the `executions` array will be empty.

**Example**

```bash
curl -G https://api.slingdata.io/execution/list \
  -H "Authorization: Sling-Project-Token $SLING_PROJECT_TOKEN" \
  --data-urlencode 'filters={"exec_id":"exc_abc123"}'
```

### Get Execution Logs (Replication Tasks)

```
POST /execution/replication-tasks
```

Returns per-task records for a replication execution, including the full log output for each stream task. Use this to retrieve logs for a completed or running replication execution.

**Request Body**

```json
{
  "exec_id": "string",        // Required — execution ID to fetch tasks for
  "stream_id": "string",      // Optional — filter to a specific stream name
  "data": {
    "status": "string",       // Optional — filter by task status (running, success, error, etc.)
    "exclude_output": false   // Optional — set to true to omit the heavy log `output` column
  }
}
```

Set `exclude_output` to `false` (or omit it) to include log output in the response. Set it to `true` for lightweight task listings without the log payload.

**Response**

```json
{
  "tasks": [
    {
      "exec_id": "string",
      "stream_id": "string",
      "status": "string",
      "start_time": "datetime",
      "end_time": "datetime",
      "rows": 0,
      "bytes": 0,
      "output": "string",     // Full log output for the task (present when exclude_output is false)
      "error": "string",
      ...
    }
  ]
}
```

**Example**

```bash
curl -X POST https://api.slingdata.io/execution/replication-tasks \
  -H "Authorization: Sling-Project-Token $SLING_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exec_id": "exc_abc123",
    "data": {
      "exclude_output": false
    }
  }'
```

## Git Sync

### Pull from Git

```
POST /project/git/pull
```

Pulls changes from the configured Git repository and syncs them to the project. This is useful for triggering a sync when changes are pushed to the repository (e.g., via a CI/CD webhook) instead of waiting for the automatic polling interval.

**Prerequisites**

* Git integration must be configured and enabled for the project
* The configured branch must exist in the remote repository

**Response**

```json
{
  "result": {
    "pulled": true,
    "created": 2,
    "updated": 1,
    "deleted": 0,
    "sha": "abc123...",
    "created_files": [...],
    "updated_files": [...],
    "deleted_file_names": [...]
  }
}
```

**Response Fields**

* `pulled`: Whether files were pulled from the repository
* `created`: Number of new files created
* `updated`: Number of existing files updated
* `deleted`: Number of files deleted
* `sha`: The commit SHA that was synced
* `created_files`: Array of newly created file objects
* `updated_files`: Array of updated file objects
* `deleted_file_names`: Array of deleted file names

**Example: GitHub Actions Webhook**

You can trigger a git pull when changes are pushed to your repository using GitHub Actions:

```yaml
name: Sync to Sling Platform

on:
  push:
    branches:
      - main  # or your configured branch

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Sling Git Pull
        run: |
          curl -X POST https://api.slingdata.io/project/git/pull \
            -H "Authorization: Sling-Project-Token ${{ secrets.SLING_PROJECT_TOKEN }}" \
            -H "Content-Type: application/json"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/sling-platform/platform/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.