Create a custom connection

llm prompts Create one connection per customer Audit for cross-tenant leaks

For customer data that isn't on their website and lives in your product (dashboards, help docs, CRM notes), push it in through the Custom Connections API with that customer's token. For data that lives in a system the customer already uses, such as their mailbox, Drive or Notion, connect it as a source instead of copying it through your backend.

You'll almost always want exactly one custom connection per customer: create it once right after provisioning and store the returned connection id as CONN_ID alongside the token. Then upsert documents into it whenever your source data changes.

Request fields

namestring

Required. What the connection is called in Context Link, up to 255 characters.

Response fields

connectionobject

The custom connection that was created.

connection.idinteger

The connection id to store as CONN_ID and use in every later upsert.

connection.namestring

The name you gave the connection.

connection.scopestring

Always personal for an API account, so its content stays private to that customer.

connection.created_by_user_idinteger

The id of the account whose token created the connection.

connection.post_countinteger

Documents currently in the connection, so 0 on creation.

connection.last_synced_attimestamp

When content was last pushed, null until the first upsert.

connection.created_attimestamp

When the connection was created.

Content pushed as a customer is only ever visible to that customer. Personal scope is enforced server-side for API accounts; there is no scope parameter to get wrong.

Shared content across all customers

Organisation-level content is fleet-visible. Anything indexed at organisation level is blended into every customer's results, and every customer's answers can cite it. That is the point (shared help docs, a product glossary, an FAQ), but it also means one customer's data must never be indexed there. If in doubt, push through the customer's token: content pushed as an API account can never leak sideways.

To make something retrievable by every customer, push it as yourself, not as an API account: the partner admin's own custom-connections token (from Settings) creates organisation-level connections. Tenant content in through the customer's token; fleet-wide content through yours.

The same asymmetry applies to namespaces: an API account's note lands in that account's private memory, never the organisation's.

curl -X POST "https://context-link.ai/api/v1/custom_connections" \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme app data" }'

require "net/http"
require "json"

uri = URI("https://context-link.ai/api/v1/custom_connections")

payload = { "name" => "Acme app data" }

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("ACME_TOKEN")}"
request["Content-Type"] = "application/json"
request.body = JSON.generate(payload)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

import os
import requests

url = "https://context-link.ai/api/v1/custom_connections"

payload = { "name": "Acme app data" }

headers = {
    "Authorization": f"Bearer {os.environ['ACME_TOKEN']}",
    "Content-Type": "application/json",
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
print(response.text)

// Runs on your server only: the token must never reach the browser.
const url = new URL("https://context-link.ai/api/v1/custom_connections");

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ACME_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Acme app data" }),
});

console.log(await response.text());

// Runs on your server only: the token must never reach the browser.
async function main() {
  const url = new URL("https://context-link.ai/api/v1/custom_connections");

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.ACME_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Acme app data" }),
  });

  console.log(await response.text());
}

main();

Response

{
  "connection": {
    "id": 5501,
    "name": "Acme app data",
    "scope": "personal",
    "created_by_user_id": 4211,
    "post_count": 0,
    "last_synced_at": null,
    "created_at": "2026-08-31T10:16:04Z"
  }
}

← Back to Docs Raw markdown guide for AI