---
title: "Create a new datasource"
method: POST
path: "/v2/knowledge/{knowledge_id}/datasources"
tags: ["Knowledge Bases"]
---

# Create a new datasource

`POST /v2/knowledge/{knowledge_id}/datasources`

Creates a datasource shell when only a display name is provided. When file_id is provided, the uploaded file is queued for chunking and ingestion.

## Path parameters

- `knowledge_id` string, required

## Request body

- DatasourcesServiceCreateRequest
  - `display_name` string
  - `description` string, nullable — The description of the knowledge base
  - `file_id` string
  - `chunking_options` DatasourceChunkingOptions
    - `chunking_configuration` union — The chunking configuration settings for the datasource. Defaults to the system's standard chunking configuration if not specified.
      - object — Optimized chunking strategy focusing on speed and avoiding duplication of content chunks.
        - `type` 'default', required
      - object — Provides advanced settings for customizing chunking behavior, enabling fine-grained control to better meet specific data processing needs.
        - `type` 'advanced', required
        - `chunk_max_characters` number — Defines the absolute maximum character length per chunk. Text elements exceeding this size will be automatically split into multiple chunks.
        - `chunk_overlap` number — Specifies the number of characters to overlap between consecutive chunks. This overlap helps maintain semantic continuity when splitting large text elements.
    - `chunking_cleanup_options` ChunkingCleanupOptions
      - `delete_emails` boolean
      - `delete_credit_cards` boolean
      - `delete_phone_numbers` boolean
      - `clean_bullet_points` boolean
      - `clean_numbered_list` boolean
      - `clean_unicode` boolean
      - `clean_dashes` boolean
      - `clean_whitespaces` boolean
  - `id` string — Compatibility fields used by the former datasource shell/legacy route.
  - `attachment` DatasourceAttachment
    - `id` string
    - `object_name` string
  - `metadata` CountMetadata
    - `words_count` number, double
    - `sentences_count` number, double
    - `paragraphs_count` number, double
    - `tokens_count` number, double
    - `characters_count` number, double
    - `chunks_count` number, double

## Response `200`

Datasource successfully created

- Datasource
  - `display_name` string, required
  - `description` string, nullable — The description of the knowledge base
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'queued', required
  - `file_id` string, nullable — The unique identifier of the file used to create the datasource.
  - `created` string, required
  - `updated` string, required
  - `created_by_id` string, uuid, nullable — The user ID of the creator of the knowledge base
  - `update_by_id` string, uuid, nullable — The user ID of the last user who updated the knowledge base
  - `knowledge_id` string, required
  - `chunks_count` number, double, required
  - `processing_attempts` ProcessingAttempt[] — Additive compatibility fields formerly available only from database-shaped responses.
    - `id` string, required
    - `started_at` string, required
    - `queued_at` string
    - `completed_at` string
    - `errors` ProcessingError[]
      - `code` integer
      - `message` string
    - `retryable` boolean
  - `metadata` CountMetadata
    - `words_count` number, double
    - `sentences_count` number, double
    - `paragraphs_count` number, double
    - `tokens_count` number, double
    - `characters_count` number, double
    - `chunks_count` number, double
  - `attachment` DatasourceAttachment
    - `id` string
    - `object_name` string
  - `_id` string, required

## Other responses

- `500` — Failed to create datasource

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/2cd7e7f7bcb4/schema)