API Reference
Protocol version 2: JSON lines over loopback.
One JSON object per line, UTF-8, ending in \n, at most 64 MiB. On a socket the first request is hello with the token; on stdio it isn't needed. Fields marked ? are optional and default to the client's active project or program.
Requests and responses
json
{"id": 7, "cmd": "decompile", "program": "p1:/game.exe", "address": "rva:0x5d53a0", "wait": 10000}{"id": 7, "ok": true, "result": {"c": "...", "signature": "..."}, "ms": 12}{"id": 7, "ok": false, "error": {"code": "busy", "message": "...", "details": {...}}, "ms": 500}| Request field | Meaning |
|---|---|
id | Any JSON value, echoed in the response. Unique among your unanswered requests. |
cmd | The command. |
wait | Milliseconds the request may wait for a slot or lock before busy. Default 10000. |
parallel | true runs it at once on its own thread instead of after your earlier requests. |
client, harness | Labels for this request alone (at most 128 characters each). |
A response may also carry stale (read-only views whose project changed on disk) and refreshed (projects another client refreshed). Events have no ok: ready on stdio, and progress for long requests, at most one a second.
Session
cmd | Fields | Does |
|---|---|---|
hello | client, harness, clientVersion, token | Names the client; answers protocol, minClient, hydraVersion, ghidraVersion, installId. |
ping | {"pong": true} | |
status | Everything: projects, programs, clients and their requests, lanes, imports, overlays, memory. | |
cancel | target | all | cacheBuild | Cancels requests, running or queued. |
shutdown | force | Stops the daemon; refused while other clients are connected, unless force. |
Projects
cmd | Fields | Does |
|---|---|---|
open_project | path, writable, discard | Joins the project, opening it if needed; makes it active. |
close_project | project?, discard | Leaves it, closing your programs there. |
projects | Open projects, which you joined, your active one. | |
project | project? | Paths, users, programs, revision, stale, fork. |
list | folder, recursive, programsOnly, sha256, offset, limit | Folders and programs with keys and hashes, paged. |
refresh / reopen | project?, force | Reopens a read-only view on what's saved now, for all its clients. |
fork_project | project, path, name?, writable, mode, maxCopyMb? | Makes and opens a working copy. |
import | file, folder, name, language, compiler, analyze, duplicate | Imports into a writable project, once per SHA-256. |
Programs
cmd | Fields | Does |
|---|---|---|
open_program / switch | path, writable, share, overlay?, upgrade, checkout, wait | Opens or joins a program and makes it active. |
programs | Your programs in all projects. | |
info | program?, overlay? | Language, image base, hashes, function count, mode, users, revision. |
functions | contains, regex, offset, limit (max 10000), overlay? | Functions by name, paged. |
decompile | address | name, timeout, maxChars, overlay? | C text and signature, from a pooled decompiler. |
close_program | program?, discard | Drops your use; an owner with changes must save or discard. |
Changing programs
cmd | Fields | Does |
|---|---|---|
rename | address, name, kind, expect?, overlay? | Renames a function or creates/renames a label. |
comment | address, text, type, expect?, overlay? | Sets or clears (null) a comment. |
edit | ops | Several operations in one transaction, all or none. |
analyze | options, ranges, timeout | Auto-analysis, as analyzeHeadless runs it. |
save | comment | Saves; answers the new revision. |
journal | since, author, limit | Who changed what, in commit order. |
discard_edits | author | Reverts one author's unsaved renames, labels and comments. |
script | script, args, exclusive, save, timeout, maxChars, artifact | Runs a GhidraScript; contained unless you may write. |
Overlays
cmd | Fields | Does |
|---|---|---|
apply_overlay | overlay, ops | Applies rename, label, comment, signature, data_type operations, all or none. |
promote_overlay | overlay, project | fork, save | Replays the overlay into a writable copy and saves it. |
drop_overlay | overlay | Drops it. |
overlays | Your overlays. |
Error codes
| Code | Means | Do |
|---|---|---|
busy | A slot or lock didn't come free within wait. | Retry, or raise wait. |
not_owner | Another client owns the program for writing. | Use the overlaySuggestion, join with share, or fork. |
conflict | The project or value can't be had as asked: another process's lock, a changed value, an upgrade not allowed. | Act on details.reason; retrying won't help. |
read_only | The project or program is open read-only. | Open it writable, or fork. |
unsaved_changes | Closing would lose changes. | save, or pass discard. |
no_project, no_program | Nothing active, or nothing by that name. | Open one first. |
not_found | No such address, function or file. | |
cancelled | Cancelled, or timed out. | |
failed | Ghidra raised an error; its message and a short trace are attached. | |
bad_request, unknown_command, unauthorized | The request itself is wrong. |
busy, conflict, not_owner and read_only carry details.holderInfo (who: client, name, harness, command, how long) and details.suggest: retry, fork_project, open_read_only, share or reread. With fork_project, details.suggestion is a ready request.