API reference

API

The HTTP API of the Graspable agent on your computer. Access tokens and their levels, and the requests for projects, files and runs.

The Graspable app talks to its agent over an HTTP API on your computer. Scripts and other programs can use the same API. It listens on 127.0.0.1 only.

For most uses the grasp command or the MCP server is simpler. Use the API when you want to build your own tool.

Address and access

grasp api
# http://127.0.0.1:51877

The port changes each time the agent starts, so ask for the address each time, or read it from ~/.graspable/agent/api.json.

Every request needs Authorization: Bearer <token>. Create a token in Settings → Plugins and connectors → Access tokens, or:

grasp token create "my script" --scope run

The token is shown once. Graspable stores only a hash of it.

Level May
read Look at projects, files, runs and usage
run Also create projects, edit files, start and steer runs, answer approvals, start previews, use memory
admin Also change plugins, skills, components, sign-ins and tokens, move projects to the cloud, delete projects

A request above the token's level is answered with 403.

Projects and files

Request Does
GET /projects List projects
POST /projects { "name", "template" } Create a project. Packages install in the background; install becomes done
GET /projects/:id One project
GET /projects/:id/files File paths
GET /projects/:id/file?path=App.jsx { "path", "content" }
PUT /projects/:id/file { "path", "content" } Write a file
POST /projects/:id/preview Start the preview: { "url", "port" }
DELETE /projects/:id/preview Stop the preview
POST /projects/:id/check Build and check with the web browser or native engine: { "pass", "build", "browser" }. The browser field holds the runtime result for either kind
POST /projects/:id/install Install the project's packages again
POST /projects/:id/publish { "accessToken", "title", "visibility", "forkable" } Publish the app; accessToken is a Graspable session
POST /projects/fork { "appId" } A new project from a public app's source
GET /projects/:id/history, GET /projects/:id/history/:sha, POST /projects/:id/history/:sha/restore The project's versions, one version's changes, and going back to one

Paths are relative to the project. Paths that leave the project are refused.

Check images (0.19.0 and later)

A passing build does not mean the app ran. Read the runtime summary in browser for skipped checks, even when pass is true. Version 0.19.1 and later also returns browser.skipped with the reason when a browser, visionOS simulator, Unity play-mode connection or Unreal Metal toolchain is unavailable. Skipped native checks are retried instead of cached. Version 0.19.0 reports the reason in its summary only. If your integration requires a rendered result, reject a skipped check and inspect the available image separately.

Graspable 0.19.0 and later accepts POST /projects/:id/check?includeImage=true to include the check's available screenshot as image: { mimeType: "image/png", data: "<base64>" } plus an imageNote. Graspable 0.18.1 returns text results only. Omit the parameter for a compact response. The PNG is limited to 4 MiB; missing, invalid or larger pictures are omitted with a note. A failing runtime check may still carry a picture. Cached checks may reuse their picture; inspect the summary. This uses the existing run-level check permission and does not grant access to settings or credentials.

Motion inspection (experimental)

GET /projects/:id/motion?path=film.motion.json&frame=15 validates a motion document and returns its pose at that frame. It needs read access. It does not play, render or change the scene. Preview editing is separate from this read-only endpoint; see animation editing.

A document contains version: 1, fps: { numerator, denominator }, durationFrames and tracks. Each track has a unique id, a stable object target, a property and keys. Properties are position, scale, quaternion, opacity and visible. A target can have only one track for each property.

Each key contains frame, value and interpolation (linear, hold, smooth or bezier, applied until the next key). Smooth applies cubic smoothstep easing. Bézier keys also require bezier: [x1, y1, x2, y2]: both x values must be between 0 and 1, and y values between −4 and 4. Opacity and morph channels restrict y to 0–1 to avoid out-of-range weights. Other interpolation modes must omit bezier. The sampler solves the curve’s time coordinate before evaluating its value. Reads, copies and edits preserve these controls; USD export bakes nonlinear timing at whole frames. Frames are unique, increasing integers from zero through durationFrames - 1. Inspection also accepts fractional frames within that range. Position and scale values have three components; quaternions have four in x, y, z, w order and are normalized. Visibility uses booleans with hold interpolation; opacity is between zero and one. Rotations follow the shortest arc. Before the first key and after the last, the nearest pose holds.

