Client HTTP API Reference

Client HTTP API Reference

Back to Home

Overview

CoreTrace provides HTTP server mode via --ipc serve.

Start server:

cd /Users/hugopayet/Desktop/CLaude/coretrace/build
./ctrace --ipc serve --serve-host 127.0.0.1 --serve-port 8080 --shutdown-token mytoken --shutdown-timeout-ms 5000

Endpoints:

• POST /api
• POST /shutdown
• OPTIONS /api and OPTIONS /shutdown (CORS preflight)

Request Contract (POST /api)

Top-level request fields:

• proto (string, optional, default response uses provided value or coretrace-1.0)
• id (number, optional)
• type (not validated by handler)
• method (string) - only run_analysis is supported
• params (object)

If method is unknown, response is status=error with error.code=UnknownMethod.

Supported params for run_analysis

Boolean fields (must be JSON booleans)

• verbose
• sarif_format
• static_analysis
• dynamic_analysis
• include_compdb_deps
• async

String fields (must be JSON strings)

• report_file
• output_file
• tool_config
• compile_commands
• analysis_profile
• smt
• smt_backend
• smt_secondary_backend
• smt_mode
• resource_model
• escape_model
• buffer_model
• ipc_path
• ipc

List fields (accept either CSV string or JSON array of strings)

• input
• entry_points
• invoke
• smt_rules

Param Typing and Validation Notes

• Wrong JSON types produce status=error, error.code=InvalidParams.
• ipc accepted values are standardIO, socket, serve (also accepts aliases serv and server).
• For API requests, if ipc=serve, internal run configuration is normalized to standardIO for tool execution.

tool_config Integration

When params.tool_config is provided:

1. File is loaded and merged into request config.
2. Explicit request string/list fields applied later can override loaded values.

If loading fails, response is InvalidParams with message Failed to load tool_config: ....

Success Response Shape

status=ok, with result containing:

• files (number of processed files)
• static_analysis (bool)
• dynamic_analysis (bool)
• invoked_tools (array)
• sarif_format (bool)
• report_file (string)
• tool_config (string)
• include_compdb_deps (bool)
• resource_model, escape_model, buffer_model (strings)
• analysis_profile (string)
• smt, smt_backend, smt_secondary_backend, smt_mode (strings)
• smt_rules (array)
• outputs (object keyed by tool)

outputs[tool] is an array of entries:

• stream: stdout or stderr
• message: string, or parsed JSON object/array if the captured text is valid JSON

Error Codes

• InvalidRequest: invalid JSON body or request parse exception
• UnknownMethod: unsupported method
• InvalidParams: param type/validation failure, bad IPC type, or bad tool_config
• NoAnalysisSelected: none of static_analysis, dynamic_analysis, invoke selected
• MissingInput: no resolved input files
• ServerShuttingDown: server is closing and rejects new /api work

Shutdown Endpoint (POST /shutdown)

Auth headers:

• Authorization: Bearer <token>
• or X-Admin-Token: <token>

Behavior:

• If token missing/invalid -> 403, error.code=Unauthorized
• If shutdown already in progress -> 202, status=accepted
• If accepted -> 202, server stops accepting new requests and waits for in-flight requests until shutdown-timeout-ms (or indefinitely when 0)

Example: Synchronous Request

curl -X POST http://127.0.0.1:8080/api \
  -H "Content-Type: application/json" \
  -d '{
    "proto": "coretrace-1.0",
    "id": 1,
    "type": "request",
    "method": "run_analysis",
    "params": {
      "input": ["../tests/buffer_overflow.cc"],
      "entry_points": ["main"],
      "static_analysis": true,
      "dynamic_analysis": false,
      "invoke": ["ctrace_stack_analyzer"],
      "sarif_format": false,
      "async": false,
      "verbose": true
    }
  }'

Example: Parallel Scheduling Mode (async=true)

async=true enables internal parallel tool scheduling; it does not create a background job API.

curl -X POST http://127.0.0.1:8080/api \
  -H "Content-Type: application/json" \
  -d '{
    "proto": "coretrace-1.0",
    "id": 2,
    "type": "request",
    "method": "run_analysis",
    "params": {
      "input": "../tests/buffer_overflow.cc,../tests/null_pointer.c",
      "static_analysis": true,
      "invoke": ["flawfinder", "tscancode"],
      "async": true,
      "verbose": false
    }
  }'

Example: Shutdown

curl -i -X POST http://127.0.0.1:8080/shutdown \
  -H "Authorization: Bearer mytoken"

Back to Home