Skip to main content
POST
List the containers a new knowledge source could read
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/knowledge/synchronized-sources/listContainers lists, by label, the containers in a provider’s system that a new source at the target could read, for example the workspaces of a Freshservice account. Pass one container’s id as externalContainerId to Connect a knowledge source. It is the Console’s add-source container picker. MCP hosts call it through forge_call_operation with operationId listSynchronizedSourceContainers. It needs both knowledge:manage and credentials:use, the pair connecting a source requires: the provider is asked with the credential on its vendor’s connection that resolves along the target scope, never one the request names. A credential missing either answers 403 permission_denied naming it, recorded. The body is the Console picker’s arguments:
  • providerKey: a provider from List source providers whose sourceConfig.container.optionsFrom is listContainers;
  • targetScopeType and, for every type except company, targetScopeEntityId: the scope the new source would write to;
  • config (optional): the provider’s non-secret settings, as createSource takes them.
It is checked as connecting a source is, before the provider is asked:
  • a target outside the caller’s writable namespaces answers the same recorded 403 forbidden that createSource answers;
  • an unregistered provider, or one that does not list its containers, answers 400 bad_request.
The response is { data: [{ id, label }], meta }, sorted by label, paged with limit and cursor. At most 1,000 containers are returned, and meta.partial is true when the listing reached that bound; its last page then answers meta.hasMore: false with meta.truncated: true. A container never carries a URL, key or vendor body. When the provider cannot list, the answer names only its bounded code:
  • 409 conflict with SOURCE_CREDENTIAL_UNAVAILABLE when no approved credential resolves along the target scope (connect one, then retry), or LIST_CONTAINERS_UNSUPPORTED;
  • 500 internal_error with the code (for example LIST_CONTAINERS_FAILED) and the requestId when the provider failed.
The route only reads: it writes nothing and takes no Idempotency-Key.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Path Parameters

providerKey
string
required
Minimum string length: 1

Query Parameters

limit
integer

The list is bounded: at most 1000 items, the provider's distinct containers for one target, refused past it (LIST_CONTAINERS_TOO_MANY). Every answer is the whole list, so meta.hasMore is false. limit (1 to 1000) does not cut it.

Required range: 1 <= x <= 1000
cursor
string

A bounded list issues no cursor: meta.nextCursor is always null, and any cursor is 400.

Minimum string length: 1

Body

application/json

The source a container is wanted for: a registered provider that lists its containers (its sourceConfig.container.optionsFrom is listContainers in synchronized-sources/listProviders), and the scope the source would write to, which must be in the caller's writable namespaces. config holds the provider's non-secret settings, as createSynchronizedSource takes them.

targetScopeType
enum<string>
required
Available options:
company,
department,
team,
factory,
project
targetScopeEntityId
string
Minimum string length: 1
config
object

Response

The containers, by label

data
object[]
required
meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.