{
  "openapi": "3.1.0",
  "info": {
    "title": "GitHound Customer API",
    "version": "1.0.0",
    "description": "Read-only literal search of indexed public GitHub code. Pro or eligible trial/grant required. Server-to-server bearer authentication; Origin headers and CORS are unsupported. UI session endpoints are excluded. Audited against deployed implementation on 2026-11-05."
  },
  "servers": [
    {
      "url": "https://githoundexplore.com"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/workspaces": {
      "get": {
        "operationId": "listWorkspaces",
        "summary": "List owned workspaces",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "Opaque next_cursor from the previous page. No other query parameters are accepted."
          }
        ],
        "responses": {
          "400": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "Bearer"
              }
            }
          },
          "403": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Delay in seconds; daily-quota exhaustion requires the UTC reset or an allowance change."
              }
            }
          },
          "503": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "200": {
            "description": "Owned workspaces. This call does not create a workspace.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspacePage"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workspaces/{workspace_id}/code-search/stream": {
      "post": {
        "operationId": "searchCodeStream",
        "summary": "Stream a literal GitHub code search",
        "description": "Only query is accepted. Leading/trailing whitespace is trimmed; trimmed length must be 1\u20132048 characters. Whole JSON body max 4096 bytes with known Content-Length. No query parameters. 100 hits / 45s / 1MiB max. UI and API daily usage shared; retry starts a new search.",
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Owned workspace ID."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Literal query; trimmed length 1\u20132048 characters."
                  }
                }
              },
              "example": {
                "query": "example.com"
              }
            }
          }
        },
        "responses": {
          "400": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "Bearer"
              }
            }
          },
          "403": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Delay in seconds; daily-quota exhaustion requires the UTC reset or an allowance change."
              }
            }
          },
          "503": {
            "description": "Request rejected before streaming. See the error code and HTTP status. Framework/proxy failures can use another response format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "200": {
            "description": "SSE stream, NOT a JSON array. Parse event/data frames incrementally. One start, zero or more hit/progress, and terminal done or error. EOF without a terminal event is incomplete. Event payload schemas are provided in components; x-sse-events maps event names to payloads.",
            "headers": {
              "X-Search-API-Version": {
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              }
            },
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "example": "event: progress\ndata: {\"elapsed_ms\":1000}\n\n",
                "x-sse-events": {
                  "start": {
                    "$ref": "#/components/schemas/StartEvent"
                  },
                  "hit": {
                    "$ref": "#/components/schemas/HitEvent"
                  },
                  "progress": {
                    "$ref": "#/components/schemas/ProgressEvent"
                  },
                  "done": {
                    "$ref": "#/components/schemas/DoneEvent"
                  },
                  "error": {
                    "$ref": "#/components/schemas/StreamErrorEvent"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account API key with search:read scope."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "Coverage": {
        "type": "object",
        "required": [
          "live_commit_history_included",
          "partial",
          "historical_snapshots",
          "current_head_complete",
          "deleted_or_superseded_content_may_be_present"
        ],
        "properties": {
          "live_commit_history_included": {
            "type": "boolean"
          },
          "partial": {
            "type": "boolean"
          },
          "historical_snapshots": {
            "type": "boolean"
          },
          "current_head_complete": {
            "type": "boolean"
          },
          "deleted_or_superseded_content_may_be_present": {
            "type": "boolean"
          }
        }
      },
      "WorkspacePage": {
        "type": "object",
        "required": [
          "workspaces",
          "next_cursor"
        ],
        "properties": {
          "workspaces": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "required": [
                "id",
                "name"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                }
              }
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128,
            "description": "Opaque account-bound cursor, valid for 24 hours."
          }
        }
      },
      "StartEvent": {
        "type": "object",
        "required": [
          "api_version",
          "source",
          "query_mode",
          "coverage",
          "limits"
        ],
        "properties": {
          "api_version": {
            "const": 1
          },
          "source": {
            "const": "github"
          },
          "query_mode": {
            "const": "literal"
          },
          "coverage": {
            "$ref": "#/components/schemas/Coverage"
          },
          "limits": {
            "type": "object",
            "required": [
              "max_hits",
              "max_runtime_seconds",
              "max_frame_bytes",
              "max_output_bytes"
            ],
            "properties": {
              "max_hits": {
                "const": 100
              },
              "max_runtime_seconds": {
                "const": 45
              },
              "max_frame_bytes": {
                "const": 65536
              },
              "max_output_bytes": {
                "const": 1048576
              }
            }
          }
        }
      },
      "HitEvent": {
        "type": "object",
        "required": [
          "source",
          "kind",
          "id",
          "repository",
          "path",
          "commit",
          "extension",
          "bytes",
          "snippet",
          "match"
        ],
        "properties": {
          "source": {
            "const": "github"
          },
          "kind": {
            "const": "file"
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "repository": {
            "type": "string",
            "maxLength": 201,
            "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
          },
          "path": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16384
          },
          "commit": {
            "type": "string",
            "pattern": "^[a-fA-F0-9]{40}$"
          },
          "extension": {
            "type": "string",
            "maxLength": 64
          },
          "bytes": {
            "type": "integer",
            "minimum": 0,
            "maximum": 18446744073709551615
          },
          "snippet": {
            "type": "string",
            "maxLength": 600
          },
          "match": {
            "type": "string",
            "maxLength": 256
          }
        }
      },
      "ProgressEvent": {
        "type": "object",
        "required": [
          "elapsed_ms"
        ],
        "properties": {
          "elapsed_ms": {
            "type": "integer",
            "minimum": 0,
            "maximum": 50000
          }
        }
      },
      "DoneEvent": {
        "type": "object",
        "required": [
          "status",
          "count",
          "limited",
          "partial",
          "coverage"
        ],
        "properties": {
          "status": {
            "enum": [
              "complete",
              "limited",
              "paused"
            ]
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "limited": {
            "type": "boolean"
          },
          "partial": {
            "type": "boolean"
          },
          "coverage": {
            "$ref": "#/components/schemas/Coverage"
          }
        }
      },
      "StreamErrorEvent": {
        "type": "object",
        "required": [
          "code",
          "partial",
          "count",
          "coverage"
        ],
        "properties": {
          "code": {
            "const": "search_unavailable"
          },
          "partial": {
            "const": true
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "coverage": {
            "$ref": "#/components/schemas/Coverage"
          }
        }
      }
    }
  }
}