Camera shots with an end pose accept optional interpolation and bezier controls. Omitted interpolation keeps smooth timing. The selected curve applies to position, rotation and field of view from startFrame to endFrame - 1. Camera Bézier values must all stay between 0 and 1; other modes omit bezier. Shot edits preserve timing, and USD export bakes the resulting movement.

{
  "version": 1,
  "fps": { "numerator": 30, "denominator": 1 },
  "durationFrames": 31,
  "tracks": [{
    "id": "move", "target": "character", "property": "position",
    "keys": [
      { "frame": 0, "value": [0, 0, 0], "interpolation": "linear" },
      { "frame": 30, "value": [2, 0, 0], "interpolation": "hold" }
    ]
  }]
}

At frame 15 this returns the character's position as [1, 0, 0]. Inspecting another frame first does not change that result. Invalid documents and frames return 400 with an explanation. The API accepts at most two million text characters, 4096 tracks and 100000 keys in total.

Animation editing API (in development)

These endpoints are available from 0.17.2. The animation editor uses them to save a take without overwriting a newer version.

Request Does
GET /projects/:id/authoring/motion?path=film.motion.json Read { revision, document }; both are null when the take does not exist
PUT /projects/:id/authoring/motion { "path", "revision", "document" } Save a validated take using the revision returned by the last read
POST /projects/:id/authoring/operations Apply a revision-checked operation batch or save a draft, with a retry receipt and guarded undo
GET /projects/:id/authoring/history?path=… Read recent accepted edit summaries, optionally filtered to a take
GET /projects/:id/authoring/query?path=… Read a compact overview, selected data or a bounded change catalog
POST /projects/:id/authoring/export Export a revision-checked take as .usda or .otio
GET /projects/:id/authoring/otio Plan supported edits from an OTIO file without changing the take
POST /projects/:id/authoring/bind { "source", "signature" } Give a rendered scene object a persistent animation identity, after checking its source has not changed

Saving a full take through PUT and binding objects need admin access. The operations endpoint needs run access, which already permits editing project files. A successful write returns the saved data and a fragment_update event. An outdated revision or an active agent run returns 409; reload and review before retrying. Edits must use a project path ending in .motion.json; protected files and paths through symlinks cannot be saved through this endpoint. These checks do not provide remote collaborative sessions or participant roles.

The operations endpoint accepts version: 1, path, actor, a unique requestId, and the revision from the last read. Supply exactly one of:

  • edits: between 1 and 128 operations (key, remove-key, move-key, remove-track, duration, shot, remove-shot, audio, or remove-audio).
  • document: the complete validated draft, for publishing local edits as one change.
  • bulk: a copy recipe with sourceTarget, distinct targets, collision (reject or replace), and optional properties, staggerFrames, frameOffset, positionOffset, and random: { seed, frameJitter?, positionJitter? }. Random offsets are stable per target and seed; staggering follows destination order. The resulting tracks remain individually editable. The operation rejects out-of-range keys and the document's track/key limits before expanding.
  • undoOf: a previous request ID submitted by this actor with the same access credential.

Use the same request ID and body when retrying a request whose response was lost. A replay returns the current snapshot, the original appliedRevision, replayed: true, and no repeated file write. Reusing an ID with different content returns 409. Receipts survive an agent restart; recovery refuses to overwrite a take changed after an interrupted save. Up to 32 recent receipts are retained, bounded to 32 MB. Never reuse request IDs after that window.

Undo checks the tracks, shots, sounds, frame rate and duration affected by the original change. It preserves unrelated edits and refuses to restore an item another edit has since changed. Actor names are labels within an access credential, not authenticated people. This supports cooperating clients on one project host; it is not a remote invitation or presence system. An active agent run still locks authoring writes.

Outside agents can use the read_motion, motion_history and edit_motion MCP tools for this workflow. A stale revision must be read and reviewed before a new batch is submitted. History returns accepted change summaries, caller labels, request IDs, revisions and timestamps (null for older receipts), without credentials or private snapshots. New built-in agent requests also receive bounded recent history automatically; current files remain authoritative.

