Skip to main content
POST
/
sources
Creates a Document or Text Source
curl --request POST \
  --url https://api.totoy.ai/v1/sources \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form document_file='@example-file' \
  --form 'title=Totoy Company Overview' \
  --form backlink=https://www.totoy.ai/totoy-company-overview.pdf \
  --form valid_from=2024-01-01T00:00:00Z \
  --form valid_until=2026-12-31T23:59:59Z \
  --form 'custom_metadata={
  "internal_tag": "general_documents"
}'
{
  "source_id": "src_oXiYDg8QOc9JsOk86idRXiywD",
  "source_type": "document",
  "bytes": 1234567,
  "created_at": "2024-03-01T00:00:00Z",
  "updated_at": "2024-03-01T00:00:00Z",
  "title": "Totoy Company Overview",
  "document_file_name": "totoy-company-overview.pdf",
  "backlink": "https://www.totoy.ai/totoy-company-overview.pdf",
  "valid_from": "2024-01-01T00:00:00Z",
  "valid_until": "2026-12-31T23:59:59Z",
  "project_id": "pj_avX7imfLaPcQnv5ckvGlOEBA9",
  "custom_metadata": {
    "internal_tag": "general_documents"
  },
  "knowledge_base_ids": [
    "kb_feMfJbeqbAEj4u8K5HqmKpUbY",
    "kb_2eMfJbeqbAEj4u8K5HqmKpUbY"
  ],
  "status": "completed",
  "pages": 27
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

​
document_file
file
required

A document file (not file name) to be uploaded to Sources. Supported file types are .pdf, .jpg, and .png.

Maximum string length: 100000000
Example:

"<binary_file>"

​
title
string

Title of the document.

Maximum string length: 512
Example:

"Totoy Company Overview"

​
backlink
string

A url to the document source that can be used by clients to link back to the original document.

Maximum string length: 512
Example:

"https://www.totoy.ai/totoy-company-overview.pdf"

​
valid_from
string<date-time> | null

From what time the Source can be used by a Knowledge Base or an Explanation. If no valid_from is set, the Source is valid from the time it is added to Sources.

Example:

"2024-01-01T00:00:00Z"

​
valid_until
string<date-time> | null

Until when the Source can be used by a Knowledge Base or an Explanation. If no valid_until is set, the Source is valid until it is removed from Sources.

Example:

"2026-12-31T23:59:59Z"

​
project_id
string | null

The unique identifier of the project this Source should be assigned to. Sources can only be used by resources with the same project_id. If no project_id is set, the Source will be assigned to the default project.

Maximum string length: 28
Example:

"pj_avX7imfLaPcQnv5ckvGlOEBA9"

​
custom_metadata
CustomMetadata · object

Custom optional metadata for a Source provided by a client. Up to 10 key-value pairs.

Example:
{ "internal_tag": "general_documents" }

Response

OK

The Source object represents a document source (.pdf, .jpg, .png) or text source (plain-text) that has been uploaded to Totoy.

​
source_id
string
required

Unique identifier for the Source.

Maximum string length: 29
Example:

"src_oXiYDg8QOc9JsOk86idRXiywD"

​
source_type
enum<string>
required

Type for this source (document or text).

Available options:
document,
text
Example:

"document"

​
bytes
integer<int32>
required

Size of the document file or text, in bytes.

Example:

1234567

​
created_at
string<date-time>
required

Date-time for when the Source was created, in ISO 8601 format.

Example:

"2024-03-01T00:00:00Z"

​
updated_at
string<date-time>
required

Date-time for when the Source was last modified, in ISO 8601 format.

Example:

"2024-03-01T00:00:00Z"

​
project_id
string
required

The unique identifier of the project this Source is assigned to. Sources can only be used by resources with the same project_id.

Maximum string length: 28
Example:

"pj_avX7imfLaPcQnv5ckvGlOEBA9"

​
title
string

Title of the document or text.

Maximum string length: 512
Example:

"Totoy Company Overview"

​
document_file_name
string | null

The file name of a Source document.

Maximum string length: 255
Example:

"totoy-company-overview.pdf"

​
backlink
string

An external url to the Source that can be used by clients to link back to the original document or text (i.e. a web page containing that text).

Maximum string length: 512
Example:

"https://www.totoy.ai/totoy-company-overview.pdf"

​
valid_from
string<date-time> | null

From what time the Source can be used by a Knowledge Base or an Explanation. If no valid_from is set, the Source is valid from the time it is added to Sources.

Example:

"2024-01-01T00:00:00Z"

​
valid_until
string<date-time> | null

Until when the Source can be used by a Knowledge Base or an Explanation. If no valid_until is set, the Source is valid until it is removed from Sources.

Example:

"2026-12-31T23:59:59Z"

​
custom_metadata
CustomMetadata · object

Custom optional metadata for a Source provided by a client. Up to 10 key-value pairs.

Example:
{ "internal_tag": "general_documents" }
​
knowledge_base_ids
string[] | null

List of Knowledge Base identifiers where this Source is used.

Maximum array length: 1500
Maximum string length: 29
Example:
[
  "kb_feMfJbeqbAEj4u8K5HqmKpUbY",
  "kb_7eMfJbeqbAEj4u8K5HqmKpUbY"
]
​
status
enum<string>

The parsing status of the Document Source. The status completed indicates that the source is ready for use. The status parameter is only available for Document Sources.

Available options:
in_progress,
completed,
failed
Example:

"in_progress"

​
pages
integer

The number of pages of the Document Source. The pages parameter is only available for Document Sources.

Example:

27