REST API - hitspec

The hitspec server exposes a REST API when you run hitspec serve --api-only. All endpoints are prefixed with /api/v1. Responses are JSON with Content-Type: application/json.

hitspec serve --api-only --port 8080

Security and Request Requirements

The API can read, write and delete workspace files and send arbitrary requests, so the server protects itself against web pages that try to reach it through your browser:

JSON bodies need Content-Type: application/json. A request that has a JSON body but any other content type (text/plain, application/x-www-form-urlencoded, none at all) is rejected with 415 Unsupported Media Type. curl -d sends form-encoded data by default, so add -H "Content-Type: application/json". Requests without a body (for example POST /stress/stop) need no content type. PUT /files/{path} takes the raw file text and is not affected.
Host. When the server is bound to a loopback address, the Host header must be localhost, 127.0.0.1 or [::1] (optionally with the server’s port); anything else gets 403 Forbidden (DNS-rebinding protection).
Origin. A request that carries an Origin header (browsers always send one cross-site) must come from http(s)://localhost, 127.0.0.1 or [::1] on the server’s own port, or on any port when --cors is set; otherwise 403 Forbidden. This also applies to the WebSocket upgrade. Requests without Origin (curl, scripts, server-side code) are not affected.
Token. If --api-token / HITSPEC_API_TOKEN is set, every request needs Authorization: Bearer <token> (scheme is case-insensitive) or ?token=<token>, else 401. If the server binds to a non-loopback address, or --allow-shell / --allow-db is set, and no token is configured, a random token is generated and printed once to stderr.
CORS preflights. With --cors, OPTIONS preflights from an allowed origin are answered with 204 and CORS headers without a token; the actual request still needs it.
Workspace file references. A < file body or a multipart file that points outside the workspace is refused (file reference ... is outside the workspace). This applies to run, execute, stress and contract verification. hitspec run is not subject to this.

Read-only mode

