Create connection

curl --request POST \
  --url https://api.example.com/v1/connections/data \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "type": "<string>",
  "description": "<string>",
  "config": {},
  "secrets": {},
  "snapshot_config": {}
}
'

import requests

url = "https://api.example.com/v1/connections/data"

payload = {
    "name": "<string>",
    "type": "<string>",
    "description": "<string>",
    "config": {},
    "secrets": {},
    "snapshot_config": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    type: '<string>',
    description: '<string>',
    config: {},
    secrets: {},
    snapshot_config: {}
  })
};

fetch('https://api.example.com/v1/connections/data', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/connections/data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'type' => '<string>',
    'description' => '<string>',
    'config' => [
        
    ],
    'secrets' => [
        
    ],
    'snapshot_config' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/connections/data"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"description\": \"<string>\",\n  \"config\": {},\n  \"secrets\": {},\n  \"snapshot_config\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/connections/data")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"description\": \"<string>\",\n  \"config\": {},\n  \"secrets\": {},\n  \"snapshot_config\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/connections/data")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"description\": \"<string>\",\n  \"config\": {},\n  \"secrets\": {},\n  \"snapshot_config\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

Data Connectors

Create connection

Create a data connection to an external source (e.g. Postgres, Snowflake).

Call GET /v1/connections/data/types/{type} first: it lists the exact config and secrets keys this type accepts, which are required, and a ready-to-send example. Validation messages name a field by its UI label (“Database is required”); that listing is what maps the label back to the key to send (pg_db).

config holds non-secret settings; credentials go in secrets and are stored server-side, never returned. A new connection reports status ACTIVE and lastTestStatus empty: status ACTIVE means the record exists, NOT that credentials work. Call the connection test endpoint to verify — it sets lastTestStatus to PASS/FAIL and stamps lastTestedAt. Check lastTestStatus == PASS before relying on a connection, and attach datasets before expecting any data to be analyzable.

For an HTTP/REST connection only, configure durable incremental requests in connector-level snapshot_config.http_replication. Do not place advanced replication settings in config or in a dataset’s snapshot settings. The request schema documents the supported limits, resources, cursors, pagination modes, and a complete example.

POST

connections

data

Create connection

curl --request POST \
  --url https://api.example.com/v1/connections/data \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "type": "<string>",
  "description": "<string>",
  "config": {},
  "secrets": {},
  "snapshot_config": {}
}
'

import requests

url = "https://api.example.com/v1/connections/data"

payload = {
    "name": "<string>",
    "type": "<string>",
    "description": "<string>",
    "config": {},
    "secrets": {},
    "snapshot_config": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    type: '<string>',
    description: '<string>',
    config: {},
    secrets: {},
    snapshot_config: {}
  })
};

fetch('https://api.example.com/v1/connections/data', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/connections/data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'type' => '<string>',
    'description' => '<string>',
    'config' => [
        
    ],
    'secrets' => [
        
    ],
    'snapshot_config' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/connections/data"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"description\": \"<string>\",\n  \"config\": {},\n  \"secrets\": {},\n  \"snapshot_config\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/connections/data")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"description\": \"<string>\",\n  \"config\": {},\n  \"secrets\": {},\n  \"snapshot_config\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/connections/data")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"type\": \"<string>\",\n  \"description\": \"<string>\",\n  \"config\": {},\n  \"secrets\": {},\n  \"snapshot_config\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "code": "<string>",
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

name

string | null

Connection name, shown across Summation.

type

string | null

Source type, e.g. POSTGRES or SNOWFLAKE.

description

string | null

Optional human-readable description.

config

Config · object

Non-secret, type-specific settings. The accepted keys differ per type — GET /v1/connections/data/types/{type} lists them with which are required and a ready-to-send example. Postgres, for instance, takes pg_host, pg_port, pg_db, pg_user and pg_sslmode.

Example:

{
  "pg_db": "analytics",
  "pg_host": "db.example.com",
  "pg_port": "5432",
  "pg_user": "summation"
}

secrets

Secrets · object

Credentials, keyed the same way as config — see GET /v1/connections/data/types/{type} for the secret keys of a given type (Postgres: pg_pass). Stored server-side as secret refs; never returned by any response.

Example:

{ "pg_pass": "<password>" }

snapshot_config

Snapshot Config · object

Connector-level snapshot policy. Only HTTP/REST connections may set snapshot_config.http_replication; never put http_replication in connector config or dataset snapshot settings. The object accepts version=1, validate_server_address (optional; true is the only accepted value — server-address validation cannot be disabled through this API), connector-scoped limits, and resources. Each resource defines request_path; cursor, required for every INCREMENTAL_* sync strategy and optional for FULL_REFRESH, in formats RFC3339, STRING, or INTEGER; optional composite tie-breaker and DESTINATION_MAX or EXPLICIT bootstrap; pagination modes NEXT_LINK and TOKEN using JSON pointers, LINK_HEADER using the RFC 8288 Link response header, or KEYSET and OFFSET using query parameters (KEYSET requires a cursor); initial_query_parameters, which require a cursor; query_parameters containing ${cursor} and, for a composite cursor, ${tie_breaker}. A cursor-less resource rejects both placeholders, and may set constant query_parameters only under TOKEN or OFFSET pagination, where they are sent on every page; NEXT_LINK and LINK_HEADER follow a provider-built continuation URL and so reject query_parameters entirely. Optional source-to-destination field_mappings, tombstone, and execution_order. Data Management validates the complete configuration. Encode integers above 2^53-1 as strings (INTEGER-format cursor values are parsed back losslessly). PATCH semantics: a present snapshot_config replaces the stored policy, with one protection — on HTTP connections, omitting the http_replication key preserves the stored http_replication, so clients that do not round-trip it cannot erase it. Include http_replication to replace it, or set it to null to clear it. Omit the snapshot_config field entirely to leave the whole policy unchanged.

Example:

{
  "enabled": true,
  "http_replication": {
    "limits": {
      "max_concurrency": 2,
      "max_response_bytes_per_request": 100000000,
      "requests_per_day": 40000,
      "requests_per_minute": 60,
      "requests_per_second": 1,
      "response_bytes_per_hour": 4000000000
    },
    "resources": [
      {
        "cursor": {
          "bootstrap_mode": "DESTINATION_MAX",
          "field": "ModificationTimestamp",
          "format": "RFC3339",
          "literal_style": "ODATA",
          "tie_breaker_field": "ListingKey",
          "tie_breaker_format": "STRING"
        },
        "field_mappings": { "@odata.id": "odata_id" },
        "initial_query_parameters": {
          "$filter": "ModificationTimestamp ge 2026-01-01T00:00:00Z"
        },
        "pagination": {
          "data_pointer": "/value",
          "max_pages_per_run": 1000,
          "mode": "NEXT_LINK",
          "next_pointer": "/@odata.nextLink",
          "page_size": 1000,
          "page_size_parameter": "$top"
        },
        "query_parameters": {
          "$filter": "ModificationTimestamp gt ${cursor} or (ModificationTimestamp eq ${cursor} and ListingKey gt ${tie_breaker})"
        },
        "request_path": "/v2/Property"
      }
    ],
    "validate_server_address": true,
    "version": 1
  }
}

Response

Successful Response

⌘I

Get started

Features

API & Integrations

API Reference

Create connection

Authorizations

Body

Response