Documents and files

Method	Description
list_documents	List documents.
iter_documents	Iterate over documents.
get_document	Get a document by SID.
create_document_from_markdown	Create a document from markdown text or a UTF-8 markdown file.
list_raw_files	List raw files.
iter_raw_files	Iterate over raw files.
get_raw_file	Get a raw file by SID.
upload_image	Upload an image for use in Jinko documents.
list_references	List references.
iter_references	Iterate over references.
get_reference	Get a reference by SID.
create_reference_from_pdf	Create a reference from a PDF file.
create_reference_from_doi	Create a reference from a DOI and fetch its bibliography metadata.
create_extract	Create an extract from a reference.

list_documents

list_documents(
    *,
    name: str | None = None,
    folder: Folder | str | None = None,
    limit: int | None = None,
    deleted: bool = False,
    after: str | None = None
) -> Page["Document"]

List documents.

Parameters:

Name	Type	Description	Default
name	str | None	Optional name filter.	None
folder	Folder | str | None	Optional folder filter.	None
limit	int | None	Maximum number of results to return.	None
deleted	bool	Whether to include deleted documents.	False
after	str | None	Pagination cursor.	None

Returns:

• Page['Document']: A page of Document objects.

iter_documents

iter_documents(
    *,
    name: str | None = None,
    folder: Folder | str | None = None,
    deleted: bool = False
) -> Iterator["Document"]

Iterate over documents.

Parameters:

Name	Type	Description	Default
name	str | None	Optional name filter.	None
folder	Folder | str | None	Optional folder filter.	None
deleted	bool	Whether to include deleted documents.	False

Yields:

• Document: Document objects.

get_document

get_document(
    sid: str, *, revision: int | None = None, allow_deleted: bool = False
) -> Document

Get a document by SID.

Parameters:

Name	Type	Description	Default
sid	str	The SID of the document.
revision	int | None	Optional revision number.	None
allow_deleted	bool	Whether to allow retrieving deleted documents.	False

Returns:

• Document: The requested Document.

create_document_from_markdown

create_document_from_markdown(
    *,
    markdown_content: str | bytes | None = None,
    markdown_file_path: str | Path | None = None,
    name: str | None = None,
    folder: Folder | str | None = None,
    description: str | None = None,
    version: str | dict | None = None
) -> Document

Create a document from markdown text or a UTF-8 markdown file.

The document body accepts standard Markdown and extends it with Jinko- specific URL handling. Common Markdown features such as headings, lists, emphasis, tables, code blocks, links, and images are supported.

In addition, Jinko URLs can be used directly in the markdown:

• A project item's .url on its own line can render as a rich Jinko embed.
• An uploaded image's .url can be used directly or as a normal Markdown image target.
• External HTTPS URLs keep normal Markdown link or image behavior.

Exactly one of markdown_content or markdown_file_path must be provided.

The supplied markdown becomes the full initial body of the new document.

Examples:

Create a document that references a model, an uploaded image, and an external URL:

model = client.create_empty_model("PK starter model")
image = client.upload_image(image_file_path="assets/overview.png")
document = client.create_document_from_markdown(
    markdown_content=f"""# Study Overview

    This document uses standard Markdown plus Jinko URLs.

    Embedded model:

    {model.url}

    Embedded image:

    ![Workflow diagram]({image.url})

    Links: [Model card]({model.url}) and
    [Company site](https://www.novainsilico.ai/jinko).
    """,
    name="Study Overview",
)

Create a document from a markdown file:

document = client.create_document_from_markdown(
    markdown_file_path="docs/study-overview.md",
    name="Study Overview",
)

list_raw_files

list_raw_files(
    *,
    name: str | None = None,
    folder: Folder | str | None = None,
    limit: int | None = None,
    deleted: bool = False,
    after: str | None = None
) -> Page["RawFile"]

List raw files.

Parameters:

Name	Type	Description	Default
name	str | None	Optional name filter.	None
folder	Folder | str | None	Optional folder filter.	None
limit	int | None	Maximum number of results to return.	None
deleted	bool	Whether to include deleted raw files.	False
after	str | None	Pagination cursor.	None

Returns:

• Page['RawFile']: A page of RawFile objects.

iter_raw_files

iter_raw_files(
    *,
    name: str | None = None,
    folder: Folder | str | None = None,
    deleted: bool = False
) -> Iterator["RawFile"]

Iterate over raw files.

Parameters:

Name	Type	Description	Default
name	str | None	Optional name filter.	None
folder	Folder | str | None	Optional folder filter.	None
deleted	bool	Whether to include deleted raw files.	False

Yields:

• RawFile: RawFile objects.

get_raw_file

get_raw_file(
    sid: str, *, revision: int | None = None, allow_deleted: bool = False
) -> RawFile

Get a raw file by SID.

Parameters:

Name	Type	Description	Default
sid	str	The SID of the raw file.
revision	int | None	Optional revision number.	None
allow_deleted	bool	Whether to allow retrieving deleted raw files.	False

Returns:

• RawFile: The requested RawFile.

upload_image

upload_image(
    *,
    image_content: bytes | None = None,
    image_file_path: str | Path | None = None
) -> File

Upload an image for use in Jinko documents.

This uploads to the document image route and returns a File whose .url can be inserted into document markdown. Uploaded images can be used in a Document Project Item, including as a standalone URL or in a normal Markdown image such as ![Alt text](...). This works in documents created with create_document_from_markdown() or updated with Document.update_markdown().

Exactly one of image_content or image_file_path must be provided.