With --read-only, writes to files, hitspec.yaml, environments (switching the active environment is still allowed), stress profiles and history return 403. Running requests, stress, mock, record start/stop, contract verification, export/curl, import (POST /import/*) and POST /record/export keep working, because they only return text and write nothing. Runs in read-only mode do not persist cookies.

Timeouts and shutdown

/run and /execute are not subject to the 60s response timeout. On shutdown the server lets in-flight requests finish for up to 10s; a second signal exits at once. --parent-pid <pid> shuts the server down when that process exits, so a supervisor that dies without cleaning up does not leave it running.

Error Format

All error responses follow a consistent structure:

{
  "error": "Bad Request",
  "message": "file is required"
}

Field	Type	Description
`error`	string	HTTP status text (e.g., `"Bad Request"`, `"Not Found"`)
`message`	string	Human-readable error detail

Workspace & Files

Get Workspace Overview

Returns the workspace file tree, total request count, active environment, and whether a config file exists.

curl http://localhost:8080/api/v1/workspace

Response 200 OK

{
  "root": "/Users/you/project",
  "files": [
    {
      "path": "tests",
      "name": "tests",
      "dir": "",
      "isDir": true,
      "children": [
        {
          "path": "tests/api.http",
          "name": "api.http",
          "dir": "tests",
          "isDir": false,
          "requestCount": 5
        }
      ]
    },
    {
      "path": "smoke.http",
      "name": "smoke.http",
      "dir": "",
      "isDir": false,
      "requestCount": 3
    }
  ],
  "totalRequests": 8,
  "environment": "dev",
  "hasConfig": true
}

List Files

Returns a flat list of all .http and .hitspec files in the workspace with metadata.

curl http://localhost:8080/api/v1/files

Response 200 OK

[
  {
    "path": "/Users/you/project/tests/api.http",
    "relativePath": "tests/api.http",
    "name": "api.http",
    "size": 1234,
    "modTime": "2026-02-10T12:00:00Z",
    "requestCount": 5
  }
]

Get Parsed File

Returns the fully parsed content of a single .http or .hitspec file, including all requests, variables, assertions, and captures.

curl http://localhost:8080/api/v1/files/tests/api.http

string

required

Relative path to the file within the workspace. Uses wildcard path matching ({path...}).

Response 200 OK

{
  "path": "tests/api.http",
  "variables": [
    { "name": "baseUrl", "value": "http://localhost:3000", "line": 1 }
  ],
  "requests": [
    {
      "name": "Get Users",
      "description": "Fetch all users",
      "tags": ["users"],
      "method": "GET",
      "url": "{{baseUrl}}/users",
      "headers": [
        { "key": "Accept", "value": "application/json", "line": 5 }
      ],
      "queryParams": [
        { "key": "limit", "value": "10", "line": 6 }
      ],
      "assertions": [
        { "subject": "status", "operator": "equals", "expected": 200, "line": 8 }
      ],
      "captures": [
        { "name": "userId", "source": "body", "path": "$.data[0].id", "line": 9 }
      ],
      "line": 3,
      "metadata": {
        "timeout": 5000,
        "retry": 2,
        "depends": ["Auth Login"]
      }
    }
  ]
}

Get Raw File Content

Returns the raw text content of a file. Use this for source editing.

curl http://localhost:8080/api/v1/files/raw/tests/api.http

string

required

Relative path to the file within the workspace.

Response 200 OK with Content-Type: text/plain

@baseUrl = https://api.example.com

### Get Users
GET {{baseUrl}}/users

Create File

Create a new .http or .hitspec file in the workspace.

curl -X POST http://localhost:8080/api/v1/files \
  -H "Content-Type: application/json" \
  -d '{"path": "tests/new-api.http", "content": "### Health Check\nGET https://api.example.com/health\n"}'

Request Body

{
  path: string;      // Required. Relative path for the new file
  content?: string;  // Optional. Initial file content
}

string

required

Relative path for the new file. Must end in .http or .hitspec and be within the workspace.

Response 201 Created

{ "path": "tests/new-api.http" }

Save File

Save raw text content to an existing file. The file watcher suppresses the corresponding change notification to prevent UI reload loops.

curl -X PUT http://localhost:8080/api/v1/files/tests/api.http \
  -H "Content-Type: text/plain" \
  -d '@baseUrl = https://api.example.com

### Get Users
GET {{baseUrl}}/users
'

string

required

Relative path to the file within the workspace.

Request Body: Raw file content as text/plain. Response 200 OK

{ "path": "tests/api.http" }

Delete File

Delete a .http or .hitspec file from the workspace.

curl -X DELETE http://localhost:8080/api/v1/files/tests/old-api.http

string

required

Relative path to the file within the workspace.

Response 204 No Content

Execution

Execute Request

Execute one or more requests from a specific file. When requestName is provided, only that request runs (filtered by name). When omitted, all requests in the file execute. Real-time progress is broadcast over the WebSocket connection during execution.

curl -X POST http://localhost:8080/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"file": "tests/api.http", "requestName": "Get Users", "environment": "dev"}'

Request Body

{
  file: string;          // Required. Relative path to the .http/.hitspec file
  requestName?: string;  // Optional. Filter to a single request by name
  environment?: string;  // Optional. Override the active environment
}

string

required

Relative path to the .http or .hitspec file within the workspace.

string

Name of a specific request to execute. When omitted, all requests in the file are executed.

string

Environment name to use for variable interpolation. Overrides the server’s active environment.

Response 200 OK

{
  "file": "tests/api.http",
  "duration": 245,
  "passed": 1,
  "failed": 0,
  "skipped": 0,
  "results": [
    {
      "name": "Get Users",
      "description": "Fetch all users",
      "passed": true,
      "duration": 245,
      "request": {
        "method": "GET",
        "url": "http://localhost:3000/users",
        "headers": { "Accept": "application/json" }
      },
      "response": {
        "statusCode": 200,
        "status": "200 OK",
        "headers": { "Content-Type": "application/json" },
        "body": "{\"data\":[{\"id\":1,\"name\":\"Alice\"}]}",
        "duration": 243,
        "size": 42
      },
      "assertions": [
        {
          "subject": "status",
          "operator": "equals",
          "expected": 200,
          "actual": 200,
          "passed": true
        }
      ],
      "captures": { "userId": 1 }
    }
  ]
}

A result may also carry warnings, an array of strings with non-fatal findings (a capture that matched nothing, a {{reference}} sent unresolved). It is omitted when empty.

Run File

Run all requests in a file. Similar to execute but always runs every request (no name filter).

curl -X POST http://localhost:8080/api/v1/run \
  -H "Content-Type: application/json" \
  -d '{"file": "tests/api.http", "environment": "staging"}'

Request Body

{
  file: string;          // Required. Relative path to the file
  environment?: string;  // Optional. Override the active environment
}

string

required

Relative path to the .http or .hitspec file within the workspace.

string

Environment name to use. Overrides the server’s active environment.

Response 200 OK — same RunResultDTO structure as the Execute Request endpoint.

Environments

List Environments

Returns all environments defined in hitspec.yaml, including the currently active environment.

curl http://localhost:8080/api/v1/environments

Response 200 OK

[
  {
    "name": "dev",
    "variables": {
      "baseUrl": "http://localhost:3000",
      "token": "dev-token"
    }
  },
  {
    "name": "staging",
    "variables": {
      "baseUrl": "https://staging.api.example.com",
      "token": "staging-token"
    }
  }
]

Set Active Environment

Switch the server’s active environment. Broadcasts an environment_changed event over WebSocket.

curl -X PUT http://localhost:8080/api/v1/environments/active \
  -H "Content-Type: application/json" \
  -d '{"name": "staging"}'

Request Body

{
  name: string;  // Required. Environment name to activate
}

string

required

The name of the environment to set as active.

Response 204 No Content

Get Environment

Get the variables for a specific environment.

curl http://localhost:8080/api/v1/environments/dev

string

required

Environment name.

Response 200 OK

{
  "name": "dev",
  "variables": {
    "baseUrl": "http://localhost:3000",
    "token": "dev-token"
  }
}

Update Environment

Create or update the variables for a named environment.

curl -X PUT http://localhost:8080/api/v1/environments/dev \
  -H "Content-Type: application/json" \
  -d '{"variables": {"baseUrl": "http://localhost:4000", "token": "new-token"}}'

string

required

Environment name.

Request Body

{
  variables: Record<string, any>;  // Key-value pairs of environment variables
}

object

required

Map of variable names to values for this environment.

Response 200 OK

{
  "name": "dev",
  "variables": {
    "baseUrl": "http://localhost:4000",
    "token": "new-token"
  }
}

Config

Get Configuration

Returns the current hitspec.yaml configuration. Returns an empty object if no config file is present.

curl http://localhost:8080/api/v1/config

Response 200 OK

{
  "defaultEnvironment": "dev",
  "timeout": 30000,
  "retries": 0,
  "retryDelay": 1000,
  "followRedirects": true,
  "maxRedirects": 10,
  "validateSSL": true,
  "proxy": "",
  "headers": {
    "User-Agent": "hitspec/1.0"
  },
  "parallel": false,
  "concurrency": 5
}

Update Configuration

Partially update the server configuration. Only provided fields are updated; omitted fields remain unchanged. Changes are persisted to the hitspec.yaml config file on disk. If no config file exists, one is created in the workspace root.

curl -X PUT http://localhost:8080/api/v1/config \
  -H "Content-Type: application/json" \
  -d '{"timeout": 60000, "parallel": true, "concurrency": 10}'

Request Body

{
  defaultEnvironment?: string;
  timeout?: number;              // Milliseconds
  retries?: number;
  retryDelay?: number;           // Milliseconds
  followRedirects?: boolean;
  maxRedirects?: number;
  validateSSL?: boolean;
  proxy?: string;
  headers?: Record<string, string>;
  parallel?: boolean;
  concurrency?: number;
}

number

Request timeout in milliseconds. 0 resets it to the default (30000).

number

Number of automatic retries on failure. 0 disables retries.

boolean

Whether to follow HTTP 3xx redirects.

boolean

Whether to validate SSL/TLS certificates.

string

HTTP proxy URL (e.g., http://proxy:8080).

boolean

Whether to run independent requests in parallel.

number

Maximum number of concurrent requests in parallel mode. 0 resets it to the default (5).

A key that is present is applied even when it is 0 or "": retries: 0 disables retries and proxy: "" clears the proxy. For timeout, retryDelay, maxRedirects and concurrency, 0 resets the value to its default. Negative numbers return 400. Response 200 OK — returns the resulting configuration.

History

hitspec maintains two layers of history: a lightweight in-memory history for the current session and a persistent SQLite-backed history stored at ~/.hitspec/history.db.

Get In-Memory History

Returns the in-memory execution history for the current server session.

curl http://localhost:8080/api/v1/history

Response 200 OK

[
  {
    "id": "a1b2c3d4",
    "file": "tests/api.http",
    "requestName": "Get Users",
    "method": "GET",
    "url": "http://localhost:3000/users",
    "statusCode": 200,
    "duration": 245,
    "passed": true,
    "timestamp": "2026-02-10T12:00:00Z"
  }
]

Clear In-Memory History

Clear all in-memory history entries.

curl -X DELETE http://localhost:8080/api/v1/history

Response 204 No Content

List Persistent Runs

Returns paginated persistent run history from the SQLite database.

curl "http://localhost:8080/api/v1/history/runs?limit=20&offset=0"

number

default:"20"

Number of runs to return. Maximum 100.

number

default:"0"

Number of runs to skip for pagination.

Response 200 OK

{
  "runs": [
    {
      "id": 42,
      "filePath": "tests/api.http",
      "environment": "dev",
      "startedAt": "2026-02-10T12:00:00Z",
      "finishedAt": "2026-02-10T12:00:01Z",
      "durationMs": 1200,
      "passed": 5,
      "failed": 0,
      "skipped": 1,
      "total": 6
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Get Run Details

Returns a single run with its full results and assertion details.

curl http://localhost:8080/api/v1/history/runs/42

number

required

Numeric run ID.

Response 200 OK

{
  "id": 42,
  "filePath": "tests/api.http",
  "environment": "dev",
  "startedAt": "2026-02-10T12:00:00Z",
  "finishedAt": "2026-02-10T12:00:01Z",
  "durationMs": 1200,
  "passed": 5,
  "failed": 0,
  "skipped": 1,
  "total": 6,
  "results": [
    {
      "id": 101,
      "requestName": "Get Users",
      "method": "GET",
      "url": "http://localhost:3000/users",
      "statusCode": 200,
      "durationMs": 243,
      "passed": true,
      "description": "Fetch all users",
      "bodyPreview": "{\"data\":[{\"id\":1,\"name\":\"Alice\"}]}",
      "warnings": ["{{nobody.token}} was not resolved and was sent literally (in header X-Token)"],
      "assertions": [
        {
          "id": 201,
          "operator": "equals",
          "subject": "status",
          "expected": "200",
          "actual": "200",
          "passed": true
        }
      ]
    }
  ]
}

A result carries warnings (an array of strings, omitted when empty) when its request produced non-fatal findings. Runs stored by older versions have none.

Delete a Run

Delete a specific run and all its associated results and assertions (cascade delete).

curl -X DELETE http://localhost:8080/api/v1/history/runs/42

number

required

Numeric run ID.

Response 204 No Content

Delete All Runs

Delete all persistent run history.

curl -X DELETE http://localhost:8080/api/v1/history/runs

Response 204 No Content

List Results by Request Name

Retrieve historical results for a specific request, filtered by file path. Useful for comparing how a single request’s responses have changed over time. Results are ordered by run start time (newest first).

curl "http://localhost:8080/api/v1/history/results?requestName=GetUsers&filePath=api.http&limit=20&offset=0"

string

required

The name of the request to look up.

string

required

The file path containing the request.

number

default:"20"

Maximum number of results to return (1–100).

number

default:"0"

Number of results to skip for pagination.

Response 200 OK

{
  "results": [
    {
      "id": 101,
      "runId": 42,
      "requestName": "GetUsers",
      "method": "GET",
      "url": "https://api.example.com/users",
      "statusCode": 200,
      "durationMs": 134,
      "passed": true,
      "skipped": false,
      "error": null,
      "bodyPreview": "{\"users\": [...]}",
      "filePath": "api.http",
      "environment": "staging",
      "runStartedAt": "2026-02-19T15:30:00Z",
      "assertions": []
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}

Stress Testing

Start Stress Test

Start a load test against the requests defined in one or more files. Metrics are broadcast in real time over the WebSocket connection via stress_update messages.

curl -X POST http://localhost:8080/api/v1/stress/start \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["tests/api.http"],
    "duration": "30s",
    "rate": 50,
    "vus": 10,
    "maxVUs": 20
  }'

Request Body

{
  files: string[];       // Required. List of .http/.hitspec files (relative paths)
  duration?: string;     // Required unless profile is set. Go duration string (e.g., "30s", "5m", "1h")
  rate?: number;         // Optional. Target requests per second
  vus?: number;          // Optional. Number of virtual users (switches to VU mode)
  maxVUs?: number;       // Optional. Maximum concurrent virtual users
  profile?: string;      // Optional. Name of a saved stress profile (stress.profiles in hitspec.yaml)
}

string[]

required

List of .http or .hitspec file paths relative to the workspace.

string

Duration of the stress test as a Go duration string (e.g., "30s", "5m", "1h"). Required unless profile is set, in which case the profile’s duration is used.

string

Name of a saved stress profile. The profile’s duration, rate, VUs, max VUs, think time, ramp-up and thresholds are the base for the run; duration, rate, vus and maxVUs in the request win over the profile’s. A threshold written without an operator gets the metric’s natural one (rps means >, the others <), and one written with an operator keeps it. An unknown profile is a 400 Bad Request.

number

Target requests per second in rate mode.

number

Number of virtual users. Setting this switches from rate mode to VU mode.

number

Maximum number of concurrent virtual users.

Response 200 OK

{ "status": "started" }

Error 409 Conflict if a stress test is already running.

Stop Stress Test

Stop a running stress test. If no test is currently running, the endpoint returns 200 OK with an "already_stopped" status instead of an error.

curl -X POST http://localhost:8080/api/v1/stress/stop

Response 200 OK

{ "status": "stopping" }

When no test is running:

{ "status": "already_stopped" }

Get Stress Test Status

Returns whether a stress test is running and, if so, the current metrics.

curl http://localhost:8080/api/v1/stress/status

Response 200 OK

{
  "running": true,
  "elapsed": 15.3,
  "duration": 60,
  "stats": {
    "total": 750,
    "success": 745,
    "errors": 5,
    "rps": 49.8,
    "p50Ms": 12.5,
    "p95Ms": 45.2,
    "p99Ms": 120.0,
    "maxMs": 350.0,
    "errorRate": 0.0067,
    "activeVUs": 10,
    "incomplete": 3,
    "assertionChecks": 745,
    "assertionFailures": 2
  }
}

incomplete counts requests still in flight, and assertionChecks / assertionFailures count responses that were checked against expect lines and those that failed one. Assertion failures are not part of errors. The three fields are omitted when zero, and the same fields appear in stress_update messages. duration is the run’s configured length in seconds (from the request or its profile), so a client can draw progress as elapsed / duration; it is omitted when unknown. When no stress test is running:

{ "running": false, "elapsed": 0, "stats": null }

Get Stress Test Result

Returns the result of the last completed stress test, including summary metrics, latency percentiles, and per-request breakdown.

curl http://localhost:8080/api/v1/stress/result

Response 200 OK

{
  "durationMs": 30000,
  "total": 1500,
  "success": 1485,
  "errors": 15,
  "timeouts": 0,
  "rps": 50.0,
  "successRate": 0.99,
  "errorRate": 0.01,
  "p50Ms": 12.5,
  "p95Ms": 45.2,
  "p99Ms": 120.0,
  "minMs": 2.1,
  "maxMs": 350.0,
  "meanMs": 25.3,
  "stdDevMs": 18.7,
  "incomplete": 4,
  "assertionChecks": 1485,
  "assertionFailures": 3,
  "assertionFailRate": 0.002,
  "warnings": ["target rate 50/s was not reached (achieved 41/s)"],
  "thresholds": [
    { "name": "p95", "passed": true, "expected": "< 200ms", "actual": "45.2ms" }
  ],
  "breakdown": [
    {
      "name": "Get Users",
      "total": 750,
      "success": 745,
      "errors": 5,
      "p50Ms": 11.0,
      "p95Ms": 40.0,
      "p99Ms": 100.0,
      "meanMs": 22.1,
      "assertionFailures": 2
    }
  ],
  "timeSeries": [],
  "timestamp": "2026-02-10T12:00:30Z"
}

incomplete, assertionChecks, assertionFailures, assertionFailRate, warnings, thresholds and breakdown[].assertionFailures are omitted when empty or zero. incomplete requests were still in flight when the window closed and are not counted in total or errors. warnings describe the run itself, for example a target rate that was not reached. When the run could not start (invalid settings, a failed setup request), the result has an error field saying why and its counters are zero. The final stress_update WebSocket event ("completed": true) carries the same error. When no result is available:

{ "error": "Not Found", "message": "no stress test result available" }

List Stress Profiles

Returns the stress test profiles defined in hitspec.yaml.

curl http://localhost:8080/api/v1/stress/profiles

Response 200 OK

[
  {
    "name": "smoke",
    "duration": "10s",
    "rate": 5
  },
  {
    "name": "load",
    "duration": "5m",
    "rate": 100,
    "thresholds": {
      "p95": "200ms",
      "errors": "1%"
    }
  },
  {
    "name": "spike",
    "duration": "2m",
    "vus": 200,
    "maxVUs": 500,
    "rampUp": "30s",
    "thinkTime": "500ms"
  }
]

Create Stress Profile

Create a new stress profile. The profile is persisted to hitspec.yaml.

curl -X POST http://localhost:8080/api/v1/stress/profiles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "smoke",
    "duration": "30s",
    "rate": 10,
    "maxVUs": 5
  }'

Request Body

{
  name: string;           // Required. Unique profile name
  duration: string;       // Required. Go duration string (e.g., "30s", "5m")
  rate?: number;          // Optional. Target requests per second
  vus?: number;           // Optional. Number of virtual users
  maxVUs?: number;        // Optional. Maximum concurrent virtual users
  rampUp?: string;        // Optional. Ramp-up duration
  thinkTime?: string;     // Optional. Think time between requests per VU
  thresholds?: {          // Optional. Pass/fail thresholds
    p95?: string;
    p99?: string;
    errors?: string;
  };
}

string

required

Unique name for the profile. Must not conflict with an existing profile.

string

required

Duration of the stress test as a Go duration string.

Response 201 Created

{ "name": "smoke" }

Error 409 Conflict if a profile with the same name already exists.

Update Stress Profile

Update an existing stress profile. The changes are persisted to hitspec.yaml.

curl -X PUT http://localhost:8080/api/v1/stress/profiles/smoke \
  -H "Content-Type: application/json" \
  -d '{"duration": "1m", "rate": 20, "maxVUs": 10}'

string

required

Name of the profile to update.

Request Body: Same fields as Create Stress Profile (except name). Response 200 OK

{ "name": "smoke" }

Error 404 Not Found if the profile does not exist.

Delete Stress Profile

Delete a stress profile. The deletion is persisted to hitspec.yaml.

curl -X DELETE http://localhost:8080/api/v1/stress/profiles/smoke

string

required

Name of the profile to delete.

Response 204 No Content Error 404 Not Found if the profile does not exist.

Mock Server

Start Mock Server

Start a mock server that serves responses based on the request/response pairs defined in your .http files. Incoming requests to the mock server are broadcast over WebSocket as mock_request events.

curl -X POST http://localhost:8080/api/v1/mock/start \
  -H "Content-Type: application/json" \
  -d '{"files": ["mocks/users.http"], "port": 3000, "delay": "100ms"}'

Request Body

{
  files: string[];    // Required. List of .http/.hitspec files with mock definitions
  port?: number;      // Optional. Port for the mock server (default: 3000)
  delay?: string;     // Optional. Artificial response delay (Go duration, e.g., "100ms")
}

string[]

required

List of .http or .hitspec file paths containing request/response pairs.

number

default:"3000"

Port on which the mock server will listen.

string

Artificial delay before each response, as a Go duration string (e.g., "100ms", "1s").

Response 200 OK

{
  "running": true,
  "port": 3000,
  "routes": [
    {
      "method": "GET",
      "path": "/users",
      "name": "Get Users",
      "statusCode": 200,
      "contentType": "application/json"
    },
    {
      "method": "POST",
      "path": "/users",
      "name": "Create User",
      "statusCode": 201,
      "contentType": "application/json"
    }
  ]
}

Error 409 Conflict if a mock server is already running, or if the port is busy or the address cannot be bound.

Stop Mock Server

Stop the running mock server.

curl -X POST http://localhost:8080/api/v1/mock/stop

Response 200 OK

{ "status": "stopping" }

Get Mock Routes

Returns the current status and registered routes of the mock server.

curl http://localhost:8080/api/v1/mock/routes

Response 200 OK (when running)

{
  "running": true,
  "port": 3000,
  "routes": [
    {
      "method": "GET",
      "path": "/users",
      "name": "Get Users",
      "statusCode": 200,
      "contentType": "application/json"
    }
  ]
}

Response 200 OK (when not running)

{ "running": false }

Contract Testing

Verify Contracts

Run contract verification against a live provider. Sends each request defined in the contract files to the provider URL and validates the responses match expectations.

curl -X POST http://localhost:8080/api/v1/contract/verify \
  -H "Content-Type: application/json" \
  -d '{
    "providerUrl": "http://localhost:3000",
    "stateHandler": "./scripts/setup-state.sh",
    "files": ["contracts/users.http"]
  }'

Request Body

{
  providerUrl: string;      // Required. Base URL of the provider to verify against
  stateHandler?: string;    // Optional. Path to an executable that sets up provider state (needs --allow-shell)
  files?: string[];         // Optional. Specific contract files (defaults to all workspace files)
}

string

required

The base URL of the provider service to verify contracts against.

string

Path to a script that is run with the state name as its argument before each interaction that declares a state. Because this executes a program on the server, the request is rejected with 403 Forbidden unless the server was started with --allow-shell, and the script (after resolving symlinks) must be inside the workspace. Relative paths are resolved from the workspace root.

string[]

List of contract file paths. When omitted, all .http/.hitspec files in the workspace are used.

Response 200 OK

[
  {
    "file": "contracts/users.http",
    "passed": 3,
    "failed": 0,
    "skipped": 0,
    "duration": 450,
    "results": [
      {
        "name": "Get Users",
        "provider": "UserService",
        "state": "users exist",
        "passed": true,
        "duration": 150
      },
      {
        "name": "Create User",
        "provider": "UserService",
        "state": "no users",
        "passed": true,
        "duration": 200
      }
    ]
  }
]

List Contract Files

Returns all .http/.hitspec files in the workspace that can be used as contract files.

curl http://localhost:8080/api/v1/contract/files

Response 200 OK

{
  "files": [
    "contracts/users.http",
    "contracts/orders.http",
    "tests/api.http"
  ]
}

Recording Proxy

Start Recording

Start a recording proxy that captures HTTP traffic passing through it. The proxy forwards requests to the target URL and records both request and response.

curl -X POST http://localhost:8080/api/v1/record/start \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "http://localhost:3000",
    "port": 8081,
    "deduplicate": true
  }'

Request Body

{
  targetUrl: string;       // Required. URL to proxy requests to
  port?: number;           // Optional. Proxy listen port (default: 8081)
  deduplicate?: boolean;   // Optional. Remove duplicate request recordings
  exclude?: string[];      // Optional. URL patterns to exclude from recording
  sanitize?: string[];     // Optional. Header names to sanitize in recordings
}

string

required

The upstream URL that the proxy forwards requests to.

number

default:"8081"

Port on which the recording proxy will listen.

boolean

default:"false"

When true, duplicate requests with the same method and path are only recorded once.

string[]

List of URL path patterns to exclude from recording.

string[]

List of header names whose values should be sanitized (replaced with placeholders) in the recorded output.

Response 200 OK

{
  "status": "started",
  "port": 8081
}

Error 409 Conflict if a recording proxy is already running, or if the port is busy or the address cannot be bound. 400 Bad Request if targetUrl is missing or is not a valid URL.

Stop Recording

Stop the recording proxy.

curl -X POST http://localhost:8080/api/v1/record/stop

Response 200 OK

{ "status": "stopping" }

Get Recording Status

Returns whether the recording proxy is running, how many requests have been captured, and the captured request details.

curl http://localhost:8080/api/v1/record/status

Response 200 OK (when running)

{
  "running": true,
  "targetUrl": "http://localhost:3000",
  "port": 8081,
  "count": 12,
  "recordings": [
    {
      "method": "GET",
      "path": "/users",
      "url": "http://localhost:3000/users",
      "contentType": "application/json",
      "statusCode": 200,
      "duration": 45
    },
    {
      "method": "POST",
      "path": "/users",
      "url": "http://localhost:3000/users",
      "contentType": "application/json",
      "statusCode": 201,
      "duration": 67
    }
  ]
}

Response 200 OK (when not running)

{ "running": false, "count": 0 }

Export Recordings

Export all captured recordings as .http file content. The proxy must be running.

curl -X POST http://localhost:8080/api/v1/record/export

Response 200 OK

{
  "content": "### Get Users\nGET http://localhost:3000/users\nAccept: application/json\n\n### Create User\nPOST http://localhost:3000/users\nContent-Type: application/json\n\n{\"name\": \"Alice\"}\n"
}

Clear Recordings

Clear all captured recordings without stopping the proxy.

curl -X DELETE http://localhost:8080/api/v1/record/clear

Response 200 OK

{ "status": "cleared" }

Import

Import curl

Convert a curl command or a file containing curl commands into .http format.

# From a command string
curl -X POST http://localhost:8080/api/v1/import/curl \
  -H "Content-Type: application/json" \
  -d '{"command": "curl -X GET https://api.example.com/users -H \"Authorization: Bearer token\""}'

# From a file
curl -X POST http://localhost:8080/api/v1/import/curl \
  -H "Content-Type: application/json" \
  -d '{"filePath": "exports/commands.sh"}'

Request Body

{
  command?: string;    // A curl command string to convert
  filePath?: string;   // Path to a file containing curl commands (relative to workspace)
}

One of command or filePath is required.

string

A curl command string to convert to .http format.

string

Path to a file containing curl commands, relative to the workspace.

Response 200 OK

{
  "content": "### Imported Request\nGET https://api.example.com/users\nAuthorization: Bearer token\n",
  "requestCount": 1
}

Import Insomnia

Convert an Insomnia export (JSON) into .http format.

# From inline JSON data
curl -X POST http://localhost:8080/api/v1/import/insomnia \
  -H "Content-Type: application/json" \
  -d '{"data": "{\"_type\":\"export\",\"resources\":[...]}"}'

# From a file
curl -X POST http://localhost:8080/api/v1/import/insomnia \
  -H "Content-Type: application/json" \
  -d '{"filePath": "insomnia-export.json"}'

Request Body

{
  data?: string;       // Insomnia export JSON as a string
  filePath?: string;   // Path to an Insomnia export file (relative to workspace)
}

One of data or filePath is required.

string

Insomnia export JSON content as a string.

string

Path to an Insomnia JSON export file, relative to the workspace.

Response 200 OK

{
  "content": "### Get Users\nGET https://api.example.com/users\n\n### Create User\nPOST https://api.example.com/users\nContent-Type: application/json\n\n{\"name\":\"Alice\"}\n",
  "requestCount": 2
}

Import OpenAPI

Convert an OpenAPI specification (YAML or JSON, v2 or v3) into .http format. The spec can be a local file path or a URL.

# From a local file
curl -X POST http://localhost:8080/api/v1/import/openapi \
  -H "Content-Type: application/json" \
  -d '{"specPath": "openapi.yaml", "baseUrl": "http://localhost:3000"}'

# From a URL
curl -X POST http://localhost:8080/api/v1/import/openapi \
  -H "Content-Type: application/json" \
  -d '{"specPath": "https://petstore.swagger.io/v2/swagger.json"}'

Request Body

{
  specPath: string;    // Required. Path or URL to the OpenAPI spec
  baseUrl?: string;    // Optional. Override the base URL in the spec
}

string

required

Path to the OpenAPI specification file (relative to workspace) or a URL. Supports YAML and JSON, OpenAPI v2 and v3.

string

Override the base URL from the spec. Useful when the spec references a production URL but you want to target localhost.

Response 200 OK

{
  "content": "### List Pets\nGET http://localhost:3000/pets\n\n### Create Pet\nPOST http://localhost:3000/pets\nContent-Type: application/json\n\n{\"name\":\"Fido\",\"tag\":\"dog\"}\n",
  "requestCount": 2
}

Export

Export as curl

Convert requests from a .http/.hitspec file into curl commands.

# Export all requests in a file
curl -X POST http://localhost:8080/api/v1/export/curl \
  -H "Content-Type: application/json" \
  -d '{"file": "tests/api.http"}'

# Export a specific request
curl -X POST http://localhost:8080/api/v1/export/curl \
  -H "Content-Type: application/json" \
  -d '{"file": "tests/api.http", "requestName": "Create User"}'

Request Body

{
  file: string;            // Required. Relative path to the file
  requestName?: string;    // Optional. Export only this named request
}

string

required

Relative path to the .http or .hitspec file in the workspace.

string

Name of a specific request to export. When omitted, all requests are exported.

Response 200 OK

{
  "commands": [
    "curl -X GET 'http://localhost:3000/users' -H 'Accept: application/json'",
    "curl -X POST 'http://localhost:3000/users' -H 'Content-Type: application/json' -d '{\"name\":\"Alice\"}'"
  ]
}

System

Get System Info

Returns version, build time, Go version, and platform information.

curl http://localhost:8080/api/v1/system/info

Response 200 OK

{
  "version": "2.6.0",
  "buildTime": "2026-02-10T12:00:00Z",
  "goVersion": "go1.25.0",
  "os": "darwin",
  "arch": "arm64"
}

WebSocket

Connect

Establish a WebSocket connection for real-time event streaming. The server pushes events as they occur — no polling required.

ws://localhost:8080/api/v1/ws

The WebSocket endpoint accepts connections from localhost, 127.0.0.1, and [::1] origins only.

Connection Example

const ws = new WebSocket('ws://localhost:8080/api/v1/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg.payload);
};

// Keep alive with ping/pong
setInterval(() => {
  ws.send(JSON.stringify({ type: 'ping' }));
}, 30000);

Message Envelope

All WebSocket messages use this envelope format:

{
  type: string;        // Message type identifier
  payload: any;        // Type-specific payload
  timestamp: string;   // ISO 8601 timestamp (UTC)
}

Message Types

`execution_start`

Sent when a request execution begins.

{
  "type": "execution_start",
  "payload": {
    "id": "a1b2c3d4",
    "file": "tests/api.http",
    "status": "started",
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}

`request_progress`

Sent for each individual request as it starts and completes during an execution.

{
  "type": "request_progress",
  "payload": {
    "execId": "a1b2c3d4",
    "file": "tests/api.http",
    "requestName": "Get Users",
    "status": "completed",
    "index": 0,
    "total": 3,
    "passed": true,
    "duration": 245,
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}

The status field is either "started" or "completed". The passed, duration and warnings fields are only present when status is "completed"; warnings is an array of strings and is omitted when empty.

`execution_complete`

Sent when an entire execution finishes. The result payload contains the full RunResultDTO.

{
  "type": "execution_complete",
  "payload": {
    "id": "a1b2c3d4",
    "file": "tests/api.http",
    "status": "completed",
    "result": { "file": "tests/api.http", "duration": 500, "passed": 3, "failed": 0, "skipped": 0, "results": [] },
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}

`error`

Sent when an execution fails with an error.

{
  "type": "error",
  "payload": {
    "id": "a1b2c3d4",
    "file": "tests/api.http",
    "status": "error",
    "error": "parse error: unexpected token at line 5",
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}

`environment_changed`

Sent when the active environment is switched via PUT /api/v1/environments/active.

{
  "type": "environment_changed",
  "payload": {
    "name": "staging",
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}

`file_changed`

Sent when a .http or .hitspec file is created, modified, or deleted in the workspace (via filesystem watcher).

{
  "type": "file_changed",
  "payload": {
    "path": "tests/api.http",
    "operation": "write",
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}

`stress_update`

Sent every 500ms during an active stress test with current metrics. The running and completed booleans indicate the test lifecycle — the UI uses these to detect when a test finishes naturally (without an explicit stop) and transition to the results view.

{
  "type": "stress_update",
  "payload": {
    "running": true,
    "completed": false,
    "stats": {
      "total": 750,
      "success": 745,
      "errors": 5,
      "rps": 49.8,
      "p50Ms": 12.5,
      "p95Ms": 45.2,
      "p99Ms": 120.0,
      "maxMs": 350.0,
      "errorRate": 0.0067,
      "activeVUs": 10
    },
    "elapsed": 15.3,
    "duration": 60,
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}

`mock_request`

Sent when the mock server receives a request, or when it starts/stops.

{
  "type": "mock_request",
  "payload": {
    "event": "request",
    "method": "GET",
    "path": "/users",
    "status": 200,
    "duration": 1.2,
    "timestamp": "2026-02-10T12:00:00Z"
  },
  "timestamp": "2026-02-10T12:00:00Z"
}

The event field can be "started", "stopped", or "request".

`ping` / `pong`

Clients can send {"type": "ping"} messages and the server will respond with a pong:

{
  "type": "pong",
  "payload": null,
  "timestamp": "2026-02-10T12:00:00Z"
}

Security and Request Requirements

Read-only mode

Timeouts and shutdown

Error Format

Workspace & Files

Get Workspace Overview

List Files

Get Parsed File

Get Raw File Content

Create File

Save File

Delete File

Execution

Execute Request

Run File

Environments

List Environments

Set Active Environment

Get Environment

Update Environment

Config

Get Configuration

Update Configuration

History

Get In-Memory History

Clear In-Memory History

List Persistent Runs

Get Run Details

Delete a Run

Delete All Runs

List Results by Request Name

Stress Testing

Start Stress Test

Stop Stress Test

Get Stress Test Status

Get Stress Test Result

List Stress Profiles

Create Stress Profile

Update Stress Profile

Delete Stress Profile

Mock Server

Start Mock Server

Stop Mock Server

Get Mock Routes

Contract Testing

Verify Contracts

List Contract Files

Recording Proxy

Start Recording

Stop Recording

Get Recording Status

Export Recordings

Clear Recordings

Import

Import curl

Import Insomnia

Import OpenAPI

Export

Export as curl

System

Get System Info

WebSocket

Connect

Message Envelope

Message Types

execution_start

request_progress

execution_complete

error

environment_changed

file_changed

stress_update

mock_request

ping / pong

`execution_start`

`request_progress`

`execution_complete`

`error`

`environment_changed`

`file_changed`

`stress_update`

`mock_request`

`ping` / `pong`