# IOPO Paper Handle API v1 Apply deterministic handling operations to an A5 sheet of MD Cotton. Each request starts from fresh stock and replays the operations in order. ## Discover - GET /api/paper/v1/capabilities for materials, commands, and limits. - GET /api/paper/v1/openapi.json for the OpenAPI 3.1 schemas. - POST /api/paper/v1/handle with Content-Type: application/json. - Open /apps for sample apps, manifest authoring, and rendered previews. These paths are relative to the IOPO origin that served this guide. The API accepts browser and server requests without a Paper API key. Private Sites also require access to the host. There are no server writes or provider calls. Save and replay your operation list for continuity. For folding charts, the separate Folding Diagram API interprets uploaded images into portable vector illustrations using OpenAI. Discover its schema and limits at GET /api/folding-diagrams/v1/capabilities and read /folding-diagrams-api.txt. This is an illustration interface, not a Paper Handle recipe or physics simulation. Interpretation requires server-side credentials and is not a free public operation. ## Example request { "operations": [ {"type":"tear","path":[[0,0.7],[1,0.7]]}, {"type":"move","piece":"piece-1","dx":0.25,"dy":0.1}, {"type":"fold","from":[0.5,0.1],"to":[0.5,0.6],"side":1,"angle":0.75}, {"type":"unfold","index":0} ] } Use [u,v] in original material coordinates. Both axes are in [0,1]; [0,0] is the original top left. Desk translation uses sheet widths for x and y. Normalized angle 1 is a 180-degree fold. Pressure, crease depth, and squeeze use [0,1]. Gather heading uses radians and rotate uses degrees. ## Handwritten Launch /apps/handwritten for the Writing Desk. A recipe can write on the original front of the sheet before or after its handling operations. {"operations":[ {"type":"write","title":"Garden note","text":"Dear Robin,\nThe hydrangeas are in bloom.","fontId":"austen"}, {"type":"fold","from":[0,0.6],"to":[1,0.6],"side":1,"angle":0.6} ]} Optional write fields include ink (#RRGGBB), colorRuns, inkOpacity, fontSize, lineSpacing, align, and the zero-based page (default 0). Discover supported fonts in writingFonts. A colorRuns entry has inclusive start and exclusive end UTF-16 offsets and a #RRGGBB color. Order the ranges, avoid overlaps, and use grapheme boundaries. Unmarked text uses ink. The latest write is returned in writing, and the preview renders that page on the original front material. To hand the full manuscript to a person, remove page from writing and save {"version":1,"document":{…}} as a .iopo-letter.json file. Reveal the top bar in Handwritten and choose My documents > Import letter. Keep the original recipe for its fold and tear geometry. ## Typeset Launch /apps/typeset for a business letter starter. The write operation accepts courier (Courier Prime), times (Tinos), et-bembo (ET Book), and arial (Arimo). These faces use even baselines and solid type. They default to fontSize 20 and lineSpacing 1.25, with both fields overridable. ## Origami Launch /apps/fortune-teller, /apps/crane, or /apps/boat. Finished recipes are available at /origami/manifests/{model}.iopo.json. Send the manifest's operations array to the handle endpoint to reproduce the model. Use /apps/boat?progress=0.21 to open the boat at 21 percent. POST {"operations":[{"type":"origami","model":"crane","progress":1}]} to the handle endpoint. Models are crane, fortune-teller, and boat. Progress runs from 0 (flat prepared stock) to 1 (complete). For a fortune-teller, add "pinch":-1 or 1 to close the opposite pocket pairs. Replay a new progress or pinch on the same model to change it. Move, turn, and rotate can be combined with the model, and write adds front-side ink. Start on a fresh sheet. The two square models use the top 148 mm of the A5 blank; the boat uses the full rectangle. pieces[0].surface contains vertices, triangular faces and original A5 uv coordinates. Vertex XYZ uses original sheet widths, before desk transforms, with z up. The same pose works with the Paper renderer. Use "layer":"flap" on a manual fold to turn a free, planar corner independently. The default fold moves all plies on its side of the hinge. ## Interpret the result - `results` lists action outcomes in request order. After a tear, read `newPieceIds` before generating a follow-on action for a detached piece. - `piece` defaults to `sheet`. Fold and gather indices are zero-based and scoped to a piece. Creases share the fold array. When changing an earlier action, recheck the resulting IDs and indices. - Read `pieces` for piece state. `pose` is a snapshot for the Paper renderer. - An error supplies `error.code`, `error.message`, and when applicable `error.operationIndex`. Fix the referenced operation and replay the recipe. To hand an app to a person, wrap the recipe in a manifest with `apiVersion` set to 1, a `name`, and the `operations` array. To execute it with the API, send its `operations` array inside the request object shown above.