Connections
Create connection
Creates a new provider connection for the workspace. Connection data is encrypted and stored securely. The response includes connection metadata but never exposes the encrypted credentials.
POST
/
workspaces
/
{workspaceSlug}
/
connections
/
Create connection
curl --request POST \
--url https://api.example.com/workspaces/{workspaceSlug}/connections/ \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"credentials": {
"bucket": "<string>",
"accessKeyId": null,
"endpoint": null,
"region": "us-east-1",
"secretAccessKey": null,
"sessionToken": null
},
"provider": "s3",
"rootPath": "<string>"
},
"displayName": "<string>",
"isActive": true,
"sync": {
"deletionPolicy": "ignore",
"scheduleCron": "<string>",
"syncMode": "import"
}
}
'import requests
url = "https://api.example.com/workspaces/{workspaceSlug}/connections/"
payload = {
"config": {
"credentials": {
"bucket": "<string>",
"accessKeyId": None,
"endpoint": None,
"region": "us-east-1",
"secretAccessKey": None,
"sessionToken": None
},
"provider": "s3",
"rootPath": "<string>"
},
"displayName": "<string>",
"isActive": True,
"sync": {
"deletionPolicy": "ignore",
"scheduleCron": "<string>",
"syncMode": "import"
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
config: {
credentials: {
bucket: '<string>',
accessKeyId: null,
endpoint: null,
region: 'us-east-1',
secretAccessKey: null,
sessionToken: null
},
provider: 's3',
rootPath: '<string>'
},
displayName: '<string>',
isActive: true,
sync: {deletionPolicy: 'ignore', scheduleCron: '<string>', syncMode: 'import'}
})
};
fetch('https://api.example.com/workspaces/{workspaceSlug}/connections/', 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/workspaces/{workspaceSlug}/connections/",
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([
'config' => [
'credentials' => [
'bucket' => '<string>',
'accessKeyId' => null,
'endpoint' => null,
'region' => 'us-east-1',
'secretAccessKey' => null,
'sessionToken' => null
],
'provider' => 's3',
'rootPath' => '<string>'
],
'displayName' => '<string>',
'isActive' => true,
'sync' => [
'deletionPolicy' => 'ignore',
'scheduleCron' => '<string>',
'syncMode' => 'import'
]
]),
CURLOPT_HTTPHEADER => [
"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/workspaces/{workspaceSlug}/connections/"
payload := strings.NewReader("{\n \"config\": {\n \"credentials\": {\n \"bucket\": \"<string>\",\n \"accessKeyId\": null,\n \"endpoint\": null,\n \"region\": \"us-east-1\",\n \"secretAccessKey\": null,\n \"sessionToken\": null\n },\n \"provider\": \"s3\",\n \"rootPath\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"isActive\": true,\n \"sync\": {\n \"deletionPolicy\": \"ignore\",\n \"scheduleCron\": \"<string>\",\n \"syncMode\": \"import\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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/workspaces/{workspaceSlug}/connections/")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"credentials\": {\n \"bucket\": \"<string>\",\n \"accessKeyId\": null,\n \"endpoint\": null,\n \"region\": \"us-east-1\",\n \"secretAccessKey\": null,\n \"sessionToken\": null\n },\n \"provider\": \"s3\",\n \"rootPath\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"isActive\": true,\n \"sync\": {\n \"deletionPolicy\": \"ignore\",\n \"scheduleCron\": \"<string>\",\n \"syncMode\": \"import\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/workspaces/{workspaceSlug}/connections/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"config\": {\n \"credentials\": {\n \"bucket\": \"<string>\",\n \"accessKeyId\": null,\n \"endpoint\": null,\n \"region\": \"us-east-1\",\n \"secretAccessKey\": null,\n \"sessionToken\": null\n },\n \"provider\": \"s3\",\n \"rootPath\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"isActive\": true,\n \"sync\": {\n \"deletionPolicy\": \"ignore\",\n \"scheduleCron\": \"<string>\",\n \"syncMode\": \"import\"\n }\n}"
response = http.request(request)
puts response.read_body{
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": {
"username": "<string>",
"avatarUrl": "<string>",
"displayName": "<string>"
},
"displayName": "<string>",
"id": "<string>",
"isActive": true,
"provider": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"workspaceSlug": "<string>",
"sync": {
"deletionPolicy": "ignore",
"syncMode": "import",
"lastSynced": "2023-11-07T05:31:56Z",
"scheduleCron": "<string>"
}
}{
"message": "<string>",
"name": "<string>",
"resource": "<string>",
"suggestion": "<string>",
"validation": [
{
"code": "<string>",
"field": "<string>",
"message": "<string>",
"params": {}
}
]
}{
"message": "<string>",
"name": "<string>",
"resource": "<string>",
"suggestion": "<string>",
"validation": [
{
"code": "<string>",
"field": "<string>",
"message": "<string>",
"params": {}
}
]
}{
"message": "<string>",
"name": "<string>",
"resource": "<string>",
"suggestion": "<string>",
"validation": [
{
"code": "<string>",
"field": "<string>",
"message": "<string>",
"params": {}
}
]
}"<string>""<string>"Path Parameters
URL-safe workspace identifier.
Body
application/json
Request payload for creating a new workspace connection.
Request payload for creating a new workspace connection.
Typed provider configuration (provider tag + its credentials), encrypted
at rest. The provider tag selects which credential shape is required and
which capability the connection has.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
Show child attributes
Show child attributes
Human-readable connection display name.
Required string length:
1 - 255Whether the connection is enabled. Omit to default to active; set false
to create it disabled.
Sync configuration. Applies only to sync-capable providers (object stores); rejected for others. Omit for manual-only defaults.
Show child attributes
Show child attributes
Response
Response type for a workspace connection.
Note: The encrypted connection data is never exposed in API responses. Only metadata about the connection is returned.
Response type for a workspace connection.
Note: The encrypted connection data is never exposed in API responses. Only metadata about the connection is returned.
When the connection was created.
Account that created this connection.
Show child attributes
Show child attributes
Human-readable connection display name.
Opaque identifier of the connection.
Pattern:
^conn_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$Whether the connection is enabled.
Provider identifier (s3, azure, gcs, openai, ollama, ...).
When the connection was last updated.
Handle of the workspace this connection belongs to.
Required string length:
3 - 32Pattern:
^[a-z0-9]+(?:-[a-z0-9]+)*$Sync configuration; present only for sync-capable connections.
Show child attributes
Show child attributes
Create connection
curl --request POST \
--url https://api.example.com/workspaces/{workspaceSlug}/connections/ \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"credentials": {
"bucket": "<string>",
"accessKeyId": null,
"endpoint": null,
"region": "us-east-1",
"secretAccessKey": null,
"sessionToken": null
},
"provider": "s3",
"rootPath": "<string>"
},
"displayName": "<string>",
"isActive": true,
"sync": {
"deletionPolicy": "ignore",
"scheduleCron": "<string>",
"syncMode": "import"
}
}
'import requests
url = "https://api.example.com/workspaces/{workspaceSlug}/connections/"
payload = {
"config": {
"credentials": {
"bucket": "<string>",
"accessKeyId": None,
"endpoint": None,
"region": "us-east-1",
"secretAccessKey": None,
"sessionToken": None
},
"provider": "s3",
"rootPath": "<string>"
},
"displayName": "<string>",
"isActive": True,
"sync": {
"deletionPolicy": "ignore",
"scheduleCron": "<string>",
"syncMode": "import"
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
config: {
credentials: {
bucket: '<string>',
accessKeyId: null,
endpoint: null,
region: 'us-east-1',
secretAccessKey: null,
sessionToken: null
},
provider: 's3',
rootPath: '<string>'
},
displayName: '<string>',
isActive: true,
sync: {deletionPolicy: 'ignore', scheduleCron: '<string>', syncMode: 'import'}
})
};
fetch('https://api.example.com/workspaces/{workspaceSlug}/connections/', 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/workspaces/{workspaceSlug}/connections/",
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([
'config' => [
'credentials' => [
'bucket' => '<string>',
'accessKeyId' => null,
'endpoint' => null,
'region' => 'us-east-1',
'secretAccessKey' => null,
'sessionToken' => null
],
'provider' => 's3',
'rootPath' => '<string>'
],
'displayName' => '<string>',
'isActive' => true,
'sync' => [
'deletionPolicy' => 'ignore',
'scheduleCron' => '<string>',
'syncMode' => 'import'
]
]),
CURLOPT_HTTPHEADER => [
"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/workspaces/{workspaceSlug}/connections/"
payload := strings.NewReader("{\n \"config\": {\n \"credentials\": {\n \"bucket\": \"<string>\",\n \"accessKeyId\": null,\n \"endpoint\": null,\n \"region\": \"us-east-1\",\n \"secretAccessKey\": null,\n \"sessionToken\": null\n },\n \"provider\": \"s3\",\n \"rootPath\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"isActive\": true,\n \"sync\": {\n \"deletionPolicy\": \"ignore\",\n \"scheduleCron\": \"<string>\",\n \"syncMode\": \"import\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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/workspaces/{workspaceSlug}/connections/")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"credentials\": {\n \"bucket\": \"<string>\",\n \"accessKeyId\": null,\n \"endpoint\": null,\n \"region\": \"us-east-1\",\n \"secretAccessKey\": null,\n \"sessionToken\": null\n },\n \"provider\": \"s3\",\n \"rootPath\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"isActive\": true,\n \"sync\": {\n \"deletionPolicy\": \"ignore\",\n \"scheduleCron\": \"<string>\",\n \"syncMode\": \"import\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/workspaces/{workspaceSlug}/connections/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"config\": {\n \"credentials\": {\n \"bucket\": \"<string>\",\n \"accessKeyId\": null,\n \"endpoint\": null,\n \"region\": \"us-east-1\",\n \"secretAccessKey\": null,\n \"sessionToken\": null\n },\n \"provider\": \"s3\",\n \"rootPath\": \"<string>\"\n },\n \"displayName\": \"<string>\",\n \"isActive\": true,\n \"sync\": {\n \"deletionPolicy\": \"ignore\",\n \"scheduleCron\": \"<string>\",\n \"syncMode\": \"import\"\n }\n}"
response = http.request(request)
puts response.read_body{
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": {
"username": "<string>",
"avatarUrl": "<string>",
"displayName": "<string>"
},
"displayName": "<string>",
"id": "<string>",
"isActive": true,
"provider": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"workspaceSlug": "<string>",
"sync": {
"deletionPolicy": "ignore",
"syncMode": "import",
"lastSynced": "2023-11-07T05:31:56Z",
"scheduleCron": "<string>"
}
}{
"message": "<string>",
"name": "<string>",
"resource": "<string>",
"suggestion": "<string>",
"validation": [
{
"code": "<string>",
"field": "<string>",
"message": "<string>",
"params": {}
}
]
}{
"message": "<string>",
"name": "<string>",
"resource": "<string>",
"suggestion": "<string>",
"validation": [
{
"code": "<string>",
"field": "<string>",
"message": "<string>",
"params": {}
}
]
}{
"message": "<string>",
"name": "<string>",
"resource": "<string>",
"suggestion": "<string>",
"validation": [
{
"code": "<string>",
"field": "<string>",
"message": "<string>",
"params": {}
}
]
}"<string>""<string>"