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"
}'

import requests

url = "https://api.totoy.ai/v1/sources"

files = { "document_file": ("example-file", open("example-file", "rb")) }
payload = {
    "title": "Totoy Company Overview",
    "backlink": "https://www.totoy.ai/totoy-company-overview.pdf",
    "valid_from": "2024-01-01T00:00:00Z",
    "valid_until": "2026-12-31T23:59:59Z",
    "custom_metadata": "{
  \"internal_tag\": \"general_documents\"
}"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('document_file', '<binary_string>');
form.append('title', 'Totoy Company Overview');
form.append('backlink', 'https://www.totoy.ai/totoy-company-overview.pdf');
form.append('valid_from', '2024-01-01T00:00:00Z');
form.append('valid_until', '2026-12-31T23:59:59Z');
form.append('custom_metadata', '{
  "internal_tag": "general_documents"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.totoy.ai/v1/sources', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.totoy.ai/v1/sources",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<binary_string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTotoy Company Overview\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"backlink\"\r\n\r\nhttps://www.totoy.ai/totoy-company-overview.pdf\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_from\"\r\n\r\n2024-01-01T00:00:00Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_until\"\r\n\r\n2026-12-31T23:59:59Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_metadata\"\r\n\r\n{\r\n  \"internal_tag\": \"general_documents\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.totoy.ai/v1/sources"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<binary_string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTotoy Company Overview\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"backlink\"\r\n\r\nhttps://www.totoy.ai/totoy-company-overview.pdf\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_from\"\r\n\r\n2024-01-01T00:00:00Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_until\"\r\n\r\n2026-12-31T23:59:59Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_metadata\"\r\n\r\n{\r\n  \"internal_tag\": \"general_documents\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.totoy.ai/v1/sources")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<binary_string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTotoy Company Overview\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"backlink\"\r\n\r\nhttps://www.totoy.ai/totoy-company-overview.pdf\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_from\"\r\n\r\n2024-01-01T00:00:00Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_until\"\r\n\r\n2026-12-31T23:59:59Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_metadata\"\r\n\r\n{\r\n  \"internal_tag\": \"general_documents\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.totoy.ai/v1/sources")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<binary_string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTotoy Company Overview\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"backlink\"\r\n\r\nhttps://www.totoy.ai/totoy-company-overview.pdf\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_from\"\r\n\r\n2024-01-01T00:00:00Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_until\"\r\n\r\n2026-12-31T23:59:59Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_metadata\"\r\n\r\n{\r\n  \"internal_tag\": \"general_documents\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "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
}

Sources

Creates a Document or Text Source

Creates a Document or Text Source that can be added to Knowledge Bases as a Knowledge Base Source or used as context for an Explanation. Upload a file that can be used across various endpoints. Individual document files can be up to 100 MB, text Sources can be up to 1000000 characters long, and the size of all Sources uploaded by one Organization can be up to 100 GB Document Sources are submitted as multipart/form-data and Text Sources as application/json.

POST

sources

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"
}'

import requests

url = "https://api.totoy.ai/v1/sources"

files = { "document_file": ("example-file", open("example-file", "rb")) }
payload = {
    "title": "Totoy Company Overview",
    "backlink": "https://www.totoy.ai/totoy-company-overview.pdf",
    "valid_from": "2024-01-01T00:00:00Z",
    "valid_until": "2026-12-31T23:59:59Z",
    "custom_metadata": "{
  \"internal_tag\": \"general_documents\"
}"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('document_file', '<binary_string>');
form.append('title', 'Totoy Company Overview');
form.append('backlink', 'https://www.totoy.ai/totoy-company-overview.pdf');
form.append('valid_from', '2024-01-01T00:00:00Z');
form.append('valid_until', '2026-12-31T23:59:59Z');
form.append('custom_metadata', '{
  "internal_tag": "general_documents"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.totoy.ai/v1/sources', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.totoy.ai/v1/sources",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<binary_string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTotoy Company Overview\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"backlink\"\r\n\r\nhttps://www.totoy.ai/totoy-company-overview.pdf\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_from\"\r\n\r\n2024-01-01T00:00:00Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_until\"\r\n\r\n2026-12-31T23:59:59Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_metadata\"\r\n\r\n{\r\n  \"internal_tag\": \"general_documents\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.totoy.ai/v1/sources"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<binary_string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTotoy Company Overview\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"backlink\"\r\n\r\nhttps://www.totoy.ai/totoy-company-overview.pdf\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_from\"\r\n\r\n2024-01-01T00:00:00Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_until\"\r\n\r\n2026-12-31T23:59:59Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_metadata\"\r\n\r\n{\r\n  \"internal_tag\": \"general_documents\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.totoy.ai/v1/sources")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<binary_string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTotoy Company Overview\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"backlink\"\r\n\r\nhttps://www.totoy.ai/totoy-company-overview.pdf\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_from\"\r\n\r\n2024-01-01T00:00:00Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_until\"\r\n\r\n2026-12-31T23:59:59Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_metadata\"\r\n\r\n{\r\n  \"internal_tag\": \"general_documents\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.totoy.ai/v1/sources")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<binary_string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTotoy Company Overview\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"backlink\"\r\n\r\nhttps://www.totoy.ai/totoy-company-overview.pdf\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_from\"\r\n\r\n2024-01-01T00:00:00Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"valid_until\"\r\n\r\n2026-12-31T23:59:59Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_metadata\"\r\n\r\n{\r\n  \"internal_tag\": \"general_documents\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

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

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

Pattern: ^pj_[a-zA-Z0-9]{25}$

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

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

Pattern: ^src_[a-zA-Z0-9]{25}$

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

Pattern: ^pj_[a-zA-Z0-9]{25}$

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

Pattern: ^kb_[a-zA-Z0-9]{25}$

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

Returns a list of Sources.Retrieves a Source.