{
  "openapi": "3.2.0",
  "info": {
    "title": "getHealth",
    "version": "1",
    "description": "Check an SWQoS edge's readiness with getHealth or the unauthenticated plain-text GET /health route."
  },
  "servers": [
    {
      "url": "https://ams.tpu.supanode.xyz"
    },
    {
      "url": "https://fra.tpu.supanode.xyz"
    },
    {
      "url": "https://la.tpu.supanode.xyz"
    },
    {
      "url": "https://lon.tpu.supanode.xyz"
    },
    {
      "url": "https://ny.tpu.supanode.xyz"
    },
    {
      "url": "https://toy.tpu.supanode.xyz"
    }
  ],
  "security": [
    {
      "apiKeyHeader": []
    },
    {
      "apiKeyQuery": []
    },
    {
      "bearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKeyHeader": {
        "$ref": "#/x-ext/b08d7c8/components/securitySchemes/apiKeyHeader"
      },
      "apiKeyQuery": {
        "$ref": "#/x-ext/b08d7c8/components/securitySchemes/apiKeyQuery"
      },
      "bearer": {
        "$ref": "#/x-ext/b08d7c8/components/securitySchemes/bearer"
      }
    }
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "getHealth",
        "summary": "getHealth",
        "description": "Check whether an SWQoS edge can currently reach upcoming leaders; readiness does not guarantee that a transaction will land. A send can still be refused, for example with `not_ready`.",
        "requestBody": {
          "required": true,
          "description": "One JSON object using the [shared request conventions](https://supanode.xyz/docs/solana/sender/reference/json-rpc#request). The method takes no params.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcVersion"
                  },
                  "id": {
                    "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcId"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "getHealth"
                    ]
                  },
                  "params": {
                    "description": "Ignored when present."
                  }
                }
              },
              "examples": {
                "Request": {
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "getHealth"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns `ok` when an SWQoS edge can currently reach upcoming leaders; readiness does not guarantee that a transaction will land. A send can still be refused, for example with `not_ready`.\n\nRefusals with HTTP 200, by `error.data.reason`:\n\n- [`invalid_request`](https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request): invalid JSON-RPC body, unreadable body or request body timeout.\n- [`too_large`](https://supanode.xyz/docs/solana/sender/reference/errors#too_large): request body exceeds 65,536 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "jsonrpc",
                        "result",
                        "id"
                      ],
                      "properties": {
                        "jsonrpc": {
                          "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcVersion"
                        },
                        "result": {
                          "type": "string",
                          "enum": [
                            "ok"
                          ]
                        },
                        "id": {
                          "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcId"
                        }
                      },
                      "additionalProperties": false
                    },
                    {
                      "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcErrorEnvelope"
                    }
                  ]
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "value": {
                      "jsonrpc": "2.0",
                      "result": "ok",
                      "id": 1
                    }
                  },
                  "ParseError": {
                    "$ref": "#/x-ext/b08d7c8/components/examples/ParseError"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/x-ext/b08d7c8/components/responses/Unauthorized"
          },
          "421": {
            "$ref": "#/x-ext/b08d7c8/components/responses/MisdirectedRequest"
          },
          "503": {
            "description": "The edge is not ready. Returns JSON-RPC code `-32005` and message `Node is unhealthy`, without a `data` member.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "jsonrpc",
                    "error",
                    "id"
                  ],
                  "properties": {
                    "jsonrpc": {
                      "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcVersion"
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "integer",
                          "enum": [
                            -32005
                          ]
                        },
                        "message": {
                          "type": "string",
                          "enum": [
                            "Node is unhealthy"
                          ]
                        }
                      },
                      "additionalProperties": false
                    },
                    "id": {
                      "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcId"
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "Unhealthy": {
                    "value": {
                      "jsonrpc": "2.0",
                      "error": {
                        "code": -32005,
                        "message": "Node is unhealthy"
                      },
                      "id": 1
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "rust",
            "id": "rust",
            "label": "Rust",
            "source": "// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\nuse swqos_examples::swqos::{Result, SwqosError, call};\n\n#[tokio::main]\nasync fn main() -> Result<()> {\n    match call::<String>(\"getHealth\", None).await {\n        Ok(health) => println!(\"health {health}\"),\n        Err(error) => {\n            if error\n                .downcast_ref::<SwqosError>()\n                .is_some_and(|error| error.code == -32005)\n            {\n                println!(\"edge not ready\");\n            } else {\n                return Err(error);\n            }\n        }\n    }\n    let slot: u64 = call(\"getSlot\", None).await?;\n    println!(\"slot {slot}\");\n    Ok(())\n}"
          },
          {
            "lang": "go",
            "id": "go",
            "label": "Go",
            "source": "// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\npackage swqos\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n)\n\nfunc PrintHealth(ctx context.Context) error {\n\thealth, err := Call[string](ctx, \"getHealth\")\n\tif err != nil {\n\t\tvar refusal *SwqosError\n\t\tif !errors.As(err, &refusal) || refusal.Code != -32005 {\n\t\t\treturn err\n\t\t}\n\t\tfmt.Println(\"edge not ready\")\n\t} else {\n\t\tfmt.Println(\"health\", health)\n\t}\n\tslot, err := Call[uint64](ctx, \"getSlot\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tfmt.Println(\"slot\", slot)\n\treturn nil\n}"
          },
          {
            "lang": "ts",
            "id": "ts",
            "label": "TypeScript",
            "source": "// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\nimport { call, SwqosError } from './swqos.ts'\n\ntry {\n  console.log('health', await call<string>('getHealth'))\n} catch (error) {\n  if (error instanceof SwqosError && error.code === -32005) console.log('edge not ready')\n  else throw error\n}\nconsole.log('slot', await call<number>('getSlot'))"
          }
        ]
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealthRoute",
        "summary": "Check health",
        "security": [],
        "description": "Check whether an SWQoS edge can currently reach upcoming leaders; readiness does not guarantee that a transaction will land. A send can still be refused, for example with `not_ready`. No API key is required. The route returns plain text and uses the same test as getHealth.",
        "responses": {
          "200": {
            "description": "Returns `ok` as plain text when an SWQoS edge can currently reach upcoming leaders; readiness does not guarantee that a transaction will land. A send can still be refused, for example with `not_ready`. No API key is required.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "ok"
                  ]
                },
                "examples": {
                  "Ready": {
                    "value": "ok"
                  }
                }
              }
            }
          },
          "421": {
            "$ref": "#/x-ext/b08d7c8/components/responses/MisdirectedRequest"
          },
          "503": {
            "description": "Returns `unhealthy` as plain text when the edge is not ready, using the same readiness test as [getHealth](https://supanode.xyz/docs/solana/sender/reference/json-rpc/health).",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "unhealthy"
                  ]
                },
                "examples": {
                  "Unhealthy": {
                    "value": "unhealthy"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "rust",
            "id": "rust",
            "label": "Rust",
            "source": "// src/bin/http_health.rs\n// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\nuse swqos_examples::swqos::Result;\n\n#[tokio::main]\nasync fn main() -> Result<()> {\n    let base = std::env::var(\"SWQOS_URL\").unwrap_or_else(|_| \"https://fra.tpu.supanode.xyz\".into());\n    let mut endpoint = reqwest::Url::parse(&base)?;\n    endpoint.set_path(\"/health\");\n    endpoint.set_query(None);\n    // This route does not require an API key.\n    let response = reqwest::Client::new().get(endpoint).send().await?;\n    let status = response.status();\n    let body = response.text().await?;\n    if !status.is_success() {\n        return Err(format!(\"HTTP {status}: {body}\").into());\n    }\n    println!(\"{body}\");\n    Ok(())\n}"
          },
          {
            "lang": "go",
            "id": "go",
            "label": "Go",
            "source": "// http_health/main.go\npackage main\n\nimport (\n    \"fmt\"\n    \"io\"\n    \"net/http\"\n    \"net/url\"\n    \"os\"\n)\n\nfunc run() error {\n    base := os.Getenv(\"SWQOS_URL\")\n    if base == \"\" {\n        base = \"https://fra.tpu.supanode.xyz\"\n    }\n    endpoint, err := url.Parse(base)\n    if err != nil {\n        return err\n    }\n    endpoint.Path = \"/health\"\n    endpoint.RawQuery = \"\"\n    // This route does not require an API key.\n    response, err := http.Get(endpoint.String())\n    if err != nil {\n        return err\n    }\n    defer response.Body.Close()\n    body, err := io.ReadAll(response.Body)\n    if err != nil {\n        return err\n    }\n    if response.StatusCode < 200 || response.StatusCode >= 300 {\n        return fmt.Errorf(\"HTTP %d: %s\", response.StatusCode, body)\n    }\n    fmt.Println(string(body))\n    return nil\n}\n\nfunc main() {\n    if err := run(); err != nil {\n        fmt.Fprintln(os.Stderr, err)\n        os.Exit(1)\n    }\n}"
          },
          {
            "lang": "ts",
            "id": "ts",
            "label": "TypeScript",
            "source": "// http-health.ts\nexport {}\n\nconst endpoint = new URL('/health', process.env.SWQOS_URL ?? 'https://fra.tpu.supanode.xyz')\n// This route does not require an API key.\nconst response = await fetch(endpoint)\nconst body = await response.text()\nif (!response.ok) throw new Error(`HTTP ${response.status}: ${body}`)\nconsole.log(body)"
          }
        ]
      }
    }
  },
  "x-ext": {
    "b08d7c8": {
      "components": {
        "schemas": {
          "Rejection": {
            "type": "object",
            "required": [
              "reason",
              "message",
              "retryable"
            ],
            "properties": {
              "reason": {
                "type": "string",
                "description": "Stable snake_case reason. Match on this; `message` wording can change, and the numeric codes are shared with Solana's RPC.",
                "examples": [
                  "missing_tip"
                ]
              },
              "message": {
                "type": "string",
                "description": "What happened and what to change. Wording can change.",
                "examples": [
                  "tip too small: the tip transfers add up to 123 lamports, the minimum is 1,000,000; raise the transfer to one of the tip accounts to at least 1,000,000 lamports"
                ]
              },
              "retryable": {
                "type": "boolean",
                "description": "Whether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.",
                "examples": [
                  false
                ]
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "Optional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.",
                "examples": [
                  "https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip"
                ]
              }
            },
            "additionalProperties": true,
            "description": "Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.",
            "examples": [
              {
                "reason": "missing_tip",
                "minimum": 1000000,
                "found": 123,
                "message": "tip too small: the tip transfers add up to 123 lamports, the minimum is 1,000,000; raise the transfer to one of the tip accounts to at least 1,000,000 lamports",
                "retryable": false,
                "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip"
              }
            ]
          },
          "JsonRpcVersion": {
            "type": "string",
            "enum": [
              "2.0"
            ],
            "examples": [
              "2.0"
            ]
          },
          "JsonRpcError": {
            "type": "object",
            "required": [
              "code",
              "message",
              "data"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "enum": [
                  -32700,
                  -32600,
                  -32601,
                  -32602,
                  -32603,
                  -32000,
                  -32001,
                  -32002,
                  -32003
                ],
                "description": "[Status codes](https://supanode.xyz/docs/solana/sender/reference/json-rpc#status-codes) maps reasons and problems to codes. Match on `data.reason`.",
                "examples": [
                  -32602
                ]
              },
              "message": {
                "type": "string",
                "description": "The same sentence as data.message."
              },
              "data": {
                "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
              }
            },
            "additionalProperties": false
          },
          "JsonRpcId": {
            "type": [
              "string",
              "number",
              "null"
            ],
            "description": "Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read.",
            "examples": [
              1,
              "request-1",
              null
            ]
          },
          "JsonRpcErrorEnvelope": {
            "type": "object",
            "required": [
              "jsonrpc",
              "error",
              "id"
            ],
            "properties": {
              "jsonrpc": {
                "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcVersion"
              },
              "error": {
                "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcError"
              },
              "id": {
                "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcId"
              }
            },
            "additionalProperties": false
          }
        },
        "securitySchemes": {
          "apiKeyHeader": {
            "type": "apiKey",
            "in": "header",
            "name": "x-api-key",
            "description": "Send the SWQoS API key in this header. See the [authentication reference](https://supanode.xyz/docs/solana/sender/reference/json-rpc#authentication) for compatibility forms and precedence."
          },
          "apiKeyQuery": {
            "type": "apiKey",
            "in": "query",
            "name": "api-key",
            "description": "Compatibility authentication. See the [authentication reference](https://supanode.xyz/docs/solana/sender/reference/json-rpc#authentication) for precedence and the URL logging warning. Prefer x-api-key."
          },
          "bearer": {
            "type": "http",
            "scheme": "bearer",
            "description": "SWQoS API key sent as Authorization: Bearer YOUR_KEY. The prefix `Bearer ` is case-sensitive. Prefer x-api-key. See the [authentication reference](https://supanode.xyz/docs/solana/sender/reference/json-rpc#authentication) for precedence."
          }
        },
        "examples": {
          "ParseError": {
            "summary": "Invalid JSON",
            "value": {
              "jsonrpc": "2.0",
              "error": {
                "code": -32700,
                "message": "the body is not valid JSON",
                "data": {
                  "reason": "invalid_request",
                  "problem": "parse_error",
                  "message": "the body is not valid JSON",
                  "retryable": false,
                  "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request"
                }
              },
              "id": null
            }
          }
        },
        "responses": {
          "Unauthorized": {
            "description": "[`unauthorized`](https://supanode.xyz/docs/solana/sender/reference/errors#unauthorized): missing, unknown or revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcErrorEnvelope"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "jsonrpc": "2.0",
                      "error": {
                        "code": -32000,
                        "message": "API key missing or not recognized; pass it as the api-key query parameter, an x-api-key header or Authorization: Bearer",
                        "data": {
                          "reason": "unauthorized",
                          "message": "API key missing or not recognized; pass it as the api-key query parameter, an x-api-key header or Authorization: Bearer",
                          "retryable": false,
                          "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#unauthorized"
                        }
                      },
                      "id": null
                    }
                  }
                }
              }
            }
          },
          "MisdirectedRequest": {
            "description": "Unknown or removed TLS SNI or HTTP Host/:authority. Returns plain text without a JSON-RPC envelope or rejection object. The current hostname policy also applies to existing connections and resumed TLS sessions.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "UnknownHost": {
                    "value": "This hostname is not served here. Check the endpoint address"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
