Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Sources

List sources

get

Returns sources available to the caller. Two access modes are supported, depending on whether the type query parameter is provided.

Mode 1 – filtered by type (type provided):

  • Lists all active, non-deleted sources of the specified type, regardless of the caller's role.

  • No additional permission check is performed on the listing itself.

  • Secrets are attached only when the caller is an administrator or a service account whose user_name matches the requested source type (case-insensitive). If the caller does not meet both conditions, sources are returned without secrets.

Mode 2 – no type (type omitted):

  • Lists non-deleted sources.

  • Requires at least one of the following:

    • Administrator or service account, or

    • The 'Manage native implementations' permission.

  • Secrets are not enriched in this mode.

No pagination is applied. The response always includes only the information the caller is allowed to see.

Query parameters
typestringOptional

Filter by source type

Responses
200

Sources

application/json
get/api/sources
GET /api/sources HTTP/1.1
Accept: */*

{
  "data": [
    {
      "active": true,
      "config": {
        "endpoint": "https://example.salesforce.com"
      },
      "external_id": "src-crm",
      "id": 1,
      "type": "salesforce"
    }
  ]
}

Create a source

post

Creates a source from the provided payload, or updates an existing one when a source with the same external_id is already present.

Requires administrative privileges (administrator or service account).

Request body:

  • source (required) – Object containing:

    • external_id (required, string) – Unique external identifier.

    • type (required, string) – Source type. Determines the template used to validate config and to identify secret fields.

    • config (required, object) – Source configuration. The config object is validated against the template for the given type. Fields marked as secret in the template are extracted, stored in the vault, and replaced by a server-generated secrets_key.

    • active (optional, boolean) – Whether the source is active. Default: true.

The endpoint behaves as an upsert. If a source with the given external_id already exists (including a soft-deleted one), it is updated in place and its deleted_at is cleared. Otherwise a new source is created. The response includes a Location header pointing to the resulting source.

The secrets_key is generated by the server and does not need to be supplied by the caller.

Body
Responses
201

Created

application/json
post/api/sources
POST /api/sources HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "source": {
    "config": {
      "endpoint": "https://example.salesforce.com"
    },
    "external_id": "src-crm",
    "type": "salesforce"
  }
}
{
  "data": {
    "active": true,
    "config": {
      "endpoint": "https://example.salesforce.com"
    },
    "dynamic_content": {
      "endpoint": {
        "origin": "user",
        "value": "https://example.salesforce.com"
      }
    },
    "external_id": "src-crm",
    "id": 1,
    "inserted_at": "2026-05-12T10:00:00Z",
    "type": "salesforce",
    "updated_at": "2026-05-12T10:00:00Z"
  }
}

Get a source by external ID

get

Fetches a single source by its external ID, including its supported job types.

Requires administrative privileges (administrator or service account).

Secrets are attached only when the caller is an administrator or service account and the caller's user_name equals the source's type (case-insensitive). If either condition fails, the source is returned without secrets.

Path parameters
external_idstringRequired

Source external ID

Responses
200

Source

application/json
get/api/sources/{external_id}
GET /api/sources/{external_id} HTTP/1.1
Accept: */*

{
  "data": {
    "active": true,
    "config": {
      "endpoint": "https://example.salesforce.com"
    },
    "dynamic_content": {
      "endpoint": {
        "origin": "user",
        "value": "https://example.salesforce.com"
      }
    },
    "external_id": "src-crm",
    "id": 1,
    "inserted_at": "2026-05-12T10:00:00Z",
    "type": "salesforce",
    "updated_at": "2026-05-12T10:00:00Z"
  }
}

Update a source or source configuration

put

Updates either the source properties or its configuration. Use the source key for general updates or the source_config key for configuration updates; only one form should be provided.

Requires administrative privileges (administrator or service account).

Path parameters
external_idstringRequired

Source external ID

Body

Update request that can contain either 'source' (general source update) or 'source_config' (configuration update). Only one of them should be provided.

or
Responses
200

Updated

application/json
put/api/sources/{external_id}
PUT /api/sources/{external_id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 87

{
  "source": {
    "config": {
      "endpoint": "https://example.salesforce.com"
    },
    "type": "salesforce"
  }
}
{
  "data": {
    "active": true,
    "config": {
      "endpoint": "https://example.salesforce.com"
    },
    "dynamic_content": {
      "endpoint": {
        "origin": "user",
        "value": "https://example.salesforce.com"
      }
    },
    "external_id": "src-crm",
    "id": 1,
    "inserted_at": "2026-05-12T10:00:00Z",
    "type": "salesforce",
    "updated_at": "2026-05-12T10:00:00Z"
  }
}

Delete a source

delete

Deletes a source by its external ID. The behavior depends on whether the source has associated jobs.

  • No associated jobs: The source is hard-deleted from the database.

  • Has associated jobs: The source is soft-deleted: deleted_at is set to the current timestamp and the source is excluded from default listings, but the row remains in the database for history. In both cases the source's secrets are removed from the vault.

Requires administrative privileges (administrator or service account).

A soft-deleted source can be reactivated by calling create with the same external_id: the underlying operation clears deleted_at instead of inserting a new row. If the source does not exist, the endpoint returns a client error through the fallback.

Path parameters
external_idstringRequired

Source external ID

Responses
204

Source deleted

No content
delete/api/sources/{external_id}
DELETE /api/sources/{external_id} HTTP/1.1
Accept: */*

No content

Update a source or source configuration

patch

Updates either the source properties or its configuration. Use the source key for general updates or the source_config key for configuration updates; only one form should be provided.

Requires administrative privileges (administrator or service account).

Path parameters
external_idstringRequired

Source external ID

Body

Update request that can contain either 'source' (general source update) or 'source_config' (configuration update). Only one of them should be provided.

or
Responses
200

Updated

application/json
patch/api/sources/{external_id}
PATCH /api/sources/{external_id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 87

{
  "source": {
    "config": {
      "endpoint": "https://example.salesforce.com"
    },
    "type": "salesforce"
  }
}
{
  "data": {
    "active": true,
    "config": {
      "endpoint": "https://example.salesforce.com"
    },
    "dynamic_content": {
      "endpoint": {
        "origin": "user",
        "value": "https://example.salesforce.com"
      }
    },
    "external_id": "src-crm",
    "id": 1,
    "inserted_at": "2026-05-12T10:00:00Z",
    "type": "salesforce",
    "updated_at": "2026-05-12T10:00:00Z"
  }
}

Last updated