Examples and workflows

#Summarise notes with an assistant (read-only)

1. rooqi_request_read_access → approvalRequired. Approve the window in RooQi and choose the project.
2. rooqi_request_read_access again → ready.
3. rooqi_list_approved_documents → { "<id>": "Lecture 3", … }
4. rooqi_read_note with { "documentID": "<id>" } → saved text and revision.

The assistant only sees saved text — not handwriting, images or PDF source text.

#Append a summary safely

1. Request write access and approve it.
2. Read the note to learn its current revision.
3. Generate fresh UUIDs for operationID and store them before calling.
4. Call rooqi_append_text:

{
  "operationID": "3B1F7A2C-9E44-4D51-A0C6-1E2F3A4B5C6D",
  "documentID": "<id>",
  "text": "Summary: …",
  "expectedVersion": 7,
  "provider": "example-assistant",
  "model": "example-model-1",
  "promptVersion": "summary-v1"
}

1. On mutationUncertain or a timeout, call again with the same body. On mutationRejected, read again and use a new operationID only if you intend a new write.

#Highlight a sentence in a PDF

1. rooqi_request_pdf_annotation_access, approve, call again.
2. rooqi_list_pdf_targets with the document → pick a surfaceID and page from availableSourcePages.
3. rooqi_read_pdf_page with a region, e.g. the top half of page 0:

{ "documentID": "<doc>", "surfaceID": "<surface>", "pageIndex": 0,
  "rect": { "x": 0, "y": 0, "width": 1000000, "height": 500000 } }

1. Narrow rect to the lines you want using the returned lines[].rect, read again, then call rooqi_annotate_pdf with the same query, the returned revision as expectedVersion, sourceAssetID and the three digests, kind: "highlight" and an empty comment.
2. If the result is uncertain, call rooqi_query_pdf_operation with the same operationID.