mcghidra/docs-site/src/content/docs/reference/rest-api.md

title	description
REST API	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:

{
  "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:

{
  "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.

{
  "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.

{
  "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.

{
  "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).

{
  "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.

{
  "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.

{ "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

{
  "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).

{
  "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.

{
  "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.

{
  "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)

{
  "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.

{
  "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.