Read only what an edit needs

read_motion now defaults to a small overview: revision, frame rate, duration and counts. Its view can be tracks for channel identities and key counts, keys for one required track, shots, audio, or changes. Track catalogs support exact target, track and property filters; shots and audio support an exact id. Key reads accept inclusive fromFrame and toFrame and include neighboring keys needed for interpolation. A range may span several pages; collect them before evaluating the curve.

Pages default to 32 items and allow limit from 1 to 256. Repeat the same filters with nextCursor; a cursor is tied to those filters and the exact content revision. revision pins a read and rejects a newer file. ifRevision returns only an unchanged receipt if the file still matches. Use that only when the previous data remains available in your context.

For view: "changes", supply since with a previously read revision. The result lists added, updated and removed track, shot and audio identities, plus current counts and whether timing metadata changed. Read the affected items separately. If the older revision has left the bounded cache, resetRequired asks for fresh reads. Each request still checks the file on disk, including edits made outside Graspable.

The edit_motion tool returns a short receipt without echoing the film or file events. revision is the current file; appliedRevision identifies the original accepted edit, which can differ on a retry after another edit. Full desktop snapshots and file-update events remain available through the existing authoring API.

Interchange files

export_motion accepts path, current revision, format (usda or otio) and output. USD supports an optional aspectRatio (default 16:9). OTIO supports name and a project-relative videoSource pointing to a full-film render. Save OTIO at the project root to keep media paths correct. The export endpoint requires run access.

The tool returns the output path, content hash (outputRevision), byte count, source revision, cache status and capability warnings. File contents stay on disk. To replace a different existing output, provide its current outputRevision; identical output is reused. Cached generation is keyed by source content, export options and adapter version. It does not skip revision or destination checks.

USD exports animated target transforms, visibility and perspective cameras. It uses meters, Y up and exact rational frame timing, baking nonlinear curves at whole frames. Target transforms are local channels on placeholder objects: geometry, parent hierarchy, materials, rigs, audio and interactive code are not reconstructed. Opacity is a custom attribute. Fractional-frame behavior can differ from the original easing. This is an animation handoff, not a complete scene export or arbitrary USD import.

OTIO exports camera-shot cuts, gaps and overlapping audio references. A render is needed to view shot media in another editor. Mix gain and fades are retained as metadata that other editors may not apply. plan_otio_import accepts path, current revision, an edited input file and optionally its expected inputRevision. It returns a reviewable batch for existing identities. Apply its exact edits with edit_motion and the returned source revision. Empty edits mean nothing changed. The plan is a snapshot of that OTIO revision; later file changes require a new plan.

Supported imports include shot renaming and retiming, audio timing and source offsets, and mute. Removing clips requires allowRemovals: true. Unsupported effects, transitions, new identities, media relinking or changed frame rates are rejected. Object keys stay at their original absolute frames, so inspect the animation after changing cut timing. Plans must fit one atomic batch of 128 operations; larger edits are refused.

The unreleased headset editing connection uses three admin-only endpoints on the desktop host:

Request Does
POST /projects/:id/authoring/headset { "path": "film.motion.json" } Start a connection for this project and take; return its session ID, expiry and headset URL
PUT /projects/:id/authoring/headset/:session Publish the desktop's sampled state and receive at most one validated headset intention
DELETE /projects/:id/authoring/headset/:session Revoke the connection

The headset receives a separate credential limited to this connection, never the desktop API credential. It expires after 30 minutes and is revoked when replaced or stopped. The preview exchanges URL credentials for HttpOnly cookies and removes them from the address. Headset writes require the preview's origin. If the desktop stops updating for ten seconds, headset editing stops accepting intentions until it reconnects. Mutations carry the state sequence they were made against; stale poses and saves are discarded instead of being applied at a different frame or to a different selection. Transport controls remain usable while playback advances. The desktop remains responsible for applying and saving every edit.

USD scenes (in development)

