Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xysq.ai/llms.txt

Use this file to discover all available pages before exploring further.

The organise namespace gives you programmatic access to the folder tree and file uploads that the Organise dashboard exposes. Folders, renames, moves, deletes, and direct file uploads all run through the same backend the dashboard uses — anything you push through the SDK shows up in app.xysq.ai instantly, and is indexed into memory once extraction finishes. 
from xysq import Xysq

with Xysq() as client:
    folder = client.organise.create_folder("Notes")
    file = client.organise.upload_file("./meeting.md", folder_id=folder.id)
    client.organise.wait_for_file(file.asset_id)
    # File content is now searchable via client.memory.surface(...)
Uploaded files become part of your memory once extraction completes. Use client.memory.surface() or client.memory.synthesize() to query their contents — no separate Organise-specific search is needed.

​
list_folders

List every folder in the vault. Returns a flat array — use each folder’s parent_id to reconstruct the tree. 
folders = client.organise.list_folders()

for f in folders:
    indent = "  " * (0 if f.parent_id is None else 1)
    print(f"{indent}{f.name} ({f.id})")
Returns: list[Folder] — each with id, name, parent_id, path, is_system, chat_id, owner_kind, owner_id
The system /Chats/ folder appears in this list with is_system=True. You can’t create folders inside it or upload files directly into it — those slots are managed by Chat.

​
get_folder

Fetch one folder plus its direct subfolders. 
folder, children = client.organise.get_folder(folder_id)
print(folder.name)
for c in children:
    print(f"  - {c.name}")
Parameters
ParameterTypeDefaultDescription
folder_idstrrequiredFolder UUID
Returns: tuple[Folder, list[Folder]] — the folder and its child folders. Files inside the folder are not returned by this call.

​
create_folder

Create a new folder. Omit parent_id to nest directly under the vault root. 
notes = client.organise.create_folder("Notes")
sub = client.organise.create_folder("Q1", parent_id=notes.id)
Parameters
ParameterTypeDefaultDescription
namestrrequired1–255 chars; cannot contain /
parent_idstrNoneParent folder UUID; None = vault root
Returns: Folder Names must be unique among siblings. A collision raises XysqError.

​
rename_folder

Rename a folder. System folders (root, /Chats/) cannot be renamed. 
client.organise.rename_folder(folder.id, "Archive")

​
move_folder

Move a folder under a new parent. The folder and everything under it move together. 
client.organise.move_folder(folder.id, new_parent_id=archive.id)
You can’t move a folder into itself, into one of its own descendants, or into the system /Chats/ folder.

​
delete_folder

Delete a folder and every subfolder + file inside it. Irreversible. 
removed_count = client.organise.delete_folder(folder.id)
print(f"Removed {removed_count} files")

# Also purge what xysq extracted from those files
client.organise.delete_folder(folder.id, forget_memories=True)
Parameters
ParameterTypeDefaultDescription
folder_idstrrequiredFolder UUID
forget_memoriesboolFalseAlso remove extracted facts from the recall bank
Returns: int — number of files removed by the cascade.
Confirm with the user before calling this on anything non-empty. There is no trash.

​
upload_file

Upload one file into a folder. Two call styles — pick one: 
# From disk — filename and MIME inferred
file = client.organise.upload_file("./release-notes.md", folder_id=folder.id)

# From in-memory bytes or string — filename + mime_type required
file = client.organise.upload_file(
    content="# Release Notes\n\nv1.2.0 ships dark mode.",
    filename="release-notes.md",
    mime_type="text/markdown",
    folder_id=folder.id,
)
Parameters
ParameterTypeDefaultDescription
pathstr | PathLikeNoneRead bytes from disk. Mutually exclusive with content
contentbytes | strNoneIn-memory payload. Requires filename + mime_type
filenamestrNoneDisplay name. Defaults to the file’s basename when using path
mime_typestrNoneMIME type. Inferred from extension when using path
folder_idstrNoneDestination folder. None = vault root
Returns: OrganiseFile — asset_id, filename (auto-renamed on collision), folder_id, mime_type, size_bytes, extraction_status Limits
Limit
File size10 MB
MIME typestext/markdown, text/plain, application/pdf, application/json, text/csv, image/*
Filename collisionsAuto-renamed with (N) suffix
Files outside the allow-list and oversized payloads raise ValueError before any bytes leave the process.

​
file_status

Poll an uploaded file’s extraction status. 
status = client.organise.file_status(file.asset_id)
print(status.extraction_status)  # "pending" | "processing" | "ready" | "failed"
Returns: FileStatus — asset_id, extraction_status, error_msg

​
wait_for_file

Block until extraction finishes or times out. 
final = client.organise.wait_for_file(file.asset_id, timeout=60.0)

if final.extraction_status == "ready":
    # Contents are now searchable via client.memory.surface(...)
    memories = client.memory.surface("release notes")
Parameters
ParameterTypeDefaultDescription
asset_idstrrequiredFile to poll
timeoutfloat60.0Maximum seconds to wait
intervalfloat1.0Poll interval in seconds
Use wait_for_file() in pipelines or tests where you need the file’s content searchable before continuing.

​
Team Organise

Wrap the client in team(team_id) to operate on a team’s Organise vault instead of your personal one. Permissions follow your team role — ro members can list and download, rw and above can upload, rename, move, and delete. 
with Xysq() as client:
    team = client.team("team-uuid")
    folders = team.organise.list_folders()
    team.organise.upload_file("./report.pdf", folder_id=folders[0].id)

​
Full example

from xysq import Xysq

with Xysq() as client:
    # Set up a folder
    folder = client.organise.create_folder("ADRs")

    # Upload several markdown decision records
    for path in ["./adr-01.md", "./adr-02.md", "./adr-03.md"]:
        file = client.organise.upload_file(path, folder_id=folder.id)
        client.organise.wait_for_file(file.asset_id, timeout=60.0)
        print(f"Indexed: {file.filename}")

    # Now query them through memory — Organise content joins the same recall layer
    result = client.memory.synthesize(
        "What did we decide about health check endpoints?"
    )
    print(result.answer)

Memory

Uploaded files surface here once extraction completes

Organise feature

Overview of the folder tree, the dashboard, and the /Chats/ system folder