Class KnowledgeSourceResource

constructor

• new KnowledgeSourceResource(http: HttpClient): KnowledgeSourceResource

  Parameters

  • http: HttpClient

  Returns KnowledgeSourceResource

Readonlykinds

create

• create(
      input: {
          agent?: string;
          metadata?: Record<string, unknown>;
          org?: string;
          parent_source?: string;
          payload?: Record<string, unknown>;
          state?: string;
          team?: string;
          thread?: string;
          type: string;
          user?: string;
      },
  ): Promise<KnowledgeSource>

  Create a knowledge source Creates a new knowledge source of the requested type and returns the created object. Only types listed by GET /api/v1/knowledge_sources/kinds may be created through this endpoint. Other source types — such as webhook/inbound, connectors/*/emails, and thread/messages — are provisioned automatically by server-driven flows (webhook auto-provisioning, installation activation, connector lifecycle events) and cannot be created directly via the API. Exactly one of team, user, agent, or org must identify the owner of the new source. Omit org when an individual owner (team, user, or agent) is supplied; include org alone for org-level system-owned sources.

  Parameters

  • input: {
        agent?: string;
        metadata?: Record<string, unknown>;
        org?: string;
        parent_source?: string;
        payload?: Record<string, unknown>;
        state?: string;
        team?: string;
        thread?: string;
        type: string;
        user?: string;
    }

    Request body.

    • Optionalagent?: string

      Agent ID (agt_...) that owns this source. Mutually exclusive with team and user.

    • Optionalmetadata?: Record<string, unknown>

      Arbitrary key-value metadata to attach to the source. Returned as-is on reads.

    • Optionalorg?: string

      Organization ID (org_...). Required for system-owned sources that have no individual owner (team, user, or agent).

    • Optionalparent_source?: string

      Parent knowledge source ID (ksrc_...). Use to create a child source.

    • Optionalpayload?: Record<string, unknown>

      Type-specific configuration for the source. Shape depends on type.

    • Optionalstate?: string

      Initial state of the source. One of "active" (default) or "paused". Paused sources do not trigger ingestion automatically.

    • Optionalteam?: string

      Team ID (team_...) that owns this source. Mutually exclusive with user and agent.

    • Optionalthread?: string

      Thread ID (thr_...) to associate this source with, if applicable.

    • type: string

      Knowledge source type. Must be one of the values returned by GET /api/v1/knowledge_sources/kinds.

    • Optionaluser?: string

      User ID (usr_...) that owns this source. Mutually exclusive with team and agent.

  Returns Promise<KnowledgeSource>

  The newly created knowledge source.

delete

• delete(source: string): Promise<void>

  Delete a knowledge source Permanently deletes the knowledge source identified by source. This action is irreversible — all documents, embeddings, and ingestion history associated with the source are removed. The authenticated caller must own the source or have sufficient permissions within its parent organization. Returns 204 No Content on success.

  Parameters

  • source: string

    Knowledge source ID (ksrc_...) to delete.

  Returns Promise<void>

  Empty response. The source has been permanently deleted.

get

• get(source: string): Promise<KnowledgeSource>

  Retrieve a knowledge source Returns the knowledge source identified by source. The authenticated caller must have access to the source's parent organization or be the individual owner of the source. Use the list endpoint to retrieve many sources at once or to discover sources by type or owner.

  Parameters

  • source: string

    Knowledge source ID (ksrc_...) to retrieve.

  Returns Promise<KnowledgeSource>

  The requested knowledge source.

ingest

• ingest(
      source: string,
      input: {
          content?: {
              content_type?: string;
              data: string;
              data_encoding?: string;
              filename?: string;
          };
          dedupe?: boolean;
          file?: string;
          metadata?: Record<string, unknown>;
          pull?: boolean;
          title?: string;
      },
  ): Promise<ContextIngestion>

  Trigger ingestion on a knowledge source Starts an ingestion run on the specified knowledge source and returns the ingestion object. Exactly one of two modes must be chosen per request: Push mode (file or content) — available for knowledge/documents sources only. Supply the document bytes either as a reference to an already-uploaded file (file) or as an inline blob (content). The runner stores the bytes and indexes the resulting document. title and metadata are persisted on the document in push mode. Pull mode (pull: true) — re-triggers ingestion using the source's own configured data. Use this to re-scrape a scrape/site, re-fetch a web/link, or re-process a file/document. Not valid for knowledge/documents (which has no upstream — push new bytes instead) or for source kinds populated by server-driven flows. title and metadata are ignored in pull mode. If an ingestion is already active for the source, the existing ingestion is returned rather than creating a duplicate.

  Parameters

  • source: string

    Knowledge source ID (ksrc_...) to ingest.

  • input: {
        content?: {
            content_type?: string;
            data: string;
            data_encoding?: string;
            filename?: string;
        };
        dedupe?: boolean;
        file?: string;
        metadata?: Record<string, unknown>;
        pull?: boolean;
        title?: string;
    }

    Request body.

    • Optionalcontent?: {
          content_type?: string;
          data: string;
          data_encoding?: string;
          filename?: string;
      }

      Inline document bytes to push to the source. Mutually exclusive with file and pull.

    • Optionaldedupe?: boolean

      When true, reuse the source's existing document if the pushed content is byte-identical to it, instead of creating a duplicate. The reused document keeps its chunks and embeddings, and title/metadata from this request are still applied to it. Content that differs in any way always creates a new document. Defaults to false, which creates a new document on every push. Push mode only — not valid with pull: true. Check metadata.document_reused on the returned ingestion to see whether a document was actually reused.

    • Optionalfile?: string

      ID of an already-uploaded file (fil_...). The runner reads filename and content type from the stored file. Upload the file via POST /v1/files first. Mutually exclusive with content and pull.

    • Optionalmetadata?: Record<string, unknown>

      Arbitrary key-value metadata to attach to the ingested document. Applied in push mode only; ignored when pull: true.

    • Optionalpull?: boolean

      When true, re-triggers ingestion using the source's own configured data. Re-scrapes a scrape/site, re-fetches a web/link, or re-processes a file/document. Mutually exclusive with file and content. Not valid for knowledge/documents sources.

    • Optionaltitle?: string

      Display title for the ingested document. Applied in push mode only; ignored when pull: true.

  Returns Promise<ContextIngestion>

  The created ingestion, or an existing active ingestion if one is already running.

list

• list(
      params?: {
          agent?: string;
          installation?: string;
          org?: string;
          ownerScope?: "system" | "any" | "individual";
          page?: number;
          pageSize?: number;
          search?: string;
          team?: string[];
          thread?: string[];
          type?: string;
      },
  ): Promise<
      {
          data: {
              agent?: string;
              context_installation?: string;
              created_at?: string;
              id: string;
              metadata?: Record<string, unknown>;
              org?: string;
              parent_source?: string;
              payload?: Record<string, unknown>;
              sandbox?: string;
              state: string;
              team?: string;
              thread?: string;
              type: string;
              updated_at?: string;
              user?: string;
          }[];
          has_next: boolean;
          has_prev: boolean;
          page: number;
          page_size: number;
          total_entries: number;
          total_pages: number;
      },
  >

  List knowledge sources Returns a paginated list of knowledge sources visible to the authenticated caller. Results are ordered by creation time descending. Use the type, installation, agent, org, and owner_scope filters to narrow the result set. Combine owner_scope: "system" with org to list org-level sources that have no individual owner. Combine owner_scope: "individual" with agent to list sources owned by a specific agent. Pagination is page-number based. The default page size is 25.

  Parameters

  • Optionalparams: {
        agent?: string;
        installation?: string;
        org?: string;
        ownerScope?: "system" | "any" | "individual";
        page?: number;
        pageSize?: number;
        search?: string;
        team?: string[];
        thread?: string[];
        type?: string;
    }

    Query parameters.

    • Optionalagent?: string

      Agent ID (agt_...). Returns only sources owned by or associated with this agent.

    • Optionalinstallation?: string

      Installation ID (ins_...). Returns only sources associated with this installation.

    • Optionalorg?: string

      Organization ID (org_...). Returns only sources belonging to this organization. Combine with owner_scope: "system" to retrieve org-level system sources.

    • OptionalownerScope?: "system" | "any" | "individual"

      Filter by ownership scope. One of "any" (default — returns all visible sources), "individual" (only sources owned by a user, team, or agent), or "system" (only sources with no individual owner, typically org-level).

    • Optionalpage?: number

      Page number to retrieve. Defaults to 1.

    • OptionalpageSize?: number

      Number of knowledge sources to return per page. Defaults to 25.

    • Optionalsearch?: string

      Filter sources whose type contains this string. Case-insensitive substring match.

    • Optionalteam?: string[]

      Exact team IDs whose sources to include.

    • Optionalthread?: string[]

      Exact backing thread IDs whose sources to include.

    • Optionaltype?: string

      Exact knowledge source type to filter by, e.g. "knowledge/documents".

  Returns Promise<
      {
          data: {
              agent?: string;
              context_installation?: string;
              created_at?: string;
              id: string;
              metadata?: Record<string, unknown>;
              org?: string;
              parent_source?: string;
              payload?: Record<string, unknown>;
              sandbox?: string;
              state: string;
              team?: string;
              thread?: string;
              type: string;
              updated_at?: string;
              user?: string;
          }[];
          has_next: boolean;
          has_prev: boolean;
          page: number;
          page_size: number;
          total_entries: number;
          total_pages: number;
      },
  >

  Successful response

search

• search(
      source: string,
      input: {
          max_results?: number;
          min_similarity?: number;
          mode?: string;
          query: string;
          recency_days?: number;
      },
  ): Promise<
      {
          data: {
              content?: string;
              content_type?: string;
              created_at?: string;
              id: string;
              kind: "chunk";
              metadata?: Record<string, unknown>;
              raw_content?: Record<string, unknown>;
              type?: string;
          }[];
      },
  >

  Search within a knowledge source Executes a search query against the indexed documents in a single knowledge source and returns matching results ranked by relevance. Three search modes are supported: "hybrid" (default) combines vector similarity and full-text scoring, "vector" uses embedding-based semantic search only, and "fulltext" uses keyword-based search only. Use "hybrid" for most use cases; prefer "vector" when semantic meaning matters more than exact terms. Optionally restrict results to documents ingested within the last N days using recency_days. Results are ordered by relevance score descending.

  Parameters

  • source: string

    Knowledge source ID (ksrc_...) to search within.

  • input: {
        max_results?: number;
        min_similarity?: number;
        mode?: string;
        query: string;
        recency_days?: number;
    }

    Request body.

    • Optionalmax_results?: number

      Maximum number of results to return. The platform applies its own upper bound; omit to use the default.

    • Optionalmin_similarity?: number

      Cosine-similarity floor for the vector leg, 0.0-1.0. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass 0.0 to disable the floor when a missed match costs more than a weak one — note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default.

    • Optionalmode?: string

      Search algorithm to use. One of "hybrid" (default, combines vector and full-text), "vector" (semantic similarity only), or "fulltext" (keyword matching only).

    • query: string

      Natural language or keyword query string to search for.

    • Optionalrecency_days?: number

      When set, limits results to documents ingested within the last N days. Omit to search across all documents regardless of age.

  Returns Promise<
      {
          data: {
              content?: string;
              content_type?: string;
              created_at?: string;
              id: string;
              kind: "chunk";
              metadata?: Record<string, unknown>;
              raw_content?: Record<string, unknown>;
              type?: string;
          }[];
      },
  >

  Successful response

update

• update(
      source: string,
      input: {
          metadata?: Record<string, unknown>;
          payload?: Record<string, unknown>;
          state?: string;
      },
  ): Promise<KnowledgeSource>

  Update a knowledge source Updates the mutable fields of an existing knowledge source and returns the updated object. Only fields provided in the request body are changed; omitted fields retain their current values. You can update the type-specific payload, the metadata map, and the state. To pause a source and prevent automatic ingestion, set state to "paused". To resume, set it back to "active".

  Parameters

  • source: string

    Knowledge source ID (ksrc_...) to update.

  • input: {
        metadata?: Record<string, unknown>;
        payload?: Record<string, unknown>;
        state?: string;
    }

    Request body.

    • Optionalmetadata?: Record<string, unknown>

      Arbitrary key-value metadata to attach to the source. Replaces the entire existing metadata map when provided.

    • Optionalpayload?: Record<string, unknown>

      Type-specific configuration to replace on the source. Shape depends on the source type. Replaces the entire existing payload when provided.

    • Optionalstate?: string

      Desired state of the source. One of "active" or "paused". Paused sources do not trigger ingestion automatically.

  Returns Promise<KnowledgeSource>

  The updated knowledge source.