The USD inspector and these endpoints are available from 0.17.2. See OpenUSD scenes for the supported editing and conversion workflow.

Request Does
GET /usd/status Report whether this build has its managed OpenUSD runtime
GET /projects/:id/usd?path=…&query=… Read a stage or a scoped page; query is a URL-encoded JSON object
POST /projects/:id/usd Save a separate edit layer or converted asset with a source revision check

Reads require read access; writes require run access. The MCP tools are read_usd and write_usd, with the same request fields plus project.

Pro/Studio can use POST /asset-library with { "entitlement": "…", "query": "pallet", "offset": 0 } to search NVIDIA SimReady and Scenario assets. Optional filters accepts provider (nvidia or scenario) and format (usd, glb, blend, spz, ply, vox or fbx). Supply id instead of query for source, license, supplied preview, format variants and import limits. Search returns 24 results per page, a nullable nextOffset and pinned source revisions.

For a Scenario GLB, POST /asset-library with id, variant, preview: true and entitlement returns verified binary model data, bounded to 32 MiB. This is for the graphical viewer, not agent context. It does not write into the project. The signed grant is checked before downloading and before returning a cached or downloaded preview. A shared preview cache holds at most four files and 64 MiB; cancelled or failed downloads are not cached.

POST /projects/:id/asset-library with { "entitlement": "…", "id": "pallet_a01" } imports a checked NVIDIA package. For Scenario, use its returned id and a variant path from the detail response to download only that format; omitting variant selects the first supplied output. The receipt contains the imported path, attribution path, file count, size and revision. Both endpoints require run access and a current signed plan statement from /api/billing/entitlement; the grant is checked again before files appear. Imports preserve source files and attribution, verify hashes and refuse files over 64 MiB. No model bytes are returned in agent tool responses.

A read without query returns a stage overview, revision, rootRevision and a dependency count. revision covers the complete local dependency graph; rootRevision hashes only the root file. A glTF read provides a revision for conversion without pretending that it is already a USD stage.

Use query.view to request stage, prims, prim, properties, samples, layers, variants or changes. Scope reads with prim, property and time. limit is 1–128, default 32. Continue with nextCursor and identical filters; a cursor is pinned to its revision. Supplying revision rejects a changed scene. Supplying ifRevision returns unchanged: true when the graph still matches.

A stage read retains a bounded change baseline. For view: "changes", set since to that revision to receive added, changed and removed prim paths, then read their affected properties. If the baseline has expired, resetRequired asks for fresh reads. This is a change catalog, not a full scene diff or automatic conflict merge. Files are checked before cached results are reused. Large values carry explicit truncation markers and original lengths or counts; a preview is not a complete replacement value.

A write supplies path, revision, a separate output and one action:

  • edit: author an override layer in .usda or .usdc. edits contains 1–128 operations using op: set_attribute, remove_sample, visibility, variant or transform.
  • convert: write .usda, .usdc or .usdz with native USD composition preserved by default. flatten: true explicitly resolves composition for a derived layer or package.
  • to_glb: convert supported USD scene data to one embedded .glb.
  • from_gltf: convert a GLB or glTF into USD text, binary or a package, including supported rig and animation data.
  • extract: save the subtree at prim as a separate .usda, .usdc, .usdz or .glb asset. Keeps ancestor transforms and required materials, textures and rigs, resolves current composition and variations, and rejects unsupported external object dependencies. format must match the output suffix. GLB requires geometry; USD also accepts material-only selections.

For example, this authors a camera-lens override in a new layer:

{
  "path": "public/models/scene.usdc",
  "revision": "<revision returned by the read>",
  "action": "edit",
  "output": "public/models/scene.edits.usda",
  "edits": [{
    "op": "set_attribute", "prim": "/World/Camera",
    "property": "focalLength", "value": 50
  }]
}

set_attribute accepts an optional time and requires a USD type when creating a new property. remove_sample needs the property's time code. variant needs an existing set and selection; an empty selection blocks the weaker layer's variant selection. transform accepts a local correction using translation, quaternion or scale; it preserves the original transform-operation stack.

