YAZE HTTP REST API

The YAZE HTTP REST API provides external access to YAZE functionality for automation, testing, and integration with external tools.

Getting Started

Building with HTTP API Support

The HTTP API is enabled automatically when building with AI-enabled presets:

# macOS
cmake --preset mac-ai
cmake --build --preset mac-ai --target z3ed
 
# Linux
cmake --preset lin-ai
cmake --build --preset lin-ai --target z3ed
 
# Windows
cmake --preset win-ai
cmake --build --preset win-ai --target z3ed

Or enable it explicitly with the CMake flag:

cmake -B build -DYAZE_ENABLE_HTTP_API=ON
cmake --build build --target z3ed

Running the HTTP Server

Start z3ed with the --http-port flag:

# Start on default port 8080
./build/bin/z3ed --http-port=8080
 
# Start on custom port with specific host
./build/bin/z3ed --http-port=9000 --http-host=0.0.0.0
 
# Combine with other z3ed commands
./build/bin/z3ed agent --rom=zelda3.sfc --http-port=8080

Security Note: The server defaults to localhost for safety. Only bind to 0.0.0.0 if you understand the security implications.

API Endpoints

All endpoints return JSON responses and support CORS headers.

GET /api/v1/health

Health check endpoint for monitoring server status.

Request:

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

Response:

{
  "status": "ok",
  "version": "1.0",
  "service": "yaze-agent-api"
}

Status Codes:

• 200 OK - Server is healthy

---

GET /api/v1/models

List all available AI models from all registered providers (Ollama, Gemini, etc.).

Request:

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

Response:

{
  "models": [
    {
      "name": "qwen2.5-coder:7b",
      "provider": "ollama",
      "description": "Qwen 2.5 Coder 7B model",
      "family": "qwen2.5",
      "parameter_size": "7B",
      "quantization": "Q4_0",
      "size_bytes": 4661211616,
      "is_local": true
    },
    {
      "name": "gemini-1.5-pro",
      "provider": "gemini",
      "description": "Gemini 1.5 Pro",
      "family": "gemini-1.5",
      "parameter_size": "",
      "quantization": "",
      "size_bytes": 0,
      "is_local": false
    }
  ],
  "count": 2
}

Status Codes:

• 200 OK - Models retrieved successfully
• 500 Internal Server Error - Failed to retrieve models (see error field)

Response Fields:

• name (string) - Model identifier
• provider (string) - Provider name ("ollama", "gemini", etc.)
• description (string) - Human-readable description
• family (string) - Model family/series
• parameter_size (string) - Model size (e.g., "7B", "13B")
• quantization (string) - Quantization method (e.g., "Q4_0", "Q8_0")
• size_bytes (number) - Model size in bytes
• is_local (boolean) - Whether model is hosted locally

---

Error Handling

All endpoints return standard HTTP status codes and JSON error responses:

{
  "error": "Detailed error message"
}

Common status codes:

• 200 OK - Request succeeded
• 400 Bad Request - Invalid request parameters
• 404 Not Found - Endpoint not found
• 500 Internal Server Error - Server-side error

CORS Support

All endpoints include CORS headers to allow cross-origin requests:

Access-Control-Allow-Origin: *

Implementation Details

Architecture

The HTTP API is built using:

• cpp-httplib - Header-only HTTP server library (ext/httplib/)
• nlohmann/json - JSON serialization/deserialization
• ModelRegistry - Unified model management across providers

Code Structure

src/cli/service/api/
├── http_server.h      # HttpServer class declaration
├── http_server.cc     # Server implementation and routing
├── api_handlers.h     # Endpoint handler declarations
├── api_handlers.cc    # Endpoint implementations
└── README.md          # This file

Threading Model

The HTTP server runs in a background thread, allowing z3ed to continue normal operation. The server gracefully shuts down when z3ed exits.

CMake Integration

Enable with:

option(YAZE_ENABLE_HTTP_API "Enable HTTP REST API server" ${YAZE_ENABLE_AGENT_CLI})

When enabled, adds compile definition:

#ifdef YAZE_HTTP_API_ENABLED
// HTTP API code
#endif

Testing

Manual Testing

1. Start the server:

   ./build/bin/z3ed --http-port=8080

2. Test health endpoint:

   curl http://localhost:8080/api/v1/health | jq

3. Test models endpoint:

   curl http://localhost:8080/api/v1/models | jq

Automated Testing

Use the provided test script:

scripts/agents/test-http-api.sh 8080

CI/CD Integration

The HTTP API can be tested in CI via workflow_dispatch:

gh workflow run ci.yml -f enable_http_api_tests=true

See docs/internal/agents/archive/utility-tools/gh-actions-remote.md for details.

Future Endpoints (Planned)

The following endpoints are planned for future releases:

• POST /api/v1/chat - Send prompts to AI agent
• POST /api/v1/tool/{tool_name} - Execute specific tools
• GET /api/v1/rom/status - ROM loading status
• GET /api/v1/rom/info - ROM metadata

See docs/internal/AI_API_ENHANCEMENT_HANDOFF.md for the full roadmap.

Security Considerations

• Localhost Only: Default host is localhost to prevent external access
• No Authentication: Currently no authentication mechanism (planned for future)
• CORS Enabled: Cross-origin requests allowed (may be restricted in future)
• Rate Limiting: Not implemented (planned for future)

For production use, consider:

1. Running behind a reverse proxy (nginx, Apache)
2. Adding authentication middleware
3. Implementing rate limiting
4. Restricting CORS origins

Troubleshooting

"Port already in use"

If you see Failed to listen on port, another process is using that port:

# Find the process
lsof -i :8080
 
# Use a different port
./build/bin/z3ed --http-port=9000

"Failed to start HTTP API server"

Check that:

1. The binary was built with YAZE_ENABLE_HTTP_API=ON
2. The port number is valid (1-65535)
3. You have permission to bind to the port (<1024 requires root)

Server not responding

Verify the server is running and reachable:

# Check if server is listening
netstat -an | grep 8080
 
# Test with verbose curl
curl -v http://localhost:8080/api/v1/health

Contributing

When adding new endpoints:

1. Declare handler in api_handlers.h
2. Implement handler in api_handlers.cc
3. Register route in http_server.cc::RegisterRoutes()
4. Document endpoint in this README
5. Add tests in scripts/agents/test-http-api.sh

Follow the existing handler pattern:

void HandleYourEndpoint(const httplib::Request& req, httplib::Response& res) {
  // Set CORS header
  res.set_header("Access-Control-Allow-Origin", "*");
 
  // Build JSON response
  json response;
  response["field"] = "value";
 
  // Return JSON
  res.set_content(response.dump(), "application/json");
}

License

Part of the YAZE project. See LICENSE for details.