# How to Use the CodexBar Serve HTTP API for External Integrations

> Integrate externally with CodexBar using its serve HTTP API. Query usage data and trigger refreshes via local JSON endpoints bound to localhost. Streamline your workflows today.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: how-to-guide
- Published: 2026-07-08

---

**The CodexBar serve HTTP API exposes a lightweight, loopback-only server via the `codexbar serve` command, enabling local scripts and applications to query usage data and trigger refreshes through JSON endpoints strictly bound to localhost connections.**

CodexBar ships with a built-in HTTP server designed specifically for local automation, allowing external tools to access real-time usage data without exposing sensitive information to the network. The server implementation resides in [`CLILocalHTTPServer.swift`](https://github.com/steipete/CodexBar/blob/main/CLILocalHTTPServer.swift) while the routing logic and endpoint definitions live in [`CLIServeCommand.swift`](https://github.com/steipete/CodexBar/blob/main/CLIServeCommand.swift), creating a secure bridge between the CLI and third-party integrations.

## Architecture and Security Model

The CodexBar serve HTTP API operates as a TCP socket server that defaults to `127.0.0.1:0`, automatically selecting a free ephemeral port to avoid collisions. According to the source in [`CLILocalHTTPServer.swift`](https://github.com/steipete/CodexBar/blob/main/CLILocalHTTPServer.swift), every incoming connection first undergoes validation through `CLILocalHTTPRequest.parse` before reaching the handler closure defined in [`CLIServeCommand.swift`](https://github.com/steipete/CodexBar/blob/main/CLIServeCommand.swift).

### Loopback-Only Enforcement

Security is enforced by the `isAllowedLoopbackHost` method (implemented around lines 83-110 in [`CLILocalHTTPServer.swift`](https://github.com/steipete/CodexBar/blob/main/CLILocalHTTPServer.swift)), which inspects the `Host` header of every request. This function explicitly rejects any connection that does not resolve to `127.0.0.1`, `localhost`, or `[::1]`, ensuring the API remains inaccessible from external networks regardless of firewall configuration. This design prevents accidental exposure while still allowing tunneling via SSH or reverse proxies for legitimate remote access scenarios.

## Available Endpoints

The router registered in [`CLIServeCommand.swift`](https://github.com/steipete/CodexBar/blob/main/CLIServeCommand.swift) exposes four primary JSON endpoints:

- **GET `/usage`** – Returns current provider statistics including consumed tokens, limits, and utilization percentages.
- **GET `/status`** – Provides a minimal health payload containing the provider name, version identifier, and operational flag.
- **POST `/refresh`** – Triggers an immediate synchronization with the provider API, ensuring subsequent queries return up-to-date data.
- **GET `/token`** – Exposes the current access token only when the CLI is invoked with the `--expose-token` flag, requiring explicit opt-in to prevent credential leakage.

Unit tests in [`CLIServeRouterTests.swift`](https://github.com/steipete/CodexBar/blob/main/CLIServeRouterTests.swift) validate these routes, ensuring proper HTTP method restrictions (returning **405** for invalid verbs) and correct JSON payload structures.

## Integration Steps

### 1. Start the Server

Launch the HTTP daemon as a background process:

```bash

# Auto-select a random port (recommended for CI/CD environments)

codexbar serve &

# Or bind to a specific port

codexbar serve --port 8080 &

```

When using the default port 0, the server outputs the assigned endpoint to stdout: `Codex Bar HTTP server listening on 127.0.0.1:53412`.

### 2. Discover the Port

Capture the port number from the console output or read the `CODX_BAR_HTTP_PORT` environment variable, which the CLI automatically exports for child processes.

### 3. Query from Shell Scripts

Use standard HTTP clients to retrieve data:

```bash
curl -s http://127.0.0.1:${CODX_BAR_HTTP_PORT}/usage | jq .

```

Typical response structure:

```json
{
  "provider": "OpenAI",
  "model": "gpt-4",
  "usedTokens": 12345,
  "limitTokens": 400000,
  "percentage": 3.1
}

```

### 4. Consume from Swift Applications

Implement a native client using `URLSession`:

```swift
import Foundation

struct Usage: Decodable {
    let provider: String
    let model: String
    let usedTokens: Int
    let limitTokens: Int
    let percentage: Double
}

func fetchUsage(from port: UInt16) async throws -> Usage {
    let url = URL(string: "http://127.0.0.1:\(port)/usage")!
    let (data, _) = try await URLSession.shared.data(from: url)
    return try JSONDecoder().decode(Usage.self, from: data)
}

// Usage example
let usage = try await fetchUsage(from: 8080)
print("Current utilization: \(usage.percentage)%")

```

### 5. Trigger Refresh Cycles

Force an immediate data update before querying:

```bash
curl -X POST -s http://127.0.0.1:${CODX_BAR_HTTP_PORT}/refresh

```

### 6. Shutdown Procedures

The server terminates automatically when the parent `codexbar` process exits. For programmatic control, invoke the `stop()` method on the `CLILocalHTTPServer` instance, or send `SIGINT`/`SIGTERM` to the process ID.

## Practical Automation Examples

Monitor usage in a polling loop:

```bash
#!/bin/bash
codexbar serve --port 8080 &
sleep 2

while true; do
    percentage=$(curl -s http://127.0.0.1:8080/usage | jq -r '.percentage')
    echo "Token usage: ${percentage}%"
    if (( $(echo "$percentage > 90" | bc -l) )); then
        echo "WARNING: Approaching limit"
    fi
    sleep 60
done

```

Integrate into a Swift build tool:

```swift
import Foundation

@main
struct StatusChecker {
    static func main() async throws {
        let port = UInt16(ProcessInfo.processInfo.environment["CODX_BAR_HTTP_PORT"] ?? "8080")!
        let url = URL(string: "http://127.0.0.1:\(port)/status")!
        let (data, _) = try await URLSession.shared.data(from: url)
        print(String(data: data, encoding: .utf8)!)
    }
}

```

## Summary

- **CodexBar serve HTTP API** provides a localhost-only server via `codexbar serve`, exposing usage data through JSON endpoints at `/usage`, `/status`, `/refresh`, and optionally `/token`.
- **Security is enforced** by `isAllowedLoopbackHost` in [`CLILocalHTTPServer.swift`](https://github.com/steipete/CodexBar/blob/main/CLILocalHTTPServer.swift), which rejects any non-loopback connection to prevent network exposure.
- **Integration requires** starting the server, capturing the port from stdout or the `CODX_BAR_HTTP_PORT` environment variable, and issuing standard HTTP requests to `127.0.0.1`.
- **Core implementation files** include [`CLILocalHTTPServer.swift`](https://github.com/steipete/CodexBar/blob/main/CLILocalHTTPServer.swift) for socket handling, [`CLIServeCommand.swift`](https://github.com/steipete/CodexBar/blob/main/CLIServeCommand.swift) for routing logic, and [`CLIServeRouterTests.swift`](https://github.com/steipete/CodexBar/blob/main/CLIServeRouterTests.swift) for behavior validation.

## Frequently Asked Questions

### How do I expose the CodexBar serve API to remote machines?

You cannot disable the loopback restriction; the `isAllowedLoopbackHost` check in [`CLILocalHTTPServer.swift`](https://github.com/steipete/CodexBar/blob/main/CLILocalHTTPServer.swift) explicitly blocks non-localhost addresses. For remote access, establish an SSH tunnel using `ssh -L 8080:127.0.0.1:8080 remote-host` or route traffic through a reverse proxy with authentication.

### Why does the server default to a random port?

The default configuration uses `127.0.0.1:0` to prevent port conflicts when running multiple instances or parallel CI jobs. The CLI prints the assigned port and sets the `CODX_BAR_HTTP_PORT` environment variable for easy discovery by calling scripts.

### How do I access the API token through the HTTP interface?

The `/token` endpoint is disabled by default to prevent credential leakage. Start the server with the `--expose-token` flag to enable this route, which then returns the current provider access token in the JSON response body.

### What HTTP status codes does the API return for errors?

According to [`CLIServeRouterTests.swift`](https://github.com/steipete/CodexBar/blob/main/CLIServeRouterTests.swift), the server returns **404** for undefined routes, **405** for valid paths with invalid HTTP methods (such as POST to `/usage`), and **403** for requests that fail the loopback host validation. Successful requests return **200** with JSON content.