{
  "openapi": "3.0.3",
  "info": {
    "title": "Heynomus Research API",
    "version": "1.0.0",
    "description": "Independent evidence projections. Preserve source links, dates, coverage and unknowns."
  },
  "servers": [
    {
      "url": "https://heynomus.xyz"
    }
  ],
  "paths": {
    "/api/projects": {
      "get": {
        "summary": "Search/filter catalogue",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tab",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "narrative",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "launchpad",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minLiquidity",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minMarketCap",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "maxMarketCap",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minVolume",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stage",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/projects/{slug}": {
      "get": {
        "summary": "Project identity",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/projects/{slug}/snapshot": {
      "get": {
        "summary": "Research brief and coverage",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/projects/{slug}/market": {
      "get": {
        "summary": "Collected pool readings",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/projects/{slug}/usage": {
      "get": {
        "summary": "Partial watched-contract calls",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/projects/{slug}/contracts": {
      "get": {
        "summary": "Contract records",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/ships": {
      "get": {
        "summary": "Counted development events",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/changes": {
      "get": {
        "summary": "Observation ledger",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/signals": {
      "get": {
        "summary": "Recorded signals",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/builders": {
      "get": {
        "summary": "Heynomus radar",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/this-week": {
      "get": {
        "summary": "Weekly report",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/narratives": {
      "get": {
        "summary": "Categories",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Service status",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/config": {
      "get": {
        "summary": "Public integration configuration",
        "responses": {
          "200": {
            "description": "Successful read"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/watchlist": {
      "get": {
        "security": [
          {
            "PrivyBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account-scoped result"
          },
          "401": {
            "description": "Sign-in required"
          }
        }
      },
      "post": {
        "security": [
          {
            "PrivyBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved"
          },
          "401": {
            "description": "Sign-in required"
          },
          "403": {
            "description": "Cross-origin write rejected"
          }
        }
      }
    },
    "/api/notes": {
      "get": {
        "security": [
          {
            "PrivyBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account-scoped result"
          },
          "401": {
            "description": "Sign-in required"
          }
        }
      },
      "post": {
        "security": [
          {
            "PrivyBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved"
          },
          "401": {
            "description": "Sign-in required"
          },
          "403": {
            "description": "Cross-origin write rejected"
          }
        }
      }
    },
    "/api/submit": {
      "get": {
        "security": [
          {
            "PrivyBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account-scoped result"
          },
          "401": {
            "description": "Sign-in required"
          }
        }
      },
      "post": {
        "security": [
          {
            "PrivyBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved"
          },
          "401": {
            "description": "Sign-in required"
          },
          "403": {
            "description": "Cross-origin write rejected"
          }
        }
      }
    },
    "/api/claims": {
      "get": {
        "security": [
          {
            "PrivyBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account-scoped result"
          },
          "401": {
            "description": "Sign-in required"
          }
        }
      },
      "post": {
        "security": [
          {
            "PrivyBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved"
          },
          "401": {
            "description": "Sign-in required"
          },
          "403": {
            "description": "Cross-origin write rejected"
          }
        }
      }
    },
    "/api/ai/chat": {
      "post": {
        "summary": "Ask a cited research question",
        "security": [
          {
            "PrivyBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slug",
                  "question"
                ],
                "properties": {
                  "slug": {
                    "type": "string"
                  },
                  "question": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 2000
                  },
                  "threadId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Answer with threadId and numbered citations"
          },
          "401": {
            "description": "Sign-in required"
          },
          "429": {
            "description": "Quota/concurrency limit"
          },
          "502": {
            "description": "Unusable model answer"
          },
          "503": {
            "description": "Provider/configuration unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PrivyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Privy JWT"
      }
    }
  }
}
