Create Record

This endpoint allows you to create a new record within a specific knowledge collection in TaskingAI. The create APIs for records can be different based on the type of collection you are working with.

Endpoint

• Method: POST
• URL: https://api.tasking.ai/v1/collections/{collection_id}/records

Path Parameters

Parameter	Type	Description
collection_id	string	The unique identifier for the collection.

Header Parameters

All TaskingAI API requests require the following headers:

Header	Type	Description
Content-Type	string	The content type of the request. Set to application/json.
Authorization	string	API key for authorization in the format Bearer $TASKINGAI_API_KEY. The key can be obtained in the project settings in your TaskingAI console.

Create Record in Text Collection

Text records can be created by providing direct text content, a URL to scrape web content, or by uploading a file.

Payload Parameters

Parameter	Type	Required	Default	Description
type	string	Yes		The type of record. Possible values are "text", "file", or "web".
title	string	No	""	The title of the record, limited to 256 characters.
file_id	string	Conditional		The file ID, required when the record type is "file". Obtain the file_id by uploading file separately.
url	string	Conditional		The URL of the webpage, required when the record type is "web".
content	string	Conditional		The text content of the record, required when the record type is "text".
text_splitter	object	Yes		Defines how the text is split into chunks.
metadata	object (key-value pairs)	No	{}	Metadata for the record, which can store up to 16 key-value pairs, each key length < 64 and value length < 512.

Text Splitters

When creating records that involve text processing, you can use a text splitter to divide the content into more manageable chunks. TaskingAI currently supports two primary types of text splitters:

TokenTextSplitter

This splitter divides the text based on a specified number of tokens. It is configured with the following parameters:

• chunk_size: The maximum number of tokens per chunk. This determines how large each text chunk can be.
• chunk_overlap: The number of tokens that consecutive chunks will overlap. A value of 0 indicates that there is no overlap between chunks.

Example Usage:

{
    "type": "token",
    "chunk_size": 200,
    "chunk_overlap": 20
}

SeparatorTextSplitter

This splitter uses specified separators to divide the text into chunks. If a separated chunk exceeds the chunk_size, it will be further divided into smaller chunks.

The parameters for this splitter are:

• separators: A list of delimiter strings used to split the text.
• chunk_size: The maximum number of tokens per chunk. (This is a mandatory parameter.)
• chunk_overlap: The number of tokens that consecutive chunks will overlap. A value of 0 indicates no overlap.

Example Usage:

separator_text_splitter = {
    "type": "separator",
    "separators": ["\n\n"],
    "chunk_size": 200,
    "chunk_overlap": 20
}

Both splitters are designed to optimize the processing of large text datasets by breaking them down into manageable segments.

Request Example

{
    "type": "text",
    "title": "Machine learning",
    "content": "Machine learning is a subfield of artificial intelligence...",
    "text_splitter": {
        "type": "token",
        "chunk_size": 200,
        "chunk_overlap": 20
    },
    "metadata": {}
}

Response Example

{
  "status": "success",
  "data": {
      "object": "Record",
      "record_id": "record_1",
      "collection_id": "collection_1",
      "title": "Machine learning",
      "status": "creating",
      "num_chunks": 1,
      "type": "text",
      "content": "Machine learning is a subfield of artificial intelligence...",
      "metadata": {},
      "updated_timestamp": 1730210035453,
      "created_timestamp": 1730210035453
  }
}

info

In some cases, the record status will remain creating for a short period after the creation call. Generally, after a few minutes, the record status will change to ready.

When the record status changes to ready, it means that the text has been effectively split into smaller fragments, and the embeddings for these chunks have been constructed. Only in the ready status can the record chunks be retrieved in response to user queries.

Create Record in QA Collection

QA records allow for the structured storage of question-and-answer pairs. These records are created by uploading a .csv or .xlsx file containing Q&A data. Text splitters are not required for QA records.

Payload Parameters

Parameter	Type	Required	Default	Description
type	string	Yes		The type of record, set to "qa_sheet" for question-and-answer data.
file_id	string	Yes		The file ID for the uploaded Q&A sheet. Obtain the file_id by uploading the file separately.
metadata	object (key-value pairs)	No	{}	Metadata for the record, which can store up to 16 key-value pairs, each key length < 64 and value length < 512.

Request Example

To create a QA record, you need to upload a .csv or .xlsx file containing the Q&A data. Follow these steps:

• First, download either the CSV template file, or the Excel template file before importing.
• Second, add Q&A rows to fill in the sheet file.
• Then, upload file and get the file_id by uploading Q&A file separately.

{
    "type": "qa_sheet",
    "file_id": "YOUR_QA_SHEET_FILE_ID",
    "metadata": {}
}

Response Example

{
  "status": "success",
  "data": {
      "object": "Record",
      "record_id": "record_1",
      "collection_id": "collection_1",
      "status": "creating",
      "num_chunks": 1,
      "type": "qa_sheet",
      "metadata": {},
      "updated_timestamp": 1730210035453,
      "created_timestamp": 1730210035453
  }
}

info

Same as with text records, the record status will remain creating for a short period after the creation call. Only in the ready status can the Q&A chunks be retrieved in response to user queries.