Examples:

Upload an image from disk and use it in markdown:

image = client.upload_image(image_file_path="assets/overview.png")
document = client.create_document_from_markdown(
    markdown_content=f"{image.url}\n\n![Overview]({image.url})",
    name="Overview",
)

Upload image bytes and mix the image with project item and external URLs:

image = client.upload_image(image_content=image_bytes)
model = client.create_empty_model("PK starter model")
document = client.create_document_from_markdown(
    markdown_content=f"""# Report

    {model.url}

    ![Rendered plot]({image.url})

    More context: https://docs.jinko.ai/
    """,
    name="Report",
)

Parameters:

Name	Type	Description	Default
image_content	bytes | None	The image data as bytes.	None
image_file_path	str | Path | None	Path to an image file.	None

Returns:

• File: The uploaded File.

list_references

list_references(
    *,
    name: str | None = None,
    folder: Folder | str | None = None,
    limit: int | None = None,
    deleted: bool = False,
    after: str | None = None
) -> Page["Reference"]

List references.

Parameters:

Name	Type	Description	Default
name	str | None	Optional name filter.	None
folder	Folder | str | None	Optional folder filter.	None
limit	int | None	Maximum number of results to return.	None
deleted	bool	Whether to include deleted references.	False
after	str | None	Pagination cursor.	None

Returns:

• Page['Reference']: A page of Reference objects.

iter_references

iter_references(
    *,
    name: str | None = None,
    folder: Folder | str | None = None,
    deleted: bool = False
) -> Iterator["Reference"]

Iterate over references.

Parameters:

Name	Type	Description	Default
name	str | None	Optional name filter.	None
folder	Folder | str | None	Optional folder filter.	None
deleted	bool	Whether to include deleted references.	False

Yields:

• Reference: Reference objects.

get_reference

get_reference(
    sid: str, *, revision: int | None = None, allow_deleted: bool = False
) -> Reference

Get a reference by SID.

Parameters:

Name	Type	Description	Default
sid	str	The SID of the reference.
revision	int | None	Optional revision number.	None
allow_deleted	bool	Whether to allow retrieving deleted references.	False

Returns:

• Reference: The requested Reference.

create_reference_from_pdf

create_reference_from_pdf(
    *,
    pdf_content: bytes | None = None,
    pdf_file_path: str | Path | None = None,
    name: str | None = None,
    folder: Folder | str | None = None,
    description: str | None = None,
    version: str | dict | None = None,
    auto_extract_from_ocr: bool | None = None
) -> Reference

Create a reference from a PDF file.

Exactly one of pdf_content or pdf_file_path must be provided.

Parameters:

Name	Type	Description	Default
pdf_content	bytes | None	The PDF data as bytes.	None
pdf_file_path	str | Path | None	Path to a PDF file.	None
name	str | None	Optional name for the new project item.	None
folder	Folder | str | None	Optional destination folder.	None
description	str | None	Optional description for the new project item.	None
version	str | dict | None	Optional version name str. Can also be a dict with the keys name and description to set a version description.	None
auto_extract_from_ocr	bool | None	Whether to automatically extract figures and tables using OCR. The extracts are then available through Reference.list_extracts() on the returned object. Defaults to no extraction when omitted.	None

Returns:

• Reference: The created Reference.

create_reference_from_doi

create_reference_from_doi(
    doi: str,
    *,
    name: str | None = None,
    folder: Folder | str | None = None,
    description: str | None = None,
    auto_extract_from_ocr: bool | None = None
) -> Reference

Create a reference from a DOI and fetch its bibliography metadata.

Parameters:

Name	Type	Description	Default
doi	str	DOI of the reference.
name	str | None	Optional name; defaults to the bibliography title.	None
folder	Folder | str | None	Optional destination folder.	None
description	str | None	Optional description for the new project item.	None
auto_extract_from_ocr	bool | None	Whether to automatically extract figures and tables using OCR if a PDF is attached later. The extracts are then available through Reference.list_extracts() on the returned object. Defaults to no extraction when omitted.	None

Returns:

• Reference: The created Reference.

create_extract

create_extract(
    reference: Reference,
    *,
    anchors: Sequence[Mapping[str, Any]],
    text: str | None = None,
    latex: str | None = None,
    mathjs: str | None = None,
    data_table: DataTable | str | None = None,
    color: (
        Literal["Cyan", "Green", "Grey", "Orange", "Pink", "Purple", "Red"]
        | None
    ) = None,
    classification_type: (
        Literal["Statement", "Hypothesis", "Data"] | None
    ) = None,
    classification_level: (
        Literal["Weak", "Medium", "Strong", "Excellent"] | None
    ) = None,
    name: str | None = None,
    folder: Folder | str | None = None,
    description: str | None = None,
    version: str | dict[str, str] | None = None
) -> Extract

Create an extract from a reference.

reference must be a Reference object.

anchors must be a non-empty sequence of mappings. Each anchor must provide page, x, y, width, and height.

x and y start from the top-left corner of the page. width and height extend rightward and downward from that point.

Multiple anchors are typically used for multi-line text selections. For non-text rectangular extracts, only the first anchor is meaningful.

Provide at most one of text, latex, and data_table. Text creates a textual extract; latex creates a formula extract, with an optional MathJS expression; and data_table creates an extract linked to that data table. When all three are omitted, a rectangular extract is created.

When color is None, the extract color defaults to Green.

When classification_type is provided without a level, the extract is created as unevaluated. Hypothesis classifications do not support the Excellent level.