Documents

Documents

toothfairyai@latest…

Manager for document operations.

This manager provides methods to upload, download, search, and manage documents.

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> result = client.documents.upload("./document.pdf")
>>> print(f"Uploaded: {result.filename}")

Accessed via client.documents.

Methods

Method	HTTP	Endpoint
create	POST	POST /doc/create
create_from_path	—	derived
get	GET	GET /doc/get/{document_id}
update	POST	POST /doc/update
delete	DELETE	DELETE /doc/delete/{document_id}
list	GET	GET /doc/list
search	POST	POST /searcher
upload	GET	GET /documents/requestPreSignedURL
upload_from_base64	GET	GET /documents/requestPreSignedURL
download	GET	GET /documents/requestDownloadURLIncognito

create

Create a document record.

def create(
    user_id: str,
    title: str,
    doc_type: str = 'readComprehensionFile',
    topics: Optional[List[str]] = None,
    folder_id: str = 'mrcRoot',
    external_path: str = '',
    source: str = '',
    status: str = 'published',
    scope: Optional[str] = None
) -> Document

Endpoint: POST /doc/create · API service

Request fields

Field	Type	Required	Description
workspaceid	string	yes	Unique workspace identifier in UUID v4 format
userid	string	yes	User ID creating the document
data	array<object>	yes	Array of document records to ingest. Each element is a field mapping for one document row; the shape depends on the document type.

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response fields

Field	Type	Description
id	integer	Unique identifier for the document
document	array<object>	Document data structure for NLP documents
workspaceid	string	Unique workspace identifier in UUID v4 format
trainingdata	object	Training data for machine learning models
insertionat	string	Document creation timestamp
updatedat	string	Document last update timestamp
createdby	string	User ID who created the document
updatedby	string	User ID who last updated the document
topics	array<string>	Associated topic IDs
type	string	Document type classification

Allowed: nlpTraining, readComprehensionTraining, readComprehensionContent, questionAnswering, generativeTraining, readComprehensionPdf, readComprehensionFile, readComprehensionUrl | | rawtext | string | Raw text content of the document | | istrained | boolean | Whether the document has been trained | | source | string | Document source or origin | | title | string | Document title | | folderid | string | Parent folder identifier | | scope | string | Document scope for training purposes

Allowed: training, validation | | status | string | Document publication status

Allowed: draft, published, archived, suspended | | external_path | string | External file path or URL | | siteid | string | Associated site identifier | | hash | string | Document hash for validation | | tokens | integer | Number of tokens in the document | | completion_percentage | integer | Processing completion percentage |

Example

client.documents.create(user_id="agent-id", title="…")

create_from_path

Create a document from a file path or URL.

def create_from_path(
    file_path: str,
    user_id: str,
    title: Optional[str] = None,
    folder_id: str = 'mrcRoot',
    topics: Optional[List[str]] = None,
    status: str = 'published',
    scope: Optional[str] = None
) -> Document

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

client.documents.create_from_path(file_path="…", user_id="agent-id")

get

Get a document by ID.

def get(document_id: str) -> Document

Endpoint: GET /doc/get/{document_id} · API service

Response

Returns the Document object — fields documented in the create section above.

Example

client.documents.get(document_id="agent-id")

update

Update a document.

def update(
    document_id: str,
    user_id: str,
    title: Optional[str] = None,
    topics: Optional[List[str]] = None,
    folder_id: Optional[str] = None,
    status: Optional[str] = None,
    scope: Optional[str] = None
) -> Document

Endpoint: POST /doc/update · API service

Request fields

Field	Type	Required	Description
fields	object	yes	Document fields to update, as a key–value mapping of field name to new value.

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response

Returns the Document object — fields documented in the create section above.

Example

client.documents.update(document_id="agent-id", user_id="agent-id")

delete

Delete a document.

def delete(document_id: str) -> Dict[str, bool]

Endpoint: DELETE /doc/delete/{document_id} · API service

Response fields

Field	Type	Description
success	boolean	Operation success status
data	object	Response data
message	string	Optional success message

Example

client.documents.delete(document_id="agent-id")

list

List documents.

def list(
    limit: Optional[int] = None,
    offset: Optional[int] = None,
    folder_id: Optional[str] = None,
    status: Optional[str] = None,
    page: Optional[int] = None,
    page_limit: Optional[int] = None
) -> ListResponse

Endpoint: GET /doc/list · API service

Example

client.documents.list()

search

Search documents using semantic search.

def search(
    text: str,
    top_k: int = 10,
    metadata: Optional[Dict[str, Any]] = None
) -> List[Any]

Endpoint: POST /searcher · AI service

Request fields

Field	Type	Required	Description
workspaceid	string	yes	Unique workspace identifier
text	string	no	Search query for knowledge hub documents. Optional if a precomputed embedding vector is supplied; when both are present the text is ignored for vector generation.
embedding	array<number>	no	Precomputed embedding vector (flat numeric array). Conditionally required when text is absent; the handler searches using this vector directly. When text is present, embedding is optional and ignored for vector generation.
topK	integer	no	Number of documents to retrieve (backend default 5).
metadata	object	no	Optional metadata filters for advanced document search. Supports filtering by document status, specific document IDs, and topic arrays.

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response fields

Returns an array of SearchResponse; fields of each element:

Field	Type	Description
id	string	Document unique identifier
score	number	Document relevance score (0.0 to 1.0)
metadata	object	Document metadata and content

Example

client.documents.search(text="…")

upload

Upload a file.

def upload(
    file_path: str,
    folder_id: str = 'mrcRoot',
    on_progress: Optional[Callable[[int, int, int], None]] = None
) -> FileUploadResult

Endpoint: GET /documents/requestPreSignedURL · API service

Response fields

Field	Type	Description
uploadURL	string	Pre-signed S3 URL for uploading the file via HTTP PUT. The URL includes a Content-Type parameter matching the file extension (e.g., audio/wav for .wav files). You MUST set the Content-Type header in your PUT request to match.

Important: The URL expires in 300 seconds (5 minutes). | | filePath | string | Full S3 URI path where the file is stored (e.g., s3://bucket-name/imported_audio_files/{workspaceid}/filename.wav) | | fileKey | string | The S3 object key for the uploaded file. Use this value as the audio_file parameter when calling /media/audio for transcription. |

Example

client.documents.upload(file_path="…")

upload_from_base64

Upload a file from base64 data.

def upload_from_base64(
    base64_data: str,
    filename: str,
    content_type: str,
    folder_id: str = 'mrcRoot',
    on_progress: Optional[Callable[[int, int, int], None]] = None
) -> FileUploadResult

Endpoint: GET /documents/requestPreSignedURL · API service

Response

Returns the requestUploadURL object — fields documented in the upload section above.

Example

client.documents.upload_from_base64(base64_data="…", filename="…", content_type="…")

download

Download a file.

def download(
    filename: str,
    output_path: str,
    context: str = 'documents',
    on_progress: Optional[Callable[[int, int, int], None]] = None
) -> FileDownloadResult

Endpoint: GET /documents/requestDownloadURLIncognito

Field-level schema not available in the API spec for this endpoint.

Example

client.documents.download(filename="…", output_path="…")