DocsHTTP API

Keep & automate

Akev HTTP API (v1)

The Akev daemon (akev CLI or the desktop app) serves this API, the live event stream, the MCP endpoint and the web UI from one localhost port (default 45456).

All JSON uses camelCase field names; enums use kebab-case strings. Types referenced as ExchangeSummary, ExchangeDetail, RuleSet, Settings, InterceptorInfo, ... are defined in crates/akev-core/src/*.rs (the UI mirrors them in ui/src/api/types.ts).

Authentication

Every /api/* and /mcp request must carry the session token, by either of:

  • Authorization: Bearer <token> (preferred)
  • ?token=<token> query parameter (for downloads & the WebSocket, where headers can't be set)
  • ?ticket=<ticket> for one download: POST /api/download-ticket with {"path": "/api/export/har"} returns {"ticket", "expiresInMs"}, a ticket valid for a single GET of that path (any query) within 60 seconds. The UI uses it for browser downloads so the token never lands in download history.

The token is never accepted from a cookie. Cookies are not isolated by port, so a cookie for 127.0.0.1 would be sent to every other service on that host (dev servers, containers, other users' apps, Akev's own proxy port, which would record it).

Opening the UI. GET /?token=<token> with the valid token serves the UI itself (Cache-Control: no-store, Referrer-Policy: no-referrer). The UI keeps the token in port-isolated web storage, removes it from the address bar and sends it as a Bearer header. A wrong token redirects to / without it. akev start never passes this URL on a command line, because other local users can read process arguments (/proc/<pid>/cmdline). Instead it writes a redirect page, open-ui.html (mode 0600), into the data directory and opens that file. The page is removed when the daemon stops. If the browser can't read the data directory (some snap or flatpak browsers), open the printed Web UI link, or the one from akev status.

Requests with a browser Origin header are rejected unless the origin is the API's own origin or explicitly allowed (--allow-origin). Embedders can also allow the Tauri webview origins (AkevOptions::allow_tauri_origins, off by default; the desktop app loads the UI from the API's own origin). This blocks drive-by attacks from web pages against the local API. On a loopback bind, GET / and static UI assets are public (they contain no data).

Network-exposed API (--api-bind not a loopback address):

  • Other machines reach the UI and the API over HTTPS only, with a certificate from Akev's own CA for the bind address, localhost, the loopback addresses, the computer's name (and <name>.local) and its network addresses; it is re-issued when the CA is regenerated. The akev start banner and akev status print this https:// address (Status.networkUrl). A device that sends plain HTTP gets a short answer pointing to https://. Plain HTTP stays for this machine itself, so the CLI, akev mcp and the desktop app keep using http://127.0.0.1:<port>.

  • The static UI requires authentication too. GET /?token= also sets a UI-only session cookie, akev_ui_<port> (HttpOnly; SameSite=Strict). It holds a separate random secret that only unlocks the static UI, never /api or /mcp.

  • A custom token (--token / AKEV_TOKEN) must be at least 24 characters and not repetitive. Startup fails otherwise. Generated tokens are 256-bit random.

  • A non-loopback peer that presents 20 distinct wrong credentials within a minute gets 429 (with Retry-After) until the minute ends, even for a correct token. Retrying the same stale token, or sending no credential, doesn't count. Loopback peers are never throttled.

Debug request logs (-vv) never record the value of a token query parameter.

Errors: non-2xx with {"error": {"code": "not-found", "message": "..."}}. Using a Pro feature without a licence or trial answers 402 with the code pro-required (see Licence).

Status & lifecycle

Method Path Body Response
GET /api/status – Status
POST /api/shutdown – 204
ts
interface Status {
  version: string;
  proxy: {
    port: number; bindAddress: string /* in effect, incl. --proxy-bind */; addresses: string[] /* host:port reachable addresses incl. LAN IPs */;
    http3: { enabled: boolean; address?: string /* UDP ip:port when listening */; port?: number; error?: string /* why it isn't listening although enabled, e.g. the UDP port is taken */ };
  };
  apiUrl: string;
  dataDir: string;
  ca: CaInfo;                 // akev-ca CaInfo
  startedAt: number;          // unix ms
  stats: { exchanges: number; memoryBodyBytes: number; spilledBodyBytes: number; activeConnections: number; totalConnections: number };
  platform: "linux" | "macos" | "windows";
  desktop: boolean;           // running inside the desktop shell
  restoredSession?: { id: string; name: string; exchanges: number; savedAt: number /* unix ms */ }; // the autosave restored at startup, once loaded
  license: LicenseStatus;     // plan, trial and licence key (see Licence)
}

Licence

Akev Pro is unlocked by a licence key or the trial; see licensing. The key is verified offline and stored in <data dir>/license.json (not in Settings, and not in a Settings export).

Method Path Body Response
GET /api/license – LicenseStatus
PUT /api/license { key: string } ("AKEV1.…") LicenseStatus, or 400 invalid-license
DELETE /api/license – LicenseStatus (the stored key is removed)
POST /api/license/trial – LicenseStatus (trial started), or 409 trial-unavailable
ts
interface LicenseStatus {
  plan: "free" | "pro";
  state: "none" | "trial" | "trial-ended" | "active" | "updates-ended" | "invalid";
  features: Feature[];          // the Pro features enabled now
  license?: {                   // the key's contents, when there is one
    id: string;
    email: string;
    name?: string;
    issued: string;             // YYYY-MM-DD
    updatesUntil: string;       // YYYY-MM-DD
  };
  trialEndsAt?: number;         // unix ms, while a trial runs or after it ended
  trialAvailable: boolean;      // POST /api/license/trial would start one
  error?: string;               // why the key is invalid
  releaseDate: string;          // YYYY-MM-DD, this build's release date
}

type Feature =
  | "scripting" | "tls-impersonation" | "wireguard" | "transparent"
  | "jvm-attach" | "proto-schemas" | "llm-lens" | "mcp-write";
state plan Meaning
none free No key, no trial
trial pro The trial runs until trialEndsAt
trial-ended free The trial is over and there is no key
active pro A valid key that covers this build
updates-ended free A valid key, but this build was released after updatesUntil: use an older build or renew
invalid free The key doesn't verify; error says why

Changes are broadcast on the live stream as { type: "license", license: LicenseStatus }.

Pro required. Endpoints that start or use a Pro feature answer, without a licence or trial:

http
HTTP/1.1 402 Payment Required
Content-Type: application/json

{"error": {"code": "pro-required", "message": "…", "feature": "wireguard"}}

feature is one of the Feature ids. Nothing stored is deleted without a licence: rules with a Pro action (which stay editable), WireGuard and transparent capture settings and protobuf schemas are kept, they just don't take effect. MCP tools that need Pro return a tool error naming the feature.

