REST 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.