Rosey

Add one file to a fact-check project by reference, fetched server side. Prefer get_upload_url: when your environment can upload bytes to a URL it is cheaper and stores the exact file. Use add_file only when you cannot upload but the file is reachable as a reference Rosey can fetch for you: file - ChatGPT fills this automatically for an attached file source_url - an https URL the user actually gave you, that Rosey downloads the file from File contents pasted into this call are not accepted, and a constructed or guessed source_url will not resolve to the user's file. When the file is in hand but has no real URL, get_upload_url takes it without the bytes ever entering the context. role has no default and must be set: "target" - the document being fact-checked (exactly one per job) "supporting" - a source file with ground-truth data (one or more) Common mime_type values (set it to the file's real content type): text/markdown, text/plain, text/csv, text/html, application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/msword, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.presentationml.presentation Returns: file_id (str) - pass to submit_fact_check

add_file

Poll for a fact-check result. Waits up to ~30s and returns the moment the job finishes. Call again with the same job_id while status is "running". Returns one of: Completed: {status: "completed", findings, stats, report_url?, next_step} findings groups the flagged items (todo, review, fyi). Each finding carries severity, action, title, description, anchor_text, replacement_text and source_references (file_name + passage). stats counts every claim checked, split into contradicted, unsupported and verified. report_url (when present): the hosted report, the target document with every claim annotated in place, the verified ones included. The user opens it signed in to Rosey. Still running: {status: "running", next_step: "call again..."} Failed: {status: "failed", error: "..."} Verified claims are counted in stats.verified but are not listed here. They carry nothing to act on, and the full annotated set is in the report. Scope of a completed result: findings cover only the claims Rosey extracted and checked, and stats.checked is that total. Anything the document asserts beyond those claims was not checked, and Rosey makes no claim about it. A failed result means the run did not happen and no Rosey verdict exists for the document. error carries the reason.

get_fact_check_result

List the experts you can pass to submit_fact_check(experts=[...]). Defaults to ['accuracy'] when submit_fact_check is called without experts. Returns: experts: list of {key (str), name (str), description (str)}. Pass the chosen `key` values in submit_fact_check's experts arg.

list_experts

Recent jobs, most recent first. Use this to re-find an in-progress job_id. limit: number of jobs to return, 1-100 (default 20) Returns: jobs: list of {job_id (str), status (str), created_at (ISO-8601 str)}

list_fact_check_jobs

Presigned S3 upload slot for one file. Preferred way to add a file. Use this whenever your environment can upload bytes to a URL. It stores the exact file without retyping. Only fall back to add_file when an HTTP upload is not possible (e.g. ChatGPT, Copilot, Relay). role has no default and must be set: "target" - the document being fact-checked (exactly one per job) "supporting" - a source file containing ground-truth data (one or more) method (optional, default "post"): "post" - presigned multipart POST (default). S3 enforces size and content-type. fields_list carries every form field, alongside a "file" field holding the bytes. The values are part of a signed policy, so reformatting any of them invalidates the signature. "put" - presigned PUT. Single URL, no form fields. PUT raw file bytes directly to upload_url with Content-Type header set to mime_type. Use this when multipart/form-data is not supported (e.g. relay.app). Common mime_type values (set it to the file's real content type): text/markdown, text/plain, text/csv, text/html, application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/msword, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.presentationml.presentation Returns: file_id (str) - pass to submit_fact_check upload_url (str) - upload the file bytes here upload_method (str) - "post" or "put"; determines how to upload fields (dict) - POST policy fields (empty when upload_method="put") fields_list (list) - same as fields but as [{name,value}] pairs max_bytes (int) - 20 MB cap

get_upload_url

Run the fact-check and return a job_id immediately. Idempotent on retry. Both document_file_id and supporting_file_ids are required. The call fails if either is missing; without sources there is no evidence to verify against. A limit or quota error (trial or token budget) means the fact-check did not run and no Rosey verdict was produced for the document. The error text carries the upgrade path. document_file_id - file_id from get_upload_url with role='target' supporting_file_ids - list of file_ids from get_upload_url with role='supporting' (at least one required, max 20) experts - optional list of expert keys to run (call list_experts to see the options). Defaults to ['accuracy'] when omitted. Different expert sets are treated as different runs (not deduplicated). Returns: job_id (str) - use with get_fact_check_result status (str) - "pending" or "running" deduplicated (bool) - true if an identical job was already active; the returned job_id is that existing job

submit_fact_check

Start a Rosey fact-check session. Returns a project_id required by all subsequent tools. Only call this when the user has attached BOTH a target document AND at least one supporting source file. Rosey extracts and parses both files itself, server side, and every verdict is anchored to the stored bytes. Reading, summarising or re-typing the contents into the conversation first changes nothing about the result and is not part of the flow. Returns: project_id (str) - pass to get_upload_url and submit_fact_check

initiate_rosey

Current Rosey token usage and your tier's cap for the rolling window. Returns: used (int) - input+output tokens spent in the window cap (int | null) - your tier's cap; null means unlimited window_seconds (int) - length of the rolling window resets_in_seconds (int) - seconds until the oldest entry ages out (0 if empty)

get_budget_status