The write receipt contains output path, outputRevision, byte count, source revision and the conversion report. To replace a different existing output, supply its current outputRevision. Source dependencies cannot be overwritten. Use ?receipt=true to omit file events from an HTTP response; MCP receipts already omit them. Warnings and structured unsupported entries describe conversion limits. A new file does not imply that every USD feature is represented in GLB.

Files are limited to 64 MiB each, with 256 MiB and 2,048 files across the dependency graph. Reads and writes also enforce bounded pages, edit batches and conversion budgets. Local source changes invalidate the graph revision; stale writes return 409.

Runs

POST /runs starts a run and returns { "runId" }:

{
  "projectId": "3f9a12bc",
  "prompt": "Add a floor that reflects the planets.",
  "engine": "claude-code",
  "approvalPolicy": "guarded"
}
Field Meaning
engine claude-code or codex (their own sign-in on this computer), or pi (the Graspable agent)
provider For pi: { "provider": "anthropic", "modelId": "…", "apiKey": "…" }. For the others, optionally { "provider": "<engine>", "modelId": "…" }
approvalPolicy auto, guarded (default) or strict
budget { "maxCostUsd", "maxTokens" }: the run stops when either is passed
plugins Secret fields of switched-on plugins: { "<plugin>": { "<FIELD>": "…" } }
Request Does
GET /runs?projectId=:id Runs of a project
GET /runs/:id { "state", "events" }
GET /runs/:id/events?since=<seq> The same events as a stream (server-sent events) until the run is finished
POST /runs/:id/approve { "toolCallId", "approved" } Answer an approval request
POST /runs/:id/steer { "text" } Send the agent a message while it works
POST /runs/:id/cancel Stop the run
POST /runs/:id/revert Undo the run's file changes

A run's state is running, waiting_user, completed, failed or cancelled.

Events

Each event is { "runId", "seq", "ts", "event" }. The kinds you will use most:

event.type Meaning
text The agent said something
tool_call, tool_result A step and its result
approval_required The run waits for an answer. Send toolCallId to /approve
fragment_update A file was written: filePath, code
verification A check finished: kind (build, smoke, xr), pass, summary
completion The end: status (success, failure, cancelled) and summary

An example

API=$(grasp api | head -1)
TOKEN=<your token>
curl -s -X POST "$API/runs" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"projectId":"3f9a12bc","prompt":"Make the sun pulse slowly.","engine":"codex"}'

Film delivery (in development)

These routes are available from 0.17.2. All paths are project-relative and use the same local API authentication as other project routes.

Method and path Purpose
GET /projects/:id/films List delivery manifests for the interface
GET /projects/:id/films?agent=true Bounded summaries; optional action=list, limit (1–32) and revision-bound cursor
GET /projects/:id/films?agent=true&action=inspect&path=… Manifest or video revision and byte count, without movie contents
GET /projects/:id/films?agent=true&action=status Native spatial and projected-video encoder capabilities
POST /projects/:id/films?metadata=… Save raw MP4/WebM bytes and a player; metadata is URL-encoded JSON with title, projection and stereo
GET /spatial-video/status Apple MV-HEVC availability
GET /projected-video/status Apple projected HEVC availability
POST /projects/:id/spatial-video Revision-checked native conversion; append ?receipt=true for a compact agent response

A native conversion request contains source, its exact SHA-256 sourceRevision, and a separate output MOV path. An existing output needs outputRevision. Choose profile: "mv-hevc" (default) or "apmp-hevc". MV-HEVC additionally requires baselineMm, horizontalFovDegrees and disparityAdjustment. An optional manifest attaches the native master to an existing matching film delivery. Source or manifest conflicts preserve the newer file; inspect the response warnings before relying on an updated player.

Film saves and human native conversions are recorded in project history and emit file updates. Binary events contain byte counts/hashes and empty code. Run-owned tools record their changes with the owning run. Writes refuse an active conflicting agent run. Uploads are bounded to 192 MB; native conversion has separate media and duration limits.

The existing publish request accepts film (manifest path) and filmRevision. This deploys the selected film player instead of building the interactive project, under the usual account and visibility rules. See Share immersive films for formats, cloud limits and playback workflows.