archive_conversation
ChatGPTArchives one of the user's own awen conversations, as Archive does in awen: it leaves their active list, its messages and files stay, and restore_conversation brings it back. A person can have at most 100 active conversations in a project, so archiving one makes room for another. Ask the user before archiving, and name the conversation. A conversation whose reply is still being written is refused until it ends or cancel_turn stops it; generations that already started finish on their own.
cancel_turn
ChatGPTStops a running turn, as Stop does in awen: it saves what the reply wrote so far, charges the model calls that finished and frees the conversation. Generations that already started finish and are charged. A turn that already ended is left as it is. Answers the turn's status.
create_folder
ChatGPTCreates a folder in a project the user can edit. Pass parent_id "root" for the project root, or a folder's entry_id from list_folder or create_folder to create it inside that folder.
create_project
ChatGPTCreates an awen project at the top of the user's Projects, with its first conversation, as New project does in awen. Use it only when the user asks for a project or has none that fits, never one per request. Without a name it is Untitled and takes its name from the first message. Pass the returned project_id to create_folder, import_file or start_conversation.
create_upload
ChatGPTPrepares the upload of a file you hold that has no public URL: a file the user attached that your code sandbox can read, or a file on this machine. 1) Measure it: its exact size in bytes and its SHA-256 in hex (wc -c < FILE; shasum -a 256 FILE or sha256sum FILE; on Windows, Get-FileHash -Algorithm SHA256). 2) Call this tool with the name it gets in the Drive, its size and its SHA-256. 3) Within 10 minutes, run the returned command with /path/to/file replaced by the file's path, inside its single quotes, with any ' in the path written as '\'', and change nothing else (your host may ask the user to approve it once). If your host cannot run it, ask the user to run it: never send the request another way. It fetches awen's upload script and sends the raw bytes to upload_host, and the upload completes only with the exact file you measured. If it stops at a refusal, next_steps says what to do for its code. Without a POSIX shell, send the same requests to upload_url with the authorization. 4) Within 30 minutes, call import_file with the same project_id and folder_id and this upload_id to place the file; an upload not placed by then is deleted. Send and place one file before preparing the next. The command needs network access to script_host for the script, then to upload_host for the file. If curl cannot reach script_host it prints only its own error: ask the user to allow both hosts. Otherwise, when the command fails, its last line, starting with awen:, says what to do next. Drive takes files up to 512 MB, images up to 95 MB and any video, never programs. Only an MP4 opens as a video in awen: other formats save as plain files.
create_with_awen
ChatGPTRuns one turn of awen's creative agent in a project conversation, as a message in awen does. It can make and edit images, videos, 3D models and documents, and it can change the project's Drive. It reads the user's memories and skills itself, so name them in the prompt instead of reading them first. It spends the organisation's credits. It answers at once with a turn_id while the turn runs. Unless the host draws a card, call get_turn with that turn_id until status is no longer working: nothing is ready before that. Spending rules. A direct request from the user is approval to call this. When the idea is yours, describe the plan and ask first. A working status is no reason to start again. Never retry paid work on your own: ask the user first. A turn can end with a question: show it to the user and wait, and never answer it yourself. A retry the user asks for passes the same conversation_id. After a refusal, ask the user before starting a new conversation. One job is one conversation, so a batch goes in one call. Without conversation_id, the turn starts a new conversation. A person can have at most 100 active conversations in a project: at the limit this is refused until they archive one in the awen app. A conversation takes one turn at a time until its generations start: a second call before then is refused and names the turn. Once they start, a second call is accepted and charged on its own while the first stays working, so wait for completed unless the user asks not to.
download
ChatGPTGives one link that downloads files and folders of a project the user can open, as Download in awen does: a ZIP of up to 50 files, counting every file inside the folders, which keep their paths (one file alone downloads as itself). Pass each item's entry_id from list_folder. convert_to saves every image that converts as PNG or JPEG and keeps every other file as stored. Files still being made inside a folder are left out and counted in skipped. The link is download_url, valid until expires_at (5 minutes): it opens these files without signing in, so give it only to the user. Call again for a fresh link.
enhance
ChatGPTMakes an enhanced copy of an image or a video of a project the user can edit, as the Enhance menu of awen's Drive does, without a turn of awen's agent: the same presets at the same price, from the organisation's credits. The source stays as it is; the copy goes in folder_id, or beside the source. It answers at once while the copy is made: see next. Image presets: upscale-precision (Preserve natural detail without inventing content); upscale-generative (Reconstruct plausible missing detail); upscale-creative (Add expressive detail to AI-generated work); restore (Rebuild detail in faded or degraded photos); denoise-light (For subtle grain); denoise-medium (For visible noise); denoise-heavy (For very noisy images); sharpen-auto (Correct ordinary blur); sharpen-severe (Rebuild details that are hard to make out); adjust-auto (Improve lighting and color); adjust-white-balance (Remove unwanted color casts); adjust-colorize (Add color to a black-and-white photo). Video presets: upscale-precision (Preserve natural detail without inventing content); upscale-generative (Reconstruct plausible missing detail); upscale-creative (Adds creative detail; size is automatic, up to 4K); denoise-light (Faster cleanup for lighter noise); denoise-medium (High-quality general cleanup); denoise-heavy (For extremely noisy footage); smooth-60-fps (Smoother motion at original speed); slow-motion-2x (Twice as long with natural motion); slow-motion-4x (Four times longer with natural motion); hdr (Expand luminance and color range; high creative intelligence use); deblur (Reduce blur in fast-moving footage); colorize (Add color to black-and-white footage). For anything else, such as removing a background, ask awen with create_with_awen.
fetch
ChatGPTReads one item by the id that search or a list returned (project:…, folder:…, file:… or conversation:…). A file gives its description, tags, prompt, model and a download link valid 5 minutes; authorized_for_usage false means no member has confirmed its rights in awen yet, not that it is forbidden. With include_preview, an image, video or 3D model also comes as a small picture you can see, when you can't open the link or the user asks what it looks like: metadata.preview says included, pending when a new file's picture is not drawn yet, so ask again in a moment, not_applicable for a text file, whose text is in the answer, or unavailable; a text file (Markdown, text, CSV, HTML) gives its content, 32 KiB at a time. A folder or project gives its listing, a memory its instructions, a conversation its messages, 20 at a time. Pass metadata.next_offset back as offset to continue a file or a conversation.
get_lineage
ChatGPTReads how an image, video or 3D model was made, as awen's Lineage panel shows it: the files it came from, the step that used each one, each file's "Authorized for usage" declaration and audit severity, and the latest lineage audit. The declaration is false until a member confirms a file's rights in awen, which does not mean it is forbidden. unaudited counts the earlier files no audit has read, not this file, and the audit is null until one runs. Pass a file:… id or a media_id. Files come nearest first, up to 50 a page, with the edges from each file to the files made from it; pass next_cursor back as cursor to continue. fetch opens a file whose id is not null and gives its prompt and model. complete is false when the history is too long to read here: audit counts are then left out, and awen shows it whole.
get_turn
ChatGPTReads a turn create_with_awen started: its status, its reply's text, its tasks and the files it saved. status is working, completed, failed or stopped. The reply ends when generations start, and the turn stays working until their tasks end. completed means every file it will make is saved; a task that failed says why in failure, so tell the user and never retry on your own. text is written as generations start and never changes: it can still say an image is generating, and it is null when the reply has no words, so read status and files to know what is ready, and fetch a file for the prompt awen used. tasks and files list at most 50 tasks: more_tasks is true when the turn made more, and list_files shows them all. The call waits up to wait_seconds (0 to 30, default 15) and answers as soon as something changes, so call it again at once while status is working, with no other pause. A turn can end with a question, with or without files: show it to the user and wait, and never answer it yourself. cost_usd is what the turn's model calls and generations were charged. It is null until nothing of the turn still runs, and where usage is hidden from members; titles, summaries and file descriptions are charged apart. Pass the last cursor back, so a change between two calls is not missed. files name each file by id: pass an id to fetch for a download link valid 5 minutes.
get_turns
ChatGPTFollows up to 10 turns create_with_awen started, in one call. Each turn reads as get_turn reads it: status, task_counts, files, more_tasks, failure, cost_usd and its reply's text, with the same meanings. The call waits up to wait_seconds (0 to 30, default 15) and answers as soon as any turn changes, or at once when none can change any more, so call it again at once while a turn is working, with no other pause. Pass the last cursor back with the same turn_ids, so a change between two calls is not missed: a turn's text is then left out when it has not changed since that answer. A turn that is not found answers error and no other field. Call get_turn for a turn's tasks and why each failed, and with include_downloads for its files' download links.
import_file
ChatGPTAdds a file to a project the user can edit, as an upload in awen does: from a public URL, from a file the user attached in ChatGPT (file), from text with a name, or from a file you sent after create_upload (upload_id). Drive takes files up to 512 MB, images up to 95 MB and any video, never programs. Only an MP4 opens as a video in awen: other formats save as plain files. Pass exactly one of url, file, text or upload_id. A memory's instructions are its own Memory.md, so no file named Memory.md can be added to a memory; the user edits them in awen.
list_conversations
ChatGPTLists the user's own awen conversations in a project, or across their projects without project_id, most recently updated first, archived ones included, 50 at a time. Pass a conversation's id to fetch to read it. active_turn_id names the turn running in a conversation, or still making its files, for get_turn: null means nothing runs there. It can lag get_turn by a few seconds, and get_turn decides. A page leaves out conversations in projects the user can no longer open, so it can hold fewer than 50, or none: keep passing next_cursor back as cursor until it is null.
list_files
ChatGPTLists the images, videos, 3D models and canvases of the user's awen Library, newest first, 50 at a time: every project shared with them, or one project. Pass a file's id to fetch to read its description, prompt and download link. Pass next_cursor back as cursor for the next page.
list_folder
ChatGPTLists the folders and files directly inside a project folder, in name order, 50 at a time. Omit folder_id for the project root. Each item names its Drive entry (entry_id), its content (media_id) and its saved bytes (revision_id); pass its id to fetch to read it. Pass next_cursor back as cursor for the next page.
list_memories
ChatGPTLists the awen memories the user can use: folders of instructions and files that awen's own assistant follows, 50 at a time, with whether the user turned each on or off. Pass a memory's id to fetch to read its instructions and files. Pass next_cursor back as cursor for the next page.
list_projects
ChatGPTLists the awen projects shared with the user, most recently updated first, 50 at a time. query keeps the projects whose name contains it. Pass a project_id to list_folder, list_files or list_conversations, or its id to fetch. Pass next_cursor back as cursor for the next page.
move_file
ChatGPTMoves files and folders of a project the user can edit into one folder, in a single call. Pass each item's entry_id from list_folder, never a media_id, and folder_id "root" for the project root or a folder's entry_id. A memory never moves inside another memory, and no other file named Memory.md moves into one: a memory reads its instructions only from its own Memory.md.
open_home
ChatGPTOpens the user's awen home where the host draws apps: their projects, their recent files and what awen is making now, and a box to describe what to make. Call it only when the user asks to open awen or its home. For an answer in text about recent work or what is running, list_conversations lists the conversations. It starts nothing and costs no credits.
rename_file
ChatGPTRenames a file in a project the user can edit; the name applies to its Drive entry and its content. Pass the file's entry_id from list_folder, never a media_id. Folders can't be renamed. A memory reads its instructions from its Memory.md: that file keeps its name, and no other file in a memory can be named Memory.md; the user edits a memory's instructions in awen.
report_issue
ChatGPTTells awen's team in one sentence what awen could not do for the user: a missing capability, an answer you could not use, or a bug. Call it once, after you tried and the need went unmet, and not for a refusal that explains itself, such as a full project. It fixes nothing and costs no credits, so still tell the user what happened. Describe the gap in general terms: never include the user's words, prompts, names, file names or links.
restore_conversation
ChatGPTRestores one of the user's archived awen conversations to their active list, as Restore does in awen. A person can have at most 100 active conversations in a project: at the limit this is refused until one is archived.
restore_entries
ChatGPTBrings files and folders of a project the user can edit back from its Trash, with everything that was trashed inside the folders, as Restore in awen does. Pass the entry_ids trash_entries returned, within 30 days. Each comes back in its folder, or at the project root when that folder is gone. A folder is refused when another folder of its name now sits in the same place, and a memory when another of the user's memories took its name: rename that one first.
search
ChatGPTSearches what the user can see in awen: project names, the Library's images, videos, 3D models and canvases (by name, tags, description and prompt), folder and document names, the user's own conversation titles, and their memories. Returns up to 5 results of each kind; pass a result's id to fetch to read it. Use short keywords; list_projects, list_files and list_folder browse everything.
show_turn
ChatGPTShows a turn on a card that follows it live, where the host draws cards, and answers as get_turn does. Call it once when the user wants to see a turn again; use get_turn to follow one yourself.
start_conversation
ChatGPTStarts an empty awen conversation in a project the user can edit, as New conversation does in awen. It sends no message. A person can have at most 100 active conversations in a project: at the limit this is refused until they archive one in the awen app.
trash_entries
ChatGPTMoves files and folders of a project the user can edit to the project's Trash, with everything inside the folders, as Delete in awen does. Pass each item's entry_id from list_folder, never a media_id. Nothing is deleted for good: restore_entries brings them back for 30 days with the entry_ids this answers, and only the user empties the Trash, in awen. A file still being made can't be trashed until it is ready. Ask the user before trashing files they did not ask to remove.
whoami
ChatGPTReturns the awen user and the awen organisation this connection works in, what the connection may do, the organisation's plan, and the usage the user sees in awen. usage is null where the organisation hides it from members. plan or usage is null when awen can't read it right now. usage does not say whether a given request fits.