Exchanges (captured traffic)

Method Path Body / Query Response
GET /api/exchanges ?filter=<query>&limit=<n> ExchangeSummary[] (id order)
GET /api/exchanges/:id – ExchangeDetail
GET /api/exchanges/:id/body/:side side = request/response; ?original=1 pre-modification body BodyView (see below)
GET /api/exchanges/:id/body/:side/raw ?decoded=1 (remove content-encoding) &download=1 (Content-Disposition attachment, filename derived from URL) raw bytes with the exchange's Content-Type
GET /api/exchanges/:id/messages ?after=<seq> StreamMessageWithPayload[]
POST /api/exchanges/:id/messages InjectMessage — inject into a live WebSocket (see WebSocket tools) 202 { seq: number | null }
GET /api/exchanges/:id/llm – LlmExchange — the conversation view of an LLM API call (see LLM conversations); 404 not-llm for other exchanges
GET /api/exchanges/:id/snippet ?target=curl { target, language, code }
POST /api/exchanges/headers { ids: number[], request?: string[], response?: string[] } (up to 5,000 ids and 32 header names per side) { exchanges: { id, request: Record<string,string>, response: Record<string,string> }[] } — the chosen headers' values, names lowercase, repeated headers joined with ", "; unknown ids are left out. The traffic list's header columns use it.
POST /api/exchanges/timings { ids: number[] } (up to 5,000) { timings: ({ id } & Timing)[] } — each exchange's phase timings, as in ExchangeDetail.timing; unknown ids are left out. The timeline uses it.
POST /api/exchanges/delete { ids: number[] } 204
POST /api/exchanges/clear { keepPinned?: boolean } 204
PATCH /api/exchanges { ids: number[], pinned?: boolean, color?: string | null, note?: string | null } 204
POST /api/exchanges/:id/replay { request?: EditableRequest, options?: SendOptions } (omitted request = resend as captured) SendResult & { body: BodyView, recorded: boolean } (see Compose)
GET /api/exchanges/:id/editable/:side – EditableRequest / EditableResponse (decoded body, base64) — used to open a captured request in Compose
ts
interface BodyView {
  kind: ContentKind;           // "json" | "html" | "image" | ...
  size: number;                // decoded size
  wireSize: number;
  encodings: string[];         // content-encoding chain
  text: string | null;         // decoded text (null if binary or decode failed)
  formatted: string | null;    // pretty-printed text where applicable
  structured: any | null;      // protobuf/grpc/msgpack/cbor → JSON, multipart parts, SSE events, form fields, image info
  decodeError: string | null;
  truncated: boolean;          // text truncated for transport (> 8 MB); use /raw for full
  captureTruncated: boolean;   // the proxy only captured a prefix of the body
  structuredTruncated?: true;  // `structured` holds only the first part (decode size limits); omitted when false
  schema?: SchemaInfo;         // an imported protobuf schema decoded the body (see "Protobuf schemas"); omitted otherwise
}
interface StreamMessageWithPayload extends StreamMessage {
  text: string | null;         // UTF-8 payload if text
  base64: string | null;       // payload when binary
}

ExchangeDetail.upstream.fingerprint (TLS upstream connections; omitted otherwise) is the ClientHello — and HTTP/2 preface — Akev itself presented to the server, recorded from the bytes actually sent (see Upstream TLS fingerprints):

ts
interface UpstreamFingerprint {
  profile: "native" | "chrome" | "firefox" | "safari" | "edge"; // what was used
  requested?: string;    // what was asked for when different: "mirror-client", or a browser profile in a build without the backend
  note?: string;         // why `requested` wasn't used as is
  ja3?: string;          // md5 hex of ja3Text
  ja3Text?: string;      // "771,4865-4866-...,0-23-65281-...,4588-29-23-24,0" (Chrome's changes per connection: it shuffles extensions)
  ja4?: string;          // e.g. "t13d1516h2_8daaf6152771_d8a2da3f94cd"
  http2?: string;        // Akamai format "SETTINGS|WINDOW_UPDATE|PRIORITY frames|pseudo-header order", HTTP/2 connections only
}

ExchangeDetail.upstream.chain (TLS upstream connections; omitted for exchanges recorded by earlier versions) is every certificate the server presented and what Akev's trust decision rested on. It is filled once per connection and shared by the exchanges that reuse it:

ts
interface CertificateChain {
  certificates: CertificateSummary[];  // as the server sent them, the leaf first
  trust: {
    status: "verified" | "not-verified" | "unknown";
      // verified: up to a trusted root; not-verified: certificate errors are ignored for this
      // host (settings) or this request (Compose); unknown: the handshake succeeded but the
      // path couldn't be rebuilt to report it
    path: number[];                      // indices into certificates of the verified path, leaf first
    anchor?: {                           // the trusted root the path ends at
      subject: string;
      index?: number;                    // set when the server sent the root itself
      source: "built-in" | "system" | "custom"; // Mozilla's roots built into Akev, the OS store, or a trusted CA file
    };
  };
}

Certificates the server sent that aren't on path (old cross-signs, duplicates) weren't used.

For gRPC / gRPC-Web, structured is { messages: GrpcMessage[], error?: string } with GrpcMessage = { compressed, decoded /* schemaless */, trailers, size }. When a schema applies, each message also carries typed (the typed decode) and unknownFields?: string[], or typedError: string when it doesn't fit the schema.

LLM conversations

Calls to LLM APIs are recognised when they are captured: OpenAI Chat Completions, legacy Completions and Responses (OpenAI, Azure OpenAI and every OpenAI-compatible server — OpenRouter, Groq, Mistral, DeepSeek, xAI, Together, Fireworks, Perplexity, Ollama, vLLM, LM Studio…), Anthropic Messages (also Claude on Vertex AI), Google Gemini generateContent / streamGenerateContent (AI Studio and Vertex AI) and Ollama's native /api/chat and /api/generate. Well-known provider hosts are recognised by URL; other hosts also need a request body of the API's shape. Such exchanges carry llm on their ExchangeSummary:

ts
interface ExchangeSummary {
  // …
  llm?: { provider: string; model?: string };   // provider id + requested model
}

and the filter language has is:llm, model: and provider:. GET /api/exchanges/:id/llm normalises the call across providers. Streamed responses (SSE deltas, Anthropic content-block events, Responses API events, Gemini SSE / JSON-array streams, Ollama NDJSON) are reassembled into the final message(s). Malformed or truncated bodies never fail the request: what could be read is returned and warnings says what couldn't.

ts
interface LlmExchange {
  provider: string;             // "openai" | "anthropic" | "google" | "vertex-ai" | "azure-openai" | "openrouter" | "groq" | "mistral"
                                // | "deepseek" | "xai" | "together" | "fireworks" | "perplexity" | "cerebras" | "huggingface"
                                // | "ollama" | "lmstudio" | "openai-compatible" | "anthropic-compatible"
  api: "openai-chat" | "openai-completions" | "openai-responses" | "anthropic-messages" | "gemini" | "ollama-chat" | "ollama-generate";
  model?: string;               // the model that answered (response), else the one requested
  stream: boolean;
  request: {
    system?: string;            // system prompt / instructions (several blocks joined by blank lines)
    messages: LlmMessage[];
    tools: { name: string; description?: string; schema?: any /* JSON Schema */; kind?: string /* built-in tool type */ }[];
    params: Record<string, any>;// every other request field under the provider's own name (temperature, max_tokens,
                                // thinking, tool_choice, response_format…); Gemini generationConfig and Ollama options flattened
  };
  response?: {                  // absent while waiting, or when the API returned an error
    id?: string;
    model?: string;
    messages: LlmMessage[];     // usually one assistant message (one per choice when n > 1)
    stopReason?: string;        // provider wording: "stop", "end_turn", "tool_use", "tool_calls", "length", "STOP"…
    usage?: {
      inputTokens?: number;     // all prompt tokens, cached included (Anthropic: input + cache reads + cache writes)
      outputTokens?: number;    // reasoning included (Gemini: candidates + thoughts)
      totalTokens?: number;
      cacheReadTokens?: number;
      cacheWriteTokens?: number;
      reasoningTokens?: number;
    };
  };
  timing: {                     // ms, measured from the request being sent upstream
    ttftMs?: number;            // first stream event carrying generated content (from the recorded SSE timestamps)
    totalMs?: number;           // until the response was complete
    tokensPerSecond?: number;   // output tokens / s after the first token (whole duration when not streamed; Ollama's own figure)
    chunks?: number;            // stream events the response arrived in
  };
  error?: { status?: number; kind?: string; code?: string; message: string }; // HTTP error body or stream error event
  warnings?: string[];          // e.g. "The stream ended before its final event: the response may be incomplete"
}
interface LlmMessage {
  role: string;                 // "system" | "developer" | "user" | "assistant" | "tool" (Gemini "model" → "assistant")
  name?: string;
  content: LlmPart[];
}
type LlmPart =
  | { type: "text"; text: string }
  | { type: "image"; mediaType?: string; data?: string /* base64, ≤ 8 MiB */; url?: string; size?: number /* bytes */ }
  | { type: "file"; label: "document" | "audio" | "file"; mediaType?: string; name?: string; url?: string; size?: number }
  | { type: "tool-call"; id?: string; name: string; arguments: any /* parsed JSON; the raw string when invalid */ }
  | { type: "tool-result"; id?: string; name?: string; content: LlmPart[]; isError?: true }
  | { type: "thinking"; text: string; redacted?: true }
  | { type: "refusal"; text: string }
  | { type: "other"; label: string; value: any };  // blocks Akev doesn't model (built-in tool results…)

Absent optional fields are omitted. For agents, the MCP tool akev_llm_conversation returns the same object with long texts cut and inline image data left out.

Filter language

Method Path Body Response
POST /api/filter/validate { query } { ok: true } | { ok: false, error: { message, start, end } }
POST /api/filter/suggest { query, cursor } Suggestion[]
POST /api/filter/query { query } { ids: number[] }
GET /api/filter/docs – FieldDoc[]

Rules

Method Path Body Response
GET /api/rules – RuleSet
PUT /api/rules RuleSet { errors: [ruleId, message][] } (applied immediately & persisted; compiling runs script rules' top-level code, up to 0.5 s each)
GET /api/rules/stats – RuleStats[]
POST /api/rules/stats/reset – RuleStats[] (counters zeroed, match limits re-armed)
POST /api/rules/test { exchangeId } or { request: EditableRequest } + optional { rules: RuleSet, runScripts?: boolean (default true) } { matched: RuleId[], terminalRule: RuleId | null, action: Action, scriptLogs?: string[], error?: string, scriptOutcome?: { kind: "continue", method, url, headers, body, response?: {status, headers, body} } | { kind: "respond", response } } (dry run; matching script rules are executed in the sandbox against the request and the captured response)
GET /api/rules/export – RuleSet as attachment akev-rules.json
POST /api/rules/import RuleSet or HTTP Toolkit rules export JSON RuleSet (converted; not applied)

The modifier action { type: "tls-profile", profile: TlsProfile } makes matching requests present that TLS fingerprint upstream, overriding proxy.tlsProfile (the last matching tls-profile rule wins; later rules still run). See Upstream TLS fingerprints.

Breakpoints

Method Path Body Response
GET /api/breakpoints – PausedExchange[]
POST /api/breakpoints/:id/resume RequestResume (request stage) or ResponseResume (response stage) 204
POST /api/breakpoints/resume-all – 204 (continue all unchanged; also forwards every paused WebSocket message)
GET /api/breakpoints/messages – PausedMessage[] (WebSocket messages paused at ws-breakpoint rules)
POST /api/breakpoints/messages/:pauseId/resume MessageResume 204
POST /api/breakpoints/messages/resume-all { id?: number, action?: "forward" | "drop" } (only exchange id's messages; default forward) { resumed: number }
ts
interface PausedExchange {
  id: number;                       // the exchange id
  stage: "request" | "response";
  pausedAt: number;                 // unix µs, when it started waiting
  request: EditableRequest;         // as received (request stage) or as sent upstream (response stage)
  response?: EditableResponse;      // response stage only
}

Breakpoints hold matching traffic even when it isn't recorded (recording paused, or capture.ignoreHosts matches the host): such an exchange is in /api/breakpoints but not in /api/exchanges, so clients should show and resume it from this snapshot.

WebSocket tools

Injecting messages. POST /api/exchanges/:id/messages writes a message into a live intercepted WebSocket, as if one of the peers had sent it:

ts
interface InjectMessage {
  direction: "sent" | "received";   // "sent" = to the server (masked like a client frame), "received" = to the client
  kind?: "text" | "binary";         // default: "text" with `text`, "binary" with `base64`
  text?: string;                    // UTF-8 payload…
  base64?: string;                  // …or raw bytes (exactly one of text / base64; text kind must be valid UTF-8)
}

The message goes out as soon as that direction is between messages (never inside a frame or a fragmented message) and is recorded like any other message, with modified: true. The response comes once it was written: 202 { seq } (its StreamMessage.seq), or 202 { seq: null } after 2 s when it is still queued behind a long message. Errors: 404 unknown exchange, 409 not an open intercepted WebSocket (closed, not a WebSocket, or sent on a ws-echo connection, which has no server), 400 invalid body (max 16 MiB), 429 when 64 messages are already queued.

Message breakpoints. A rule with the modifier action { type: "ws-breakpoint", direction: "sent" | "received" | "both", pattern?: StringMatch } pauses the text/binary messages of the WebSockets it matches. Such rules only match WebSocket upgrade requests (once per connection: that is what maxMatches and the hit counter count). pattern is tested against the payload as UTF-8 (binary lossily); without it every message is paused. The rule is looked up again for every message, so disabling, deleting or editing it applies to connections that are already open. Messages larger than 4 MiB are never paused.

A paused message holds back only its own direction, and only its data: pings and pongs still pass (so keep-alive timeouts don't fire) and the other direction keeps flowing. What arrives behind it waits in order (up to 4 MiB, then the sender is no longer read). When either peer disconnects, or the other direction ends, the pause is abandoned: the message is delivered as received and the connection stops pausing. Paused messages appear on the stream (message-paused / message-resumed) and in hello.pausedMessages.

ts
interface PausedMessage {
  id: number;                       // the WebSocket exchange
  pauseId: number;                  // resume with this id
  direction: "sent" | "received";
  kind: "text" | "binary";
  payload: string;                  // complete payload, base64
  at: number;                       // unix µs
  rule: string;                     // the ws-breakpoint rule
}
type MessageResume =
  | { action: "forward"; kind?: "text" | "binary"; text?: string; base64?: string } // no payload = unchanged (original framing kept)
  | { action: "drop" };            // never delivered, not recorded

An edited message is sent as one frame and recorded with modified: true. Errors: 404 not paused (anymore), 400 invalid payload.

Compose (send requests)

Method Path Body Response
POST /api/send { request: EditableRequest, options?: SendOptions } SendResult & { body: BodyView, recorded: boolean }
POST /api/send/repeat { request?: EditableRequest, exchangeId?: number, options?: SendOptions, count: number, concurrency?: number, delayMs?: number } NDJSON stream, one line per finished request, then { done: true, sent } (see below)
POST /api/import/curl { command } EditableRequest
GET /api/codegen/targets – TargetInfo[]
POST /api/codegen { request: EditableRequest, target } { target, language, code }

Repeat (POST /api/send/repeat) sends one request count times (at most 10,000), with up to concurrency requests in flight (default 1, at most 64); each worker pauses delayMs (at most 60,000) between its requests. Give request, or exchangeId to resend a captured request as it was. The response streams one JSON line per finished request, in the order they finish:

json
{"index":0,"id":812,"status":200,"durationMs":41.7}
{"index":2,"id":814,"error":"timeout","durationMs":60000}
{"done":true,"sent":3}

index is the request's place in the run, id the exchange it made (in the traffic list unless recording is paused), status or error (an error kind such as timeout or connection-refused) the outcome, and durationMs the time to the end of the response body or the failure. Closing the connection stops the run, in-flight requests included.

recorded tells whether exchange id was stored in the traffic list. It is false while recording is paused (PUT /api/capture) or when the capture settings ignore the host. The id then can't be opened (/api/exchanges/:id answers 404).

ts
interface SendOptions {           // all optional
  applyRules: boolean;            // false — run through the user's rules
  followRedirects: boolean;       // false — each hop is recorded
  timeoutMs: number;              // 60000 — response head timeout; 0 = the proxy settings' default
  insecure: boolean;              // false — ignore upstream certificate errors
  httpVersion: "auto" | "http1" | "http2" | "http3"; // "auto"
}

httpVersion: auto lets the settings decide (HTTP/2 via ALPN, HTTP/3 per proxy.http3.upstream); http1 never negotiates HTTP/2; http2 stays on TCP (HTTP/2 when the server offers it, else HTTP/1.1) and never uses HTTP/3; http3 tries HTTP/3 over QUIC first whatever the settings say and falls back to TCP when the QUIC connection can't be established (like curl --http3). HTTP/3 only applies to https:// URLs, never through an upstream proxy. The response's httpVersion (and the recorded exchange's, for Compose / Repeat) is the one actually used.

Interceptors

Method Path Body Response
GET /api/interceptors – InterceptorInfo[]
POST /api/interceptors/:id/activate { options?: any } ActivationResult
POST /api/interceptors/:id/deactivate { options?: any } 204
GET /api/setup/terminal ?shell=bash|zsh|fish|powershell|cmd text/plain script for an already open terminal (see below)

activate passes options to the interceptor. electron starts the executable at options.path with options.args, so the token grants running programs as the user. Over MCP this is refused unless the user opted in (see MCP).

JVM attach

jvm attaches the Akev Java agent to a running JVM (guide). GET /api/interceptors → metadata:

ts
{
  processes: {
    pid: number; name: string;            // short name: "Main", "app.jar"
    mainClass: string;                    // main class, -jar path or module/class ("" if unknown)
    commandLine: string; javaVersion: string | null; javaHome: string | null;
    attached: boolean;                    // the agent routes this JVM to an Akev proxy…
    active: boolean;                      // …this one (attachedPort = this proxy's port)
    attachedPort: number | null; attachedAt: number | null; interceptLoopback: boolean | null;
  }[];
  discovery: "jps" | "process-table";     // how JVMs were found (process table without jps)
  jps: string | null; jpsError: string | null;
  java: string | null;                    // first Java that will run the attacher
  notes: string[];                        // what is / isn't intercepted
}

activate options: { pid: number, interceptLoopback?: boolean (false), proxyProperties?: "auto" | "always" | "never" }. Only JVMs listed in processes can be attached to. On success metadata is { pid, name, java, agent }, agent being the agent's report: proxy, proxySelector, defaultSslContext, httpsUrlConnection (installed), existingDefaultContext (patched or unchanged: <reason>), trustStore (temporary store path or unchanged: <reason>), proxyProperties (set or skipped: <reason>), okhttp (loaded OkHttp client classes), warnings[], agentVersion, javaVersion, javaVendor, javaHome. Failures (not attachable, Attach API missing, agent error) return { success: false, message }. deactivate with { pid } restores that JVM (also one attached by an earlier Akev run), without options every attached JVM; restoring fails with 500 if the agent can't restore a live JVM. Shutting the daemon down restores every attached JVM.

The existing terminal one-liner fetches the setup script. It sends the token in a header read from curl's config on stdin (-K -), never in the URL. Process arguments, including curl's URL, are visible to other local users, and printf is a shell builtin, so it spawns no process:

sh
# bash / zsh
eval "$(printf '%s\n' 'header = "Authorization: Bearer <token>"' | curl -sS --noproxy '*' -K - 'http://127.0.0.1:45456/api/setup/terminal?shell=bash')"
# fish
printf '%s\n' 'header = "Authorization: Bearer <token>"' | curl -sS --noproxy '*' -K - 'http://127.0.0.1:45456/api/setup/terminal?shell=fish' | source

PowerShell downloads the script in-process with the token as a request header, so neither appears in a process list:

powershell
iex (& { $c = New-Object Net.WebClient -Property @{Proxy=$null}; $c.Headers['Authorization'] = 'Bearer <token>'; $c.DownloadString('http://127.0.0.1:45456/api/setup/terminal?shell=powershell') })

cmd writes the curl config to %TEMP%\akev-curl.cfg with the echo builtin (a pipe would run it in a child cmd.exe), runs curl with -K on it, deletes it, then calls the downloaded script. The daemon's interceptor metadata (GET /api/interceptors, existing-terminal → metadata.shells.<shell>.command) carries the ready-made one-liners. ?token= keeps working for clients that can't set headers.

Transparent capture (Linux)

A second listener (settings.proxy.transparent, off by default) accepts connections the firewall redirected to Akev (nftables / iptables REDIRECT). Each connection's original destination is read from conntrack (SO_ORIGINAL_DST / IP6T_SO_ORIGINAL_DST) and handled like a CONNECT tunnel to it: TLS is intercepted by SNI (or passed through), HTTP is parsed, other protocols are piped through. Exchanges get client.via: "transparent". Akev never runs firewall commands; it generates them. Guide: guide/transparent.md.

Method Path Body Response
GET /api/transparent – TransparentInfo — listener status, redirect check, system facts
POST /api/transparent/plan TransparentPlanRequest TransparentPlan — the commands (400 with a message for invalid options, e.g. an unknown user)
ts
interface TransparentSettings {      // settings.proxy.transparent (all optional)
  enabled: boolean;                  // false
  port: number;                      // 8001 — next free port (up to +100) when busy; 0 = any
  mark: number;                      // 0 — SO_MARK on Akev's upstream sockets (needs CAP_NET_ADMIN)
}
interface TransparentInfo {
  supported: boolean;                // Linux
  unsupportedReason?: string;
  active: boolean;                   // a redirected connection arrived in the last 10 minutes
  listener: TransparentStatus;
  system: { platform: string; uid?: number; user?: string; cgroupV2: boolean; ownCgroup?: string;
            userManagerCgroup?: string; nft: boolean; iptables: boolean; systemdRun: boolean; executable?: string };
  slice: "akev-capture.slice";
}
interface TransparentStatus {
  enabled: boolean; supported: boolean; listening: boolean;
  port?: number; requestedPort: number; addresses: string[];   // e.g. ["127.0.0.1:8001", "[::1]:8001"]
  error?: string;                    // why it isn't listening
  mark: number; markError?: string;  // e.g. missing CAP_NET_ADMIN
  connections: number;               // accepted on the transparent port
  redirected: number;                // ...with an original destination
  direct: number;                    // ...made to the port directly (handled by Host / SNI)
  loops: number;                     // Akev's own connections sent back by the rules (refused)
  lastRedirectAt?: number;           // unix ms
  recent: { at: number; client: string; originalDestination?: string; process?: string }[];  // newest first, ≤ 20
}
interface TransparentPlanRequest {   // all optional, defaults first
  mode?: "app" | "user" | "machine";
  ports?: "web" | "all" | "custom";  // web = 80 + 443
  customPorts?: number[];
  backend?: "nft" | "iptables";
  command?: string;                  // app: what to launch (default: a captured "$SHELL")
  user?: string;                     // user: name or uid (must not be Akev's own, unless a mark is set)
  exclude?: "uid" | "mark";          // machine: how Akev's own traffic is kept out
  launcher?: "systemd" | "cgroupfs"; // app: systemd user slice, or a hand-made cgroup
  excludeDestinations?: string[];    // IPs / CIDRs never redirected (loopback never is)
  trustCa?: boolean;                 // true — app: CA trust variables on the launch command
  sudo?: boolean;                    // true — prefix root commands with sudo
}
interface TransparentStep { title: string; command: string; root: boolean; description?: string }
interface TransparentPlan {
  mode: string; backend: string; port: number; summary: string;
  setup: TransparentStep[];          // run in order
  launch?: TransparentStep;          // app mode
  test: TransparentStep;             // prints 200 when redirection reaches Akev
  teardown: TransparentStep[];
  rules: string;                     // the nft ruleset / iptables commands alone
  warnings: string[]; notes: string[];
}

The transparent-linux interceptor (Linux only, needsConfig) exposes the same thing to the catalogue and MCP: info.metadata = { listener, system, slice }, active = the redirect check above, and activate with a TransparentPlanRequest as options returns the plan as metadata. deactivate fails with the teardown command: removing firewall rules needs root.

The listener binds 127.0.0.1 and ::1 (locally redirected connections arrive there) plus the proxy's bind address. PUT /api/settings applies changes immediately and rejects transparent.port equal to proxy.port while enabled.

Settings & certificate

Method Path Body Response
GET /api/settings – Settings
PUT /api/settings Settings Settings (applied live; port / bind address changes rebind the proxy, see below)
PATCH /api/settings/ui any JSON 204 (replaces settings.ui)
GET /api/ca – CaInfo
GET /api/ca/cert.pem – PEM (application/x-pem-file, attachment akev-ca.pem)
GET /api/ca/cert.der – DER (application/x-x509-ca-cert, attachment akev-ca.crt)
POST /api/ca/regenerate – CaInfo (the proxy restarts on its current port and bind address)

--proxy-port / --proxy-bind apply to the current run only. They are never written to settings.json, so GET /api/settings keeps returning the stored values, while Status.proxy reports the live ones. PUT /api/settings moves the proxy only for listener fields that differ from the stored settings. A field sent back unchanged keeps its live value. For example, toggling proxy.bindAddress keeps the port the proxy listens on now, even if that port came from --proxy-port or a fallback.

To move the proxy to the stored port anyway (after a busy-port fallback, or to drop a --proxy-port / --proxy-bind override for the rest of the run), use the explicit rebind:

Method Path Body Response
POST /api/proxy/rebind { port: number, bindAddress?: string } (default: the bind address in effect) Status["proxy"] — 400 invalid port/address, 409 when that exact port is in use (the proxy stays where it was; it never falls back to another port here)

It always rebinds and doesn't change settings.json; the new address becomes the preferred one for the run (CA regeneration restarts the proxy there).

Settings.proxy.http3 (all optional, defaults shown) — HTTP/3 over QUIC, applied live:

ts
interface Http3Settings {
  upstream: "off" | "alt-svc" | "prefer"; // "off" — when requests to HTTPS servers use HTTP/3:
                                          // never; for origins that advertised `Alt-Svc: h3=...`
                                          // (cached for its `ma`); or first for every HTTPS origin.
                                          // A failed QUIC connection always falls back to TCP.
  listen: boolean;                        // false — accept HTTP/3 from clients on a QUIC (UDP) listener
  listenPort: number;                     // 0 — its UDP port; 0 = the proxy's port number
}

The listener binds proxy.bindAddress and follows rebinds when listenPort is 0. Its state is in Status.proxy.http3; a UDP port that can't be bound is reported there (error) instead of failing the settings update, and a port in use is retried for a few seconds (and on every later settings change). See the HTTP/3 guide.

Settings.sessions (all optional, defaults shown) controls autosave, see Sessions:

ts
interface SessionSettings {
  autosave: boolean;              // false — save traffic to the "Autosave" session periodically and on shutdown
  autosaveIntervalSecs: number;   // 60 (1–86400) — only when the traffic changed since the last autosave
  restoreOnStartup: boolean;      // true — load the autosave back at startup (only while autosave is on)
  autosaveMaxExchanges: number;   // 100000 — newest exchanges kept (pinned always kept); 0 = unlimited
  autosaveMaxBytes: number;       // 1073741824 — captured body bytes kept, newest first; 0 = unlimited
}

Upstream TLS fingerprints

Method Path Body Response
GET /api/tls-profiles – TlsProfiles — the profiles and whether this build can present browser fingerprints
ts
type TlsProfile = "native" | "chrome" | "firefox" | "safari" | "edge" | "mirror-client";

// Settings.proxy.tlsProfile (defaults shown). Unknown profile names read as "native".
interface TlsProfileSettings {
  profile: TlsProfile;                                  // "native"
  overrides: { host: string; profile: TlsProfile }[];   // [] — host globs ("*.example.com", "host:8443"); first match wins; empty hosts → 400
}

interface TlsProfiles {
  available: boolean;          // browser profiles work in this build (cargo feature `impersonate`)
  backend?: "BoringSSL";       // when compiled in
  profiles: {
    id: TlsProfile;
    label: string;
    description: string;
    imitates?: string;         // e.g. "Chrome 133+ (desktop)"
    ja4?: string;              // expected JA4 with h2 offered
    http2?: string;            // Akamai HTTP/2 fingerprint
    available: boolean;
  }[];
}

Precedence per request: a matching tls-profile rule, then the first matching override, then profile. mirror-client uses the intercepted client's browser family — from its ClientHello's JA4 (cipher hash), refined by its User-Agent (Edge shares Chrome's TLS stack), or the User-Agent alone for plain-HTTP clients — and native for clients that aren't a recognised browser. In builds without the backend every profile falls back to native and UpstreamFingerprint.note says so. Profiles only change TLS and HTTP/2 framing: request headers are forwarded as the client sent them. TLS to HTTPS upstream proxies always uses the native stack. Changing the setting doesn't drop pooled connections (the fingerprint is part of the pool key).

Import / export

Method Path Body Response
GET /api/export/har ?ids=1,2,3 (optional) &filter= &redact=1 HAR JSON attachment, streamed (chunked, no Content-Length; constant memory). redact=1 replaces secrets with [redacted] (what is redacted)
POST /api/import/har HAR bytes { ids: number[] }
GET /api/export/session ?ids= optional, &redact=1 .akev file attachment
POST /api/import/session .akev bytes { ids: number[] }
POST /api/import/charles Charles JSON session (.chlsj) bytes { ids: number[] } (400 with a reason when it isn't one)
POST /api/import/mitmproxy mitmproxy flow file bytes (mitmdump -w, mitmweb Save) { ids: number[] } (HTTP & WebSocket flows; TCP/UDP/DNS flows are skipped)
POST /api/import/fiddler Fiddler session archive (.saz) bytes, from Fiddler Classic or Fiddler Everywhere { ids: number[] } (400 with a reason when it can't be read, or is password-protected)

Charles: bodies Charles decoded ("decoded": true) are stored decoded with their Content-Encoding removed; FAILED / incomplete transactions import as aborted with the error mapped to an error kind; CONNECT transactions without SSL proxying become tunnel rows; WebSocket messages, notes, TLS and timing details are kept. mitmproxy: raw (still encoded) bodies, WebSocket messages, client/server TLS & addresses, connection timings, comment → note and marked → colour tag.

Sessions

Named sessions saved in the data directory (sessions/<id>.akev, the native session format, plus a small <id>.json sidecar). Writes stream from the store to a temp file and replace the target atomically, so a crash never leaves a half-written session.

Method Path Body Response
GET /api/sessions – SessionInfo[] (most recently updated first)
POST /api/sessions { name, ids?: number[], filter?: string } (all traffic, or the ids and/or the filter's matches) SessionInfo
GET /api/sessions/:id – the .akev file (attachment named after the session, streamed, not re-compressed)
PUT /api/sessions/:id { name } SessionInfo (renaming an autosave keeps it as a saved session with a new id)
DELETE /api/sessions/:id – 204
POST /api/sessions/:id/open { mode: "replace" | "append" } (default replace) { ids: number[] } — replace removes all current traffic (pinned too) after the session validated
ts
interface SessionInfo {
  id: string;                 // stable, file-safe slug of the first name: "checkout-bug", "checkout-bug-2", "autosave"
  name: string;               // 1–200 characters, no control characters
  kind: "saved" | "autosave";
  exchanges: number;
  size: number;               // file size in bytes
  createdAt: number;          // unix ms
  updatedAt: number;          // unix ms of the last content write
}

Errors: 404 unknown id, 400 invalid name, 422 invalid-session when a session file is corrupt. .akev files copied into the directory by hand are listed too.

Autosave (settings.sessions.autosave): every autosaveIntervalSecs while the traffic changed, and once more on graceful shutdown, the traffic is written to the autosave session (newest exchanges within the autosave bounds, pinned ones always). It runs on a background thread and never blocks capture. The first autosave of a run keeps the previous run's autosave as autosave-previous ("Autosave (previous run)") unless it was restored. With restoreOnStartup, the autosave is loaded in the background at startup; its exchanges get ids reserved before the proxy starts, so they sort before anything captured meanwhile. When it's loaded, Status.restoredSession describes it and stream clients get session-restored.

WireGuard mode

An embedded WireGuard server (UDP, userspace): devices that import its client configuration (QR code in the official WireGuard apps) send all their TCP traffic through the proxy, served as if it arrived in a CONNECT tunnel to the original destination. Their exchanges have client.via = "wireguard" and client.interceptor = "wireguard" (source:wireguard). Guide: guide/wireguard.md.

Method Path Body Response
GET /api/wireguard ?host= (optional endpoint host for config) WireguardInfo — 400 for an invalid host
PUT /api/wireguard { enabled?: boolean, port?: number (1–65535), bindAddress?: string | null } WireguardInfo (changes settings.proxy.wireguard: persisted, applied live, broadcast as settings)
POST /api/wireguard/regenerate – WireguardInfo — new server and client keys; configurations handed out before stop working; a running server restarts with them
GET /api/wireguard/config ?host= the client configuration, text/plain attachment akev.conf

The wireguard interceptor (GET /api/interceptors, category mobile, needsConfig: true) reflects the same server: activate / deactivate switch settings.proxy.wireguard.enabled.

settings.proxy.wireguard (all optional, defaults shown):

ts
interface WireguardSettings {
  enabled: boolean;      // false
  port: number;          // 51820 (UDP)
  bindAddress?: string;  // absent = all interfaces (0.0.0.0); "::" = dual-stack
}

A server that can't start (e.g. the port is in use) doesn't fail the settings change: the settings are the desired state, WireguardInfo.error says why it isn't running (and a notice is broadcast). It is retried when the settings change again and at the next start.

ts
interface WireguardInfo {
  enabled: boolean;
  running: boolean;
  port: number;              // in the configuration: the bound port while running
  bindAddress?: string;
  listenAddr?: string;       // "0.0.0.0:51820" while running
  error?: string;            // why it isn't running although enabled
  endpoints: string[];       // LAN addresses devices can use (the bind address if specific)
  endpoint: string;          // "host:port" written into config
  config: string;            // [Interface] PrivateKey, Address = 10.0.0.2/32, DNS = 10.0.0.53
                             // [Peer] PublicKey, AllowedIPs = 0.0.0.0/0, ::/0, Endpoint
  qrPayload: string;         // what to encode in the QR code (= config)
  configFileName: "akev.conf";
  serverPublicKey: string;   // base64
  clientAddress: "10.0.0.2/32";
  dnsAddress: "10.0.0.53";
  keysCreatedAt: number;     // unix ms
  peer: WireguardPeer;
  stats?: {                  // while running
    listenAddr: string; peer: WireguardPeer;
    tcpActive: number; tcpTotal: number; tcpRejected: number;   // connections handed to the proxy
    dnsQueries: number; udpFlows: number; udpRelayed: number;
    quicDropped: number; droppedPackets: number;
  };
}

interface WireguardPeer {
  publicKey: string;         // the client's
  endpoint?: string;         // where its packets come from
  lastHandshakeAt?: number;  // unix ms (current session)
  lastSeenAt?: number;       // unix ms (last authenticated packet)
  rxBytes: number;           // IP bytes received from the device
  txBytes: number;           // IP bytes sent to it
  connected: boolean;        // a session younger than WireGuard's 3-minute lifetime
}

Keys are stored in wireguard.json in the data directory (mode 0600 on Unix). Inside the tunnel, 10.0.0.53 answers DNS over UDP and TCP (resolved on the Akev machine; akev.cert → 10.0.0.1, where the proxy serves its setup page), UDP 443 (QUIC) is dropped, other UDP is relayed and ICMP is dropped.

Protobuf schemas

.proto files and descriptor sets the user imported. They are compiled at runtime (protox) into one descriptor pool and used to decode protobuf, gRPC and gRPC-Web bodies with names (body views of exchanges, Compose / replay responses, MCP akev_get_exchange). Stored in the data directory under protos/ (in memory only for --ephemeral sessions).

Method Path Body / Query Response
GET /api/protos – ProtoRegistry
POST /api/protos JSON { files: { name, content?: string, base64?: string }[] } (exactly one of content / base64 per file), or the raw bytes of one file with ?name= ProtoRegistry (files added or replaced by name; files that don't compile are kept with their errors)
DELETE /api/protos ?name=<name> (one file) or ?all=1 (every file; mappings are kept) ProtoRegistry
GET /api/protos/file ?name=<name> the file as uploaded (text/plain for .proto, application/octet-stream otherwise)
GET /api/protos/mappings – ProtoMapping[]
PUT /api/protos/mappings ProtoMapping[] ProtoMapping[] (validated, trimmed, ids filled in)

Names are relative paths (shop/v1/catalog.proto: letters, digits, . _ - + @, / separators; no .. or hidden segments). Names ending in .proto are source text (UTF-8), any other name is a serialized google.protobuf.FileDescriptorSet (.desc, .pb, .binpb, .protoset). Limits: 16 MB per file, 2000 files, 128 MB in total. Invalid uploads and mappings answer 400, unknown names 404.

Imports resolve by exact name, then — when exactly one stored file fits — by path suffix or file name (the file is then compiled under the imported name, reported as importName). The well-known google/protobuf/*.proto files are built in; files of uploaded descriptor sets can be imported too.

ts
interface ProtoRegistry {
  files: ProtoFileInfo[];
  mappings: ProtoMapping[];
  messageTypes: string[];          // every message type the files define, sorted
}
interface ProtoFileInfo {
  name: string;
  kind: "proto" | "descriptor-set";
  size: number;
  addedAt: number;                 // unix ms
  importName?: string;             // compiled under this name (imports refer to it so)
  package?: string;
  contains?: string[];             // descriptor sets: the .proto files inside (google/protobuf/* left out)
  services: { name: string; methods: { name: string; path: string /* /pkg.Service/Method */; inputType: string; outputType: string; clientStreaming: boolean; serverStreaming: boolean }[] }[];
  messages: string[];              // fully-qualified, nested included, map entries excluded
  enums: string[];
  errors: ProtoError[];            // empty = compiled
}
interface ProtoError { file: string; line: number | null; column: number | null /* 1-based */; message: string }
interface ProtoMapping {
  id: string;                      // generated when empty
  enabled: boolean;                // default true
  pattern: string;                 // see below
  side: "request" | "response" | "both";   // default "both"
  messageType: string;             // "shop.v1.Item" (a leading "." is dropped)
}
interface SchemaInfo {             // BodyView.schema
  messageType: string;
  source: "grpc" | "content-type" | "mapping";
  method?: { service: string; method: string; inputType: string; outputType: string; clientStreaming: boolean; serverStreaming: boolean };
  mapping?: string;                // the matching mapping's pattern
  typed?: any;                     // protobuf bodies: the typed decode (gRPC: per message in `structured`)
  error?: string;                  // didn't decode with the schema (gRPC: no message did); `structured` keeps the schemaless decode
  unknownFields?: string[];        // field paths on the wire the schema doesn't define ("21", "items.9")
}

Choosing the message type of a body — the first that applies:

  1. a messageType=, proto= or message= parameter of the body's Content-Type (application/x-protobuf; messageType="shop.v1.Item"); with encoding=delimited the body is a sequence of varint length-prefixed messages and typed is an array;
  2. gRPC / gRPC-Web content (application/grpc*): the last two path segments name package.Service/Method; requests decode as its input type, responses as its output type;
  3. the first enabled mapping whose side includes the body and whose pattern matches the request URL, when the schemas define its type.

Mapping patterns: * matches any characters (/ included), case-insensitive. A pattern starting with / matches the path, one containing :// the whole URL, one with a / the host (:port when not the default) plus path, and one without / the host. Path and URL patterns match with or without the query string.

Typed decoding applies to protobuf, gRPC and gRPC-Web bodies, and (content-type and mapping plans only) to binary or unclassified bodies, which become protobuf views (kind: "protobuf") when they decode. JSON-coded gRPC (application/grpc+json) is never decoded with a schema. The typed form is the proto3 JSON mapping with field names as declared in the .proto, enum value names (numbers when unknown), 64-bit integers as JSON numbers, bytes as base64, map entries sorted by key and the well-known types in their JSON form; fields the schema doesn't define stay, schemaless, under their numbers. It has its own output budget (the limits of structured); a decode that would exceed it reports error: "too large to decode with the schema (output limit reached)".

Live stream — GET /api/stream (WebSocket)

Auth via ?token=. Server → client JSON messages:

ts
type ServerMessage =
  | { type: "hello"; status: Status; summaries: ExchangeSummary[]; paused: PausedExchange[]; rules: RuleSet; settings: Settings }
  | { type: "exchanges"; added: ExchangeSummary[]; updated: ExchangeSummary[] }   // batched, max ~30/s
  | { type: "removed"; ids: number[] }
  | { type: "cleared" }
  | { type: "messages"; id: number; messages: StreamMessage[] }                   // new WS/SSE messages (no payload)
  | { type: "paused"; exchange: PausedExchange }
  | { type: "resumed"; id: number }
  | { type: "message-paused"; message: PausedMessage }                            // WebSocket message paused at a ws-breakpoint
  | { type: "message-resumed"; id: number; pauseId: number }                      // forwarded, dropped or abandoned
  | { type: "rules"; rules: RuleSet }                                              // rules changed elsewhere
  | { type: "rule-stats"; stats: RuleStats[] }                                     // at most 2/s
  | { type: "settings"; settings: Settings }
  | { type: "interceptors"; interceptors: InterceptorInfo[] }                      // when activation state changes
  | { type: "stats"; stats: Status["stats"] }                                      // every 2s
  | { type: "notice"; level: "info" | "warning" | "error"; message: string }       // e.g. CA expiring
  | { type: "capture"; recording: boolean }
  | { type: "license"; license: LicenseStatus }                                    // licence or trial changed
  | { type: "session-restored"; session: { id: string; name: string; exchanges: number; savedAt: number } } // autosave restored at startup
  | { type: "filter-result"; seq: number; query: string; ids: number[] | null; error?: { message: string; start: number; end: number } }
  | { type: "pong" };
// `exchanges` messages additionally carry `filtered?: { add: number[]; remove: number[] }` once a filter is set.
// `hello` also carries `pausedMessages: PausedMessage[]` (see WebSocket tools); its `status.license` is the licence state.

Client → server:

ts
type ClientMessage =
  | { type: "ping" }                                  // server replies { type: "pong" }
  | { type: "set-filter"; query: string; seq: number } // server-side filtering for this connection

Server-side filtering: after set-filter, the server replies { type: "filter-result", seq, query, ids: number[] | null, error?: { message, start, end } } (ids: null = matches everything) and from then on every exchanges batch carries filtered: { add: number[], remove: number[] } — ids that started/stopped matching this connection's filter (computed on add and on every update, since e.g. status: only matches once the response arrives). removed/cleared apply to the filtered set implicitly. An invalid query keeps the previous filter and returns error.

Within one exchanges batch, an id appears at most once (in added if new since last batch, else in updated with the latest summary).

Recording

Method Path Body Response
GET /api/capture – { recording: boolean }
PUT /api/capture { recording: boolean } { recording } — when false, traffic is still proxied (and rules applied) but not stored. Broadcast as { type: "capture", recording } on the stream.

MCP — POST /mcp (Streamable HTTP, JSON-RPC 2.0)

Model Context Protocol server so AI agents can inspect and change traffic, with the same Authorization: Bearer <token> as the rest of the API. The tools, their arguments and which need Pro are listed in MCP for AI agents; setting up Claude Code, Claude Desktop, Cursor and VS Code is in Set up your client.

  • akev_send_request takes the Compose options (httpVersion: auto | http1 | http2 | http3, see SendOptions). Results carry recorded: false (and a note) when the exchange wasn't stored.
  • akev_llm_conversation { id, maxTextChars? } returns the LLM conversation of an LLM API call (texts cut to maxTextChars, default 20000; inline image data left out). List rows of akev_list_exchanges carry llm: { provider, model }; filter with is:llm.
  • Tools that launch or reconfigure programs, replace rules or clear traffic (akev_activate_interceptor, akev_set_rules, akev_clear_traffic) are annotated destructiveHint: true; clients that honour it ask the user first. electron (an arbitrary executable with arbitrary arguments) is refused over MCP unless Akev runs with akev start --mcp-allow-launch (or akev mcp --allow-launch for an embedded instance; AkevOptions::mcp_allow_launch). Agents read captured traffic, which attackers can influence, so a prompt injection must not be able to start programs. The UI and REST API are not affected.

Tools that change something — akev_send_request, akev_replay, akev_set_rules, akev_add_mock, akev_resume_breakpoint, akev_set_recording, akev_clear_traffic and akev_activate_interceptor — need the Pro feature mcp-write, and akev_llm_conversation needs llm-lens. Without it they return a tool error naming the feature. The read tools are free and unlimited. See MCP.

akev mcp (stdio) bridges stdio JSON-RPC to this endpoint for MCP clients that spawn processes (Claude Code, Cursor, etc.).

Device setup (served by the proxy port)

Requests through the proxy to http://akev.cert/ (or directly to http://<proxy-ip>:<port>/) return a mobile-friendly setup page with CA download links (/ca.pem, /ca.crt, /ca.mobileconfig for iOS) and instructions. No auth (CA certs are public).

Type to search guides, the CLI and the API.