--- title: REST API description: Reference for the Ghidra plugin's HATEOAS HTTP API --- The Ghidra plugin runs an HTTP server inside the JVM and exposes a HATEOAS REST API. Every response includes hypermedia links (`_links`) to related resources, so clients can discover the API by following links rather than hardcoding paths. The MCP server wraps this API as MCP tools. You generally do not need to call the REST API directly, but understanding it helps when debugging or building custom integrations. ## General Concepts ### Request Format Standard HTTP verbs: `GET` to read, `POST` to create, `PATCH` to modify, `PUT` to replace, `DELETE` to remove. Request bodies use JSON (`Content-Type: application/json`). Include an `X-Request-ID` header for correlation if needed. ### Response Envelope Every response follows this structure: ```json { "id": "req-123", "instance": "http://localhost:8192", "success": true, "result": { ... }, "_links": { "self": { "href": "/path/to/resource" }, "related": { "href": "/path/to/related" } } } ``` - `id` -- Correlation identifier from `X-Request-ID`, or a generated value. - `instance` -- URL of the plugin instance that handled the request. - `result` -- The payload. A single object for detail endpoints, an array for list endpoints. - `_links` -- HATEOAS links to related resources and actions. ### Error Responses Errors use standard HTTP status codes and include a structured error object: ```json { "id": "req-456", "instance": "http://localhost:8192", "success": false, "error": { "code": "RESOURCE_NOT_FOUND", "message": "No function at address 0x999999" } } ``` Common status codes: `200` OK, `201` Created, `400` Bad Request, `404` Not Found, `500` Internal Server Error. ### Pagination List endpoints accept `offset` and `limit` query parameters. Responses include `size` (total count), `offset`, `limit`, and `_links` with `next`/`prev` when applicable. ``` GET /functions?offset=50&limit=50 ``` ### Addressing and Search Resources can be accessed by hex address or searched by name: - By address: `GET /functions/0x401000` - By exact name: `GET /functions?name=main` - By substring: `GET /functions?name_contains=init` - By regex: `GET /functions?name_matches_regex=^FUN_` --- ## Meta Endpoints ### `GET /plugin-version` Returns the plugin build version and API version number. The MCP server uses this for compatibility checks. ```json { "result": { "plugin_version": "v2.0.0", "api_version": 2 } } ``` ### `GET /info` Returns details about the current plugin instance: loaded file, architecture, processor, address size, project name, and server port. ```json { "result": { "file": "example.exe", "architecture": "x86:LE:64:default", "processor": "x86", "addressSize": 64, "project": "MyProject", "serverPort": 8192, "instanceCount": 1 } } ``` ### `GET /instances` Lists all active plugin instances (one per open program in the Ghidra project). Each entry includes port, type, project, file, and links to connect. ### `GET /program` Returns program metadata: language ID, compiler spec, image base address, memory size, and analysis status. ```json { "result": { "name": "mybinary.exe", "languageId": "x86:LE:64:default", "compilerSpecId": "gcc", "imageBase": "0x400000", "memorySize": 1048576, "analysisComplete": true } } ``` --- ## Functions ### `GET /functions` List functions. Supports pagination and search parameters (`name`, `name_contains`, `name_matches_regex`, `addr`). ```json { "result": [ { "name": "main", "address": "0x401000" }, { "name": "init_peripherals", "address": "0x08001cf0" } ], "size": 150, "offset": 0, "limit": 50 } ``` ### `POST /functions` Create a function at an address. Body: `{ "address": "0x401000" }`. ### `GET /functions/{address}` Get function details: name, signature, size, stack depth, calling convention, varargs status. ```json { "result": { "name": "process_data", "address": "0x4010a0", "signature": "int process_data(char * data, int size)", "size": 128, "calling_convention": "__stdcall" } } ``` ### `PATCH /functions/{address}` Modify a function. Payload can include `name`, `signature`, and `comment`. ```json { "name": "calculate_checksum", "signature": "uint32_t calculate_checksum(uint8_t* buffer, size_t length)" } ``` ### `DELETE /functions/{address}` Delete the function definition at the specified address. ### `GET /functions/{address}/decompile` Get decompiled C pseudocode. Optional query parameters: | Parameter | Description | |-----------|-------------| | `syntax_tree` | `true` to include the syntax tree as JSON | | `style` | Decompiler simplification style (e.g., `normalize`) | | `timeout` | Decompilation timeout in seconds | ```json { "result": { "address": "0x4010a0", "ccode": "int process_data(char *param_1, int param_2)\n{\n ...\n}\n" } } ``` ### `GET /functions/{address}/disassembly` Get assembly listing. Supports pagination (`offset`, `limit`). ```json { "result": [ { "address": "0x4010a0", "mnemonic": "PUSH", "operands": "RBP", "bytes": "55" }, { "address": "0x4010a1", "mnemonic": "MOV", "operands": "RBP, RSP", "bytes": "4889E5" } ] } ``` ### `GET /functions/{address}/variables` List local variables for a function. Supports name search. ### `PATCH /functions/{address}/variables/{variable_name}` Modify a local variable. Payload: `{ "name": "new_name", "type": "int" }`. --- ## Data ### `GET /data` List defined data items. Supports search (`name`, `name_contains`, `addr`, `type`) and pagination. ### `POST /data` Define data at an address. Body: `{ "address": "0x402000", "type": "dword" }`. ### `GET /data/{address}` Get data item details (type, size, value representation). ### `PATCH /data/{address}` Modify a data item: change `name`, `type`, or `comment`. ### `DELETE /data/{address}` Undefine the data item at the specified address. ### `GET /strings` List defined strings. Supports pagination and a `filter` parameter for substring matching. ```json { "result": [ { "address": "0x00401234", "value": "Hello, world!", "length": 14, "type": "string" }, { "address": "0x00401250", "value": "Error: could not open file", "length": 26, "type": "string" } ] } ``` --- ## Structs ### `GET /structs` List struct data types. Supports pagination and `category` filtering. ### `GET /structs?name={name}` Get detailed struct information including all fields with offsets, types, and comments. ```json { "result": { "name": "MyStruct", "size": 16, "category": "/custom", "fields": [ { "name": "id", "offset": 0, "length": 4, "type": "int", "comment": "Unique identifier" }, { "name": "flags", "offset": 4, "length": 4, "type": "dword", "comment": "" } ] } } ``` ### `POST /structs/create` Create a struct. Body: `{ "name": "NetworkPacket", "category": "/network" }`. ### `POST /structs/addfield` Add a field. Body: `{ "struct": "NetworkPacket", "fieldName": "header", "fieldType": "dword" }`. ### `POST /structs/updatefield` Update a field. Identify by `fieldName` or `fieldOffset`, then provide `newName`, `newType`, and/or `newComment`. ### `POST /structs/delete` Delete a struct. Body: `{ "name": "NetworkPacket" }`. --- ## Symbols ### `GET /symbols` List all symbols. Supports search and pagination. Can filter by `type` (`function`, `data`, `label`). ### `POST /symbols` Create or rename a symbol. Body: `{ "address": "0x401000", "name": "my_label" }`. ### `PATCH /symbols/{address}` Modify a symbol (rename, change namespace, set as primary). ### `DELETE /symbols/{address}` Remove the symbol at the specified address. --- ## Memory ### `GET /memory/{address}` Read bytes from memory. | Parameter | Description | |-----------|-------------| | `length` | Number of bytes (required, server-imposed max) | | `format` | `hex`, `base64`, or `string` (default: `hex`) | ```json { "result": { "address": "0x402000", "length": 16, "format": "hex", "bytes": "48656C6C6F20576F726C642100000000" } } ``` ### `PATCH /memory/{address}` Write bytes. Body: `{ "bytes": "DEADBEEF", "format": "hex" }`. Use with caution. --- ## Segments ### `GET /segments` List memory segments (`.text`, `.data`, `.bss`, etc.) with address ranges, sizes, and R/W/X permissions. ### `GET /segments/{name}` Get details for a specific segment. --- ## Cross-References ### `GET /xrefs` Find cross-references. At least one query parameter is required: | Parameter | Description | |-----------|-------------| | `to_addr` | References pointing to this address | | `from_addr` | References originating from this address | | `type` | Filter: `CALL`, `READ`, `WRITE`, `DATA`, `POINTER` | Supports pagination. --- ## Analysis ### `GET /analysis` Get analysis status and list of available analyzers. ```json { "result": { "program": "mybinary.exe", "analysis_enabled": true, "available_analyzers": [ "Function Start Analyzer", "Reference Analyzer", "Decompiler Parameter ID" ] } } ``` ### `POST /analysis` Trigger re-analysis of the program. ### `GET /analysis/callgraph` Generate a call graph. | Parameter | Default | Description | |-----------|---------|-------------| | `function` | *entry point* | Starting function name | | `max_depth` | `3` | Maximum call depth | Returns `nodes` (functions) and `edges` (calls between them with call-site addresses). ### `GET /analysis/dataflow` Trace data flow from an address. | Parameter | Default | Description | |-----------|---------|-------------| | `address` | *required* | Starting address | | `direction` | `forward` | `forward` or `backward` | | `max_steps` | `50` | Maximum analysis steps | Returns a list of `steps`, each with an address, instruction, and description.