---
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

## Changes

> 253 revisions in range; 71 not diffed.

- **2026-08-24** `addad33219df` — 4 breaking, 18 info
  - the response property `metadata` became optional for the status `200`
  - the `_id` response's property type/format changed from `string`/`ulid` to `string`/`` for status `200`
  - the `created_by_id` response's property type/format changed from `string, null`/`` to `string, null`/`uuid` for status `200`
  - the `update_by_id` response's property type/format changed from `string, null`/`` to `string, null`/`uuid` for status `200`
  - …18 more
- **2026-08-21** `1586760a252f` — 10 breaking, 10 warning, 8 info
  - the response property `_id` became optional for the status `200`
  - the `chunks_count` response's property type/format changed from `number`/`double` to `number`/`` for status `200`
  - the `created_by_id` response's property type/format changed from `string, null`/`uuid` to `string, null`/`` for status `200`
  - the `metadata/characters_count` response's property type/format changed from `number`/`double` to `number`/`` for status `200`
  - …24 more
- …earlier changes not shown

[Full history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/knowledge/:knowledge_id/datasources/post.md)

---

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