GraphQL API

Hugin exposes a GraphQL API primarily used by the desktop UI. It provides richer querying capabilities than the REST API for flow data – multi-field filtering, sorting, pagination, and real-time subscriptions are all available in a single interface.

🔗Endpoint

POST /graphql     Execute queries and mutations
GET  /graphql     GraphQL Playground (interactive browser IDE)

The GraphQL Playground is accessible at http://127.0.0.1:8081/graphql in a browser when the API server is running.

🔗Schema

The schema is built with async-graphql and provides queries, mutations, and subscriptions.

🔗Queries

flows – List flows with filtering, sorting, and pagination.

query {
  flows(filter: {
    host: "example.com"
    method: "POST"
    statusCode: 200
    flagged: true
    limit: 50
    offset: 0
    sortBy: "created_at"
    sortOrder: "desc"
    createdAfter: "2026-03-01T00:00:00Z"
    minStatus: 200
    maxStatus: 299
    hasParams: true
    contentType: "application/json"
    tag: "auth"
  }) {
    flows {
      id
      method
      url
      host
      status
      contentType
      size
      latency
      flagged
      createdAt
    }
    total
    limit
    offset
    hasMore
  }
}

Filter fields:

• method – Filter by HTTP method
• host – Filter by hostname
• urlContains – Substring match on URL
• statusCode – Exact status code match
• flagged – Boolean filter for flagged flows
• projectId – Filter by project UUID
• limit – Results per page (default: 100)
• offset – Pagination offset (default: 0)
• sortBy – Sort column: created_at, method, host, status, latency, size
• sortOrder – asc or desc (default: desc)
• createdAfter – ISO 8601 timestamp lower bound
• createdBefore – ISO 8601 timestamp upper bound
• minStatus / maxStatus – Status code range
• minLatencyMs – Minimum response latency in milliseconds
• hasParams – Only flows whose URL contains ?
• contentType – Content-Type LIKE match
• tag – Flow must have this specific tag

flow – Get a single flow by ID.

query {
  flow(id: "a3f2e1d0-...") {
    id
    method
    url
    host
    status
    requestHeaders
    responseHeaders
    requestBody
    responseBody
    latency
    flagged
    annotations
    createdAt
  }
}

stats – Proxy statistics.

query {
  stats {
    totalFlows
    uniqueHosts
    totalSize
  }
}

🔗Mutations

annotateFlow – Flag, unflag, comment, or delete a flow.

mutation {
  annotateFlow(id: "a3f2...", action: FLAG, comment: "Interesting endpoint") {
    id
    flagged
  }
}

deleteFlow – Delete a flow by ID.

mutation {
  deleteFlow(id: "a3f2...") {
    success
  }
}

🔗Subscriptions

flowUpdates – Real-time stream of new flows as they are captured by the proxy.

subscription {
  flowUpdates {
    id
    method
    url
    host
    status
    latency
    createdAt
  }
}

This subscription uses WebSocket transport (graphql-ws protocol). Connect to ws://127.0.0.1:8081/graphql with the graphql-transport-ws subprotocol.

🔗Usage with curl

# Query flows
curl -X POST http://127.0.0.1:8081/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ flows(filter: { host: \"example.com\", limit: 10 }) { flows { id method url status } total } }"}'

# Get stats
curl -X POST http://127.0.0.1:8081/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ stats { totalFlows uniqueHosts } }"}'

🔗Usage from JavaScript

const response = await fetch('http://127.0.0.1:8081/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `
      query($host: String) {
        flows(filter: { host: $host, limit: 20 }) {
          flows { id method url status latency }
          total hasMore
        }
      }
    `,
    variables: { host: 'api.example.com' }
  })
});
const { data } = await response.json();

🔗Authentication

When API authentication is enabled, include credentials in the request:

# Bearer token
curl -X POST http://host:8081/graphql \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ stats { totalFlows } }"}'

# Basic Auth
curl -X POST http://host:8081/graphql \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ stats { totalFlows } }"}'

🔗REST vs GraphQL

The REST API and GraphQL API share the same underlying data store and service layer. Choose based on your use case:

• REST: Simple CRUD, automation scripts, CI/CD integration, shell scripting
• GraphQL: Complex queries with multiple filters, real-time subscriptions, UI integration, when you need precise control over returned fields