curl --request POST \
--url https://api.example.com/v0/connectors \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"idempotency_key": "<string>",
"corpus_id": "<string>",
"source_namespace": "<string>",
"kind": "<string>",
"config": {},
"schedule": {
"interval_seconds": 43200
},
"health_policy": {
"silent_after_seconds": 1296000,
"credential_warning_seconds": 15768000
}
}
'import requests
url = "https://api.example.com/v0/connectors"
payload = {
"idempotency_key": "<string>",
"corpus_id": "<string>",
"source_namespace": "<string>",
"kind": "<string>",
"config": {},
"schedule": { "interval_seconds": 43200 },
"health_policy": {
"silent_after_seconds": 1296000,
"credential_warning_seconds": 15768000
}
}
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({
idempotency_key: '<string>',
corpus_id: '<string>',
source_namespace: '<string>',
kind: '<string>',
config: {},
schedule: {interval_seconds: 43200},
health_policy: {silent_after_seconds: 1296000, credential_warning_seconds: 15768000}
})
};
fetch('https://api.example.com/v0/connectors', 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/v0/connectors",
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([
'idempotency_key' => '<string>',
'corpus_id' => '<string>',
'source_namespace' => '<string>',
'kind' => '<string>',
'config' => [
],
'schedule' => [
'interval_seconds' => 43200
],
'health_policy' => [
'silent_after_seconds' => 1296000,
'credential_warning_seconds' => 15768000
]
]),
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/v0/connectors"
payload := strings.NewReader("{\n \"idempotency_key\": \"<string>\",\n \"corpus_id\": \"<string>\",\n \"source_namespace\": \"<string>\",\n \"kind\": \"<string>\",\n \"config\": {},\n \"schedule\": {\n \"interval_seconds\": 43200\n },\n \"health_policy\": {\n \"silent_after_seconds\": 1296000,\n \"credential_warning_seconds\": 15768000\n }\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/v0/connectors")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"idempotency_key\": \"<string>\",\n \"corpus_id\": \"<string>\",\n \"source_namespace\": \"<string>\",\n \"kind\": \"<string>\",\n \"config\": {},\n \"schedule\": {\n \"interval_seconds\": 43200\n },\n \"health_policy\": {\n \"silent_after_seconds\": 1296000,\n \"credential_warning_seconds\": 15768000\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/connectors")
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 \"idempotency_key\": \"<string>\",\n \"corpus_id\": \"<string>\",\n \"source_namespace\": \"<string>\",\n \"kind\": \"<string>\",\n \"config\": {},\n \"schedule\": {\n \"interval_seconds\": 43200\n },\n \"health_policy\": {\n \"silent_after_seconds\": 1296000,\n \"credential_warning_seconds\": 15768000\n }\n}"
response = http.request(request)
puts response.read_body{
"connector_id": "<string>",
"corpus_id": "<string>",
"source_namespace": "<string>",
"kind": "<string>",
"config": {},
"schedule": {
"interval_seconds": 2
},
"health_policy": {
"silent_after_seconds": 2,
"credential_warning_seconds": 1
},
"enabled": true,
"created_at": "2023-11-07T05:31:56Z",
"health": {
"state": "active",
"evaluated_at": "2023-11-07T05:31:56Z",
"last_success_at": "2023-11-07T05:31:56Z",
"last_item_at": "2023-11-07T05:31:56Z",
"last_error": {
"code": "<string>",
"at": "2023-11-07T05:31:56Z"
},
"usage": {
"day": "<string>",
"items_read": 1,
"previous_day_items_read": 1
},
"diagnostics": {},
"push": {
"state": "active",
"error": {
"class": "access",
"code": "<string>",
"at": "2023-11-07T05:31:56Z"
},
"last_delivery_at": "2023-11-07T05:31:56Z",
"poll_interval_seconds": 2
}
},
"disabled_at": "2023-11-07T05:31:56Z",
"credential": {
"version": 2,
"deposited_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z"
},
"webhook_url": "<string>"
}{
"code": "<string>",
"message": "<string>",
"retryable": true,
"field": "<string>",
"resync_url": "<string>"
}Create connector
Create a Connector Instance bound to exactly one authorized Corpus and one Source Namespace. Kind-specific config and credential secret are validated against the kind’s JSON Schema (see listConnectorKinds); a failure is 422 invalid_config or invalid_credential with field pointing at the offending member. Replaying the same idempotency key and request returns the same instance (without re-enabling a disabled one); a different request under the same key is 409 idempotency_conflict. Another enabled instance on the same Corpus and Source Namespace is 409 source_namespace_in_use. The interval defaults per kind and is refused below the deployment floor (30 s by default) with 422 invalid_interval. Deposited credentials are write-only and never returned. A deployment without a credential key refuses any request carrying a credential with 503 credentials_unavailable (retryable false) before storing or digesting it; instances without a credential are unaffected. Commits connector.created in the change feed.
curl --request POST \
--url https://api.example.com/v0/connectors \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"idempotency_key": "<string>",
"corpus_id": "<string>",
"source_namespace": "<string>",
"kind": "<string>",
"config": {},
"schedule": {
"interval_seconds": 43200
},
"health_policy": {
"silent_after_seconds": 1296000,
"credential_warning_seconds": 15768000
}
}
'import requests
url = "https://api.example.com/v0/connectors"
payload = {
"idempotency_key": "<string>",
"corpus_id": "<string>",
"source_namespace": "<string>",
"kind": "<string>",
"config": {},
"schedule": { "interval_seconds": 43200 },
"health_policy": {
"silent_after_seconds": 1296000,
"credential_warning_seconds": 15768000
}
}
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({
idempotency_key: '<string>',
corpus_id: '<string>',
source_namespace: '<string>',
kind: '<string>',
config: {},
schedule: {interval_seconds: 43200},
health_policy: {silent_after_seconds: 1296000, credential_warning_seconds: 15768000}
})
};
fetch('https://api.example.com/v0/connectors', 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/v0/connectors",
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([
'idempotency_key' => '<string>',
'corpus_id' => '<string>',
'source_namespace' => '<string>',
'kind' => '<string>',
'config' => [
],
'schedule' => [
'interval_seconds' => 43200
],
'health_policy' => [
'silent_after_seconds' => 1296000,
'credential_warning_seconds' => 15768000
]
]),
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/v0/connectors"
payload := strings.NewReader("{\n \"idempotency_key\": \"<string>\",\n \"corpus_id\": \"<string>\",\n \"source_namespace\": \"<string>\",\n \"kind\": \"<string>\",\n \"config\": {},\n \"schedule\": {\n \"interval_seconds\": 43200\n },\n \"health_policy\": {\n \"silent_after_seconds\": 1296000,\n \"credential_warning_seconds\": 15768000\n }\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/v0/connectors")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"idempotency_key\": \"<string>\",\n \"corpus_id\": \"<string>\",\n \"source_namespace\": \"<string>\",\n \"kind\": \"<string>\",\n \"config\": {},\n \"schedule\": {\n \"interval_seconds\": 43200\n },\n \"health_policy\": {\n \"silent_after_seconds\": 1296000,\n \"credential_warning_seconds\": 15768000\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/connectors")
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 \"idempotency_key\": \"<string>\",\n \"corpus_id\": \"<string>\",\n \"source_namespace\": \"<string>\",\n \"kind\": \"<string>\",\n \"config\": {},\n \"schedule\": {\n \"interval_seconds\": 43200\n },\n \"health_policy\": {\n \"silent_after_seconds\": 1296000,\n \"credential_warning_seconds\": 15768000\n }\n}"
response = http.request(request)
puts response.read_body{
"connector_id": "<string>",
"corpus_id": "<string>",
"source_namespace": "<string>",
"kind": "<string>",
"config": {},
"schedule": {
"interval_seconds": 2
},
"health_policy": {
"silent_after_seconds": 2,
"credential_warning_seconds": 1
},
"enabled": true,
"created_at": "2023-11-07T05:31:56Z",
"health": {
"state": "active",
"evaluated_at": "2023-11-07T05:31:56Z",
"last_success_at": "2023-11-07T05:31:56Z",
"last_item_at": "2023-11-07T05:31:56Z",
"last_error": {
"code": "<string>",
"at": "2023-11-07T05:31:56Z"
},
"usage": {
"day": "<string>",
"items_read": 1,
"previous_day_items_read": 1
},
"diagnostics": {},
"push": {
"state": "active",
"error": {
"class": "access",
"code": "<string>",
"at": "2023-11-07T05:31:56Z"
},
"last_delivery_at": "2023-11-07T05:31:56Z",
"poll_interval_seconds": 2
}
},
"disabled_at": "2023-11-07T05:31:56Z",
"credential": {
"version": 2,
"deposited_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z"
},
"webhook_url": "<string>"
}{
"code": "<string>",
"message": "<string>",
"retryable": true,
"field": "<string>",
"resync_url": "<string>"
}Authorizations
API key, not necessarily a JWT. Server derives Organization, permitted actions and Corpus scope; every resource access is authorized.
Body
111 - 200Connector kind, provided by the engine or by a pinned connector plugin; listConnectorKinds lists the kinds this deployment accepts. Built-in kinds are fixture (a deterministic test connector available only when the deployment enables it). First-party connector plugins provide rss (RSS 2.0, RSS 1.0, Atom and JSON Feed documents; config url, optional honor_ttl; optional credential username+password or token), x_list (an X list) and m365_mail (Microsoft 365 mailboxes). Another kind is refused with 422 unsupported_connector_kind.
^[a-z][a-z0-9_]{0,31}$Kind-specific configuration validated by the kind's JSON Schema. Holds no secret.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Response
Successful response
111Connector kind, provided by the engine or by a pinned connector plugin; listConnectorKinds lists the kinds this deployment accepts. Built-in kinds are fixture (a deterministic test connector available only when the deployment enables it). First-party connector plugins provide rss (RSS 2.0, RSS 1.0, Atom and JSON Feed documents; config url, optional honor_ttl; optional credential username+password or token), x_list (an X list) and m365_mail (Microsoft 365 mailboxes). Another kind is refused with 422 unsupported_connector_kind.
^[a-z][a-z0-9_]{0,31}$Show child attributes
Show child attributes
Show child attributes
Show child attributes
Last committed Connector Health, evaluated at each acquisition run, credential replacement and disable; evaluated_at shows its age. Precedence disabled, access_error, credential_expiring, silent, active. access_error means the source refused access (distinct from silent, which means no new item within the threshold), including a push channel refused access while polling carries the collection. Other failures appear only as last_error.
Show child attributes
Show child attributes
Metadata of the current Deposited Credential; the secret itself is never returned.
Show child attributes
Show child attributes
Public address of the instance's webhook route, present when its kind declares the push mode and the deployment sets public_url. The kind's plugin registers it with the source.