Happenstance AI Personal network API

Added on March 2, 2026 • Managed by admin

Open API schema

{
  "openapi": "3.1.0",
  "info": {
    "title": "Happenstance API",
    "description": "\nThe Happenstance API provides programmatic access to network search, person research and Happenstance Chat.\n\n## Authentication\n\nAll API endpoints require authentication using an API key. Include your API key in the `Authorization` header:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n## Error Responses\n\nAll errors follow RFC 7807 Problem Details format with `application/problem+json` content type.\n\nExample error response:\n```json\n{\n  \"type\": \"https://developer.happenstance.ai/errors/empty-field\",\n  \"title\": \"Bad Request\",\n  \"status\": 400,\n  \"detail\": \"Description must not be empty\",\n  \"instance\": \"/v1/research\"\n}\n```\n",
    "version": "0.1.0"
  },
  "paths": {
    "/v1/search": {
      "post": {
        "summary": "Create Search",
        "description": "Search for people within specified groups and/or within a user's connections.\n\nUse @mentions in your search query to filter results to a specific person's\nconnections (e.g., \"engineers @Jane Smith knows\"). Use the /v1/groups/{group_id}\nendpoint to look up member names for @mentions.\n\nRequires sufficient credits. Returns 402 Payment Required if not enough credits.\nReturns 429 Too Many Requests if you have 10 or more search requests currently running.",
        "operationId": "create_search_v1_search_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequestV1"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "headers": {
              "Link": {
                "description": "RFC 8288 Web Linking header for HATEOAS. Contains URIs to related resources.",
                "schema": {
                  "type": "string"
                },
                "example": "</v1/research/abc123>; rel=\"self\""
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateSearchResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "x-pricing": {
          "credit_based": true,
          "description": "This endpoint costs 2 credits per search"
        }
      }
    },
    "/v1/search/{search_id}": {
      "get": {
        "summary": "Get Search",
        "description": "Get search results.\n\nReturns the status and results of a search request.\nOptionally provide a page_id to retrieve a specific page of results.",
        "operationId": "get_search_v1_search__search_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "search_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Search Id"
            }
          },
          {
            "name": "page_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Page Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetSearchResponseV1"
                }
              }
            },
            "headers": {
              "Link": {
                "description": "RFC 8288 Web Linking header for HATEOAS. Contains URIs to related resources.",
                "schema": {
                  "type": "string"
                },
                "example": "</v1/research/abc123>; rel=\"self\""
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        }
      }
    },
    "/v1/search/{search_id}/find-more": {
      "post": {
        "summary": "Find More Search",
        "description": "Find more results for a search.\n\nCreates a new search that excludes all people from previous results in the search chain.\nUses the same query and settings as the original search.\nCan only be called on the parent search (searches without a parent_search_id).\n\nRequires sufficient credits. Returns 402 Payment Required if not enough credits.\nReturns 429 Too Many Requests if you have 10 or more search requests currently running.",
        "operationId": "find_more_search_v1_search__search_id__find_more_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "search_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Search Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FindMoreSearchResponseV1"
                }
              }
            },
            "headers": {
              "Link": {
                "description": "RFC 8288 Web Linking header for HATEOAS. Contains URIs to related resources.",
                "schema": {
                  "type": "string"
                },
                "example": "</v1/research/abc123>; rel=\"self\""
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        },
        "x-pricing": {
          "credit_based": true,
          "description": "This endpoint costs 2 credits per search"
        }
      }
    },
    "/v1/research": {
      "post": {
        "summary": "Create Research",
        "description": "Start a new person research request.\n\nInclude as many details as possible about the person in the description field\n(full name, company, title, location, social media handles, etc.) for best results.\n\nRequires sufficient credits. Returns 402 Payment Required if not enough credits.\nReturns 429 Too Many Requests if you have 10 or more research requests currently running.",
        "operationId": "create_research_v1_research_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResearchRequestV1"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "headers": {
              "Link": {
                "description": "RFC 8288 Web Linking header for HATEOAS. Contains URIs to related resources.",
                "schema": {
                  "type": "string"
                },
                "example": "</v1/research/abc123>; rel=\"self\""
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateResearchResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "x-pricing": {
          "credit_based": true,
          "description": "This endpoint costs 1 credit per successful, completed research request"
        }
      }
    },
    "/v1/research/{research_id}": {
      "get": {
        "summary": "Get Research",
        "description": "Get the status of a research request.",
        "operationId": "get_research_v1_research__research_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "research_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Research Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetResearchResponseV1"
                }
              }
            },
            "headers": {
              "Link": {
                "description": "RFC 8288 Web Linking header for HATEOAS. Contains URIs to related resources.",
                "schema": {
                  "type": "string"
                },
                "example": "</v1/research/abc123>; rel=\"self\""
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/me": {
      "get": {
        "summary": "Get Current User Profile",
        "description": "Get the current user's profile.",
        "operationId": "get_current_user_profile_v1_users_me_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "headers": {
              "Link": {
                "description": "RFC 8288 Web Linking header for HATEOAS. Contains URIs to related resources.",
                "schema": {
                  "type": "string"
                },
                "example": "</v1/research/abc123>; rel=\"self\""
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/v1/groups": {
      "get": {
        "summary": "Get Groups",
        "operationId": "get_groups_v1_groups_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "headers": {
              "Link": {
                "description": "RFC 8288 Web Linking header for HATEOAS. Contains URIs to related resources.",
                "schema": {
                  "type": "string"
                },
                "example": "</v1/research/abc123>; rel=\"self\""
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetGroupsResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/v1/groups/{group_id}": {
      "get": {
        "summary": "Get Group",
        "description": "Get details of a specific group including its members.\n\nMember names can be used as @mentions in search queries to filter results\nto that person's connections (e.g., \"engineers @Jane Smith knows\").",
        "operationId": "get_group_v1_groups__group_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "group_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Group Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetGroupResponseV1"
                }
              }
            },
            "headers": {
              "Link": {
                "description": "RFC 8288 Web Linking header for HATEOAS. Contains URIs to related resources.",
                "schema": {
                  "type": "string"
                },
                "example": "</v1/research/abc123>; rel=\"self\""
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "summary": "Get Usage",
        "description": "Get credit balance, purchase history, usage history, and Auto Reload settings for the authenticated user.",
        "operationId": "get_usage_v1_usage_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "headers": {
              "Link": {
                "description": "RFC 8288 Web Linking header for HATEOAS. Contains URIs to related resources.",
                "schema": {
                  "type": "string"
                },
                "example": "</v1/research/abc123>; rel=\"self\""
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetUsageResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/v1/chat": {
      "post": {
        "summary": "Create Chat",
        "description": "Start a chat with Happenstance Chat, optionally with its first message.\n\nChat searches the user's network (their connections, their friends' and their groups'),\nresearches people and drafts outreach, over as many turns as the conversation needs. A\nmessage returns at once with a turn id: poll GET /v1/chat/{chat_id}/turns/{turn_id} until\nthe turn's status is completed, then read the people and drafts.\n\nEach turn is charged when it finishes. Returns 402 when the balance is below 3 credits.",
        "operationId": "create_chat_v1_chat_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateChatRequestV1"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateChatResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        },
        "x-pricing": {
          "credit_based": true,
          "description": "Each message is charged when its turn finishes, for the turn's cost in credits, to two decimal places. Chat turns have variable cost depending on how much work is done, often 1\u20133 credits."
        }
      },
      "get": {
        "summary": "List Chats",
        "description": "The user's chats, most recently active first: the ones started through the API, which\ntake messages, and the ones started in the Happenstance app, which can be read.",
        "operationId": "list_chats_v1_chat_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Page, starting at 0 (50 chats a page)",
              "default": 0,
              "title": "Page"
            },
            "description": "Page, starting at 0 (50 chats a page)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetChatsResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/{chat_id}": {
      "get": {
        "summary": "Get Chat",
        "description": "The whole chat: its messages (Chat's as markdown), its turns, the searches it ran, and\nthe notes Chat keeps on the user's goal and preferences (memory) and on older turns.",
        "operationId": "get_chat_v1_chat__chat_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "chat_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Chat Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetChatResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/{chat_id}/messages": {
      "post": {
        "summary": "Send Chat Message",
        "description": "Send a message to a chat started through the API. Returns at once with the turn to poll. A\nmessage sent while a turn is still working joins that turn (joined: true): Chat takes it\ninto the work in progress, and the turn's reply and charge cover both messages.\n\nWhen a turn ends with stop_reason needs_input, Chat waits on the questions in its\nreply.questions: send answers (by question index and option label), a message that answers\nthem in words, or both. The answer starts the next turn (answered: true).\n\nReturns 402 when the balance is below 3 credits for this message and for each turn still\nrunning, 409 for a chat started in the app.",
        "operationId": "send_chat_message_v1_chat__chat_id__messages_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "chat_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Chat Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendChatMessageRequestV1"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendChatMessageResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        },
        "x-pricing": {
          "credit_based": true,
          "description": "Each message is charged when its turn finishes, for the turn's cost in credits, to two decimal places. Chat turns have variable cost depending on how much work is done, often 1\u20133 credits."
        }
      }
    },
    "/v1/chat/{chat_id}/turns/{turn_id}": {
      "get": {
        "summary": "Get Chat Turn",
        "description": "A turn: its status, Chat's reply so far (markdown), the searches it ran, and its usage\nand charge once finished. Poll every 5 seconds for the first minute, then every 10; turns\nwith searches usually take 1 to 3 minutes. Not rate limited. `latest` reads the chat's\nnewest turn; the response's `id` names it.",
        "operationId": "get_chat_turn_v1_chat__chat_id__turns__turn_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "chat_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Chat Id"
            }
          },
          {
            "name": "turn_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "A turn ID from POST /v1/chat or /messages, or `latest` for the chat's newest turn",
              "title": "Turn Id"
            },
            "description": "A turn ID from POST /v1/chat or /messages, or `latest` for the chat's newest turn"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatTurnV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/{chat_id}/turns/{turn_id}/cancel": {
      "post": {
        "summary": "Cancel Chat Turn",
        "description": "Stop a running turn, as the Stop button in the app does. Chat keeps what it wrote, its\nsearches stop, and the turn ends cancelled, charged for the work done. A finished turn is\nreturned as it is. `latest` stops whatever the chat is working on.",
        "operationId": "cancel_chat_turn_v1_chat__chat_id__turns__turn_id__cancel_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "chat_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Chat Id"
            }
          },
          {
            "name": "turn_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "A turn ID from POST /v1/chat or /messages, or `latest` for the chat's newest turn",
              "title": "Turn Id"
            },
            "description": "A turn ID from POST /v1/chat or /messages, or `latest` for the chat's newest turn"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatTurnV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/{chat_id}/people": {
      "get": {
        "summary": "Get Chat People",
        "description": "Everyone Chat showed in the chat, one row per person with their cards merged: title,\ncompany, location, LinkedIn, how the user is connected (directly, and through which\nmutuals, with connection strength), and why Chat picked them. In order of first\nappearance; with turn_id, the people of that turn.",
        "operationId": "get_chat_people_v1_chat__chat_id__people_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "chat_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Chat Id"
            }
          },
          {
            "name": "turn_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Only the people this turn showed, in its order; `latest` for the newest turn",
              "title": "Turn Id"
            },
            "description": "Only the people this turn showed, in its order; `latest` for the newest turn"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Page, starting at 0 (100 people a page)",
              "default": 0,
              "title": "Page"
            },
            "description": "Page, starting at 0 (100 people a page)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetChatPeopleResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/{chat_id}/drafts": {
      "get": {
        "summary": "Get Chat Drafts",
        "description": "The message drafts Chat wrote in the chat. Happenstance never sends them; the caller\nmay, with the user's own email, LinkedIn or other tools.",
        "operationId": "get_chat_drafts_v1_chat__chat_id__drafts_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "chat_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Chat Id"
            }
          },
          {
            "name": "latest_per_person",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "description": "Only the latest draft for each recipient (false: every version, in order)",
              "default": true,
              "title": "Latest Per Person"
            },
            "description": "Only the latest draft for each recipient (false: every version, in order)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetChatDraftsResponseV1"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "410": {
            "description": "Gone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailV1"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiPurchaseV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the purchase"
          },
          "credits": {
            "type": "integer",
            "title": "Credits",
            "description": "Number of credits purchased"
          },
          "purchased_at": {
            "type": "string",
            "title": "Purchased At",
            "description": "When the purchase was made (ISO 8601 format)"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "credits",
          "purchased_at"
        ],
        "title": "ApiPurchaseV1",
        "description": "A credit purchase record"
      },
      "ApiUsageV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the usage"
          },
          "credit_used": {
            "type": "number",
            "title": "Credit Used",
            "description": "Credits consumed, to two decimal places"
          },
          "created_at": {
            "type": "string",
            "title": "Created At",
            "description": "When the usage was recorded (ISO 8601 format)"
          },
          "resource_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Resource Id",
            "description": "ID of the resource that consumed the credits (search ID, research ID, or chat turn ID)"
          },
          "resource_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Resource Type",
            "description": "Type of resource: 'search', 'research' or 'chat_turn'"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "credit_used",
          "created_at"
        ],
        "title": "ApiUsageV1",
        "description": "A credit usage record"
      },
      "AutoReloadSettingsV1": {
        "properties": {
          "enabled": {
            "type": "boolean",
            "title": "Enabled",
            "description": "Whether Auto Reload is enabled"
          },
          "threshold_credits": {
            "type": "integer",
            "title": "Threshold Credits",
            "description": "Credits threshold that triggers Auto Reload"
          },
          "reload_credit_amount": {
            "type": "integer",
            "title": "Reload Credit Amount",
            "description": "Number of credits to purchase on Auto Reload"
          },
          "last_reload_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Reload At",
            "description": "Last Auto Reload timestamp (ISO 8601 format)"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "enabled",
          "threshold_credits",
          "reload_credit_amount"
        ],
        "title": "AutoReloadSettingsV1",
        "description": "Auto Reload configuration"
      },
      "ChatAnswerV1": {
        "properties": {
          "question_index": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Question Index",
            "description": "The question's index, from 0"
          },
          "selected": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "maxItems": 4,
            "title": "Selected",
            "description": "The chosen option labels, exactly as given (several only for a multi_select question)"
          },
          "other": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 32000
              },
              {
                "type": "null"
              }
            ],
            "title": "Other",
            "description": "A free-text answer instead of or beside the options"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "question_index"
        ],
        "title": "ChatAnswerV1",
        "description": "An answer to one of Chat's questions (reply.questions of a needs_input turn)."
      },
      "ChatDraftV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "The draft's id, unique in the chat"
          },
          "turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Turn Id",
            "description": "The turn that wrote it"
          },
          "group_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Group Id",
            "description": "The id of the set of drafts it was written with, when Chat wrote several together"
          },
          "recipient_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Recipient Name"
          },
          "person_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Person Id",
            "description": "The recipient's person id; null for templates, posts and recipients Chat didn't identify"
          },
          "kind": {
            "type": "string",
            "enum": [
              "outreach",
              "intro_request",
              "forwardable",
              "template",
              "post",
              "email"
            ],
            "title": "Kind",
            "description": "What the draft is, guessed from how Chat named it"
          },
          "body_markdown": {
            "type": "string",
            "title": "Body Markdown",
            "description": "The text to send; links are markdown links"
          },
          "body_text": {
            "type": "string",
            "title": "Body Text",
            "description": "The same text in plain form for channels without markdown (LinkedIn, plain email): each link written as its text followed by the URL in parentheses"
          },
          "characters": {
            "type": "integer",
            "title": "Characters",
            "description": "Length of body_text, in characters"
          },
          "supersedes": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Supersedes",
            "description": "The earlier draft for the same recipient this one revises"
          },
          "created_at": {
            "type": "string",
            "title": "Created At",
            "description": "When it was written (ISO 8601)"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "kind",
          "body_markdown",
          "body_text",
          "characters",
          "created_at"
        ],
        "title": "ChatDraftV1",
        "description": "A message draft Chat wrote. Happenstance never sends it; the caller may."
      },
      "ChatLinkV1": {
        "properties": {
          "url": {
            "type": "string",
            "title": "Url"
          },
          "text": {
            "type": "string",
            "title": "Text"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "url",
          "text"
        ],
        "title": "ChatLinkV1"
      },
      "ChatMessageV1": {
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant",
              "schedule"
            ],
            "title": "Role",
            "description": "user: a message to Chat. assistant: Chat's reply. schedule: a scheduled task ran; the markdown is its instruction."
          },
          "turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Turn Id",
            "description": "The turn the message belongs to"
          },
          "markdown": {
            "type": "string",
            "title": "Markdown"
          },
          "created_at": {
            "type": "string",
            "title": "Created At"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "role",
          "markdown",
          "created_at"
        ],
        "title": "ChatMessageV1"
      },
      "ChatPersonColumnV1": {
        "properties": {
          "column": {
            "type": "string",
            "title": "Column",
            "description": "The column's label, as the table's header shows it"
          },
          "value": {
            "type": "string",
            "title": "Value",
            "description": "The person's value; empty when Chat didn't know it"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "column",
          "value"
        ],
        "title": "ChatPersonColumnV1"
      },
      "ChatPersonMutualV1": {
        "properties": {
          "user_id": {
            "type": "string",
            "title": "User Id",
            "description": "The mutual's user id"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "The mutual's name"
          },
          "happenstance_url": {
            "type": "string",
            "title": "Happenstance Url",
            "description": "The mutual's Happenstance profile"
          },
          "via": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "friend",
                  "group"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Via",
            "description": "How the user reaches the mutual: a Happenstance friend, or a member of a shared group"
          },
          "affinity": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Affinity",
            "description": "How well the mutual knows the person, as a score: 0 means we have no evidence beyond the connection itself; 45 and up is medium, 75 strong, 100 very strong."
          },
          "affinity_level": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "very_strong",
                  "strong",
                  "medium",
                  "weak"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Affinity Level",
            "description": "The same as a level, as the Happenstance app shows it"
          },
          "sources": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Sources",
            "description": "How the mutual is connected to the person, when that's public: linkedin, instagram, twitter, in that order. Email, calendar and contact-book connections are the mutual's own and are left out, so this is empty when those are all there is"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "user_id",
          "name",
          "happenstance_url"
        ],
        "title": "ChatPersonMutualV1",
        "description": "A Happenstance user who knows the person and could introduce the user."
      },
      "ChatPersonRelationshipV1": {
        "properties": {
          "you_know_them": {
            "type": "boolean",
            "title": "You Know Them",
            "description": "Whether the user is directly connected to them"
          },
          "sources": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Sources",
            "description": "Where the user's own connection comes from (linkedin, gmail, google_calendar, google_contacts, ...). Empty when they aren't directly connected."
          },
          "affinity": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Affinity",
            "description": "How strong the user's own connection is, as a score: 0 means we have no evidence beyond the connection itself; 45 and up is medium, 75 strong, 100 very strong. Null when not directly connected."
          },
          "affinity_level": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "very_strong",
                  "strong",
                  "medium",
                  "weak"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Affinity Level",
            "description": "The same as a level, as the Happenstance app shows it"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "you_know_them"
        ],
        "title": "ChatPersonRelationshipV1"
      },
      "ChatPersonV1": {
        "properties": {
          "person_id": {
            "type": "string",
            "title": "Person Id",
            "description": "The person's id (stable across chats and searches)"
          },
          "name": {
            "type": "string",
            "title": "Name"
          },
          "headline": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Headline",
            "description": "Title and company, as shown"
          },
          "current_title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Title"
          },
          "current_company": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Company"
          },
          "location": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Location"
          },
          "linkedin_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Linkedin Url"
          },
          "happenstance_url": {
            "type": "string",
            "title": "Happenstance Url",
            "description": "The person's page on Happenstance"
          },
          "relationship": {
            "$ref": "#/components/schemas/ChatPersonRelationshipV1"
          },
          "mutuals": {
            "items": {
              "$ref": "#/components/schemas/ChatPersonMutualV1"
            },
            "type": "array",
            "title": "Mutuals",
            "description": "People who can introduce the user, strongest first (at most 20)"
          },
          "rationale_markdown": {
            "type": "string",
            "title": "Rationale Markdown",
            "description": "Why Chat picked them: the card's text from the latest turn that showed them, with its links"
          },
          "links": {
            "items": {
              "$ref": "#/components/schemas/ChatLinkV1"
            },
            "type": "array",
            "title": "Links",
            "description": "The links in the rationale (posts, pages)"
          },
          "columns": {
            "items": {
              "$ref": "#/components/schemas/ChatPersonColumnV1"
            },
            "type": "array",
            "title": "Columns",
            "description": "The extra columns of the table that showed them (from the latest card that had any, with an earlier card's value for a column it left blank), in the table's order: values the user asked Chat for, such as priority or best role. Empty when the table had none."
          },
          "section": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Section",
            "description": "The heading the card was under, when Chat grouped the people (\"Investors\", \"Tier 1\")"
          },
          "search_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Search Id",
            "description": "The search that found them, when one did"
          },
          "turn_ids": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Turn Ids",
            "description": "The turns that showed them, oldest first"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "person_id",
          "name",
          "happenstance_url",
          "relationship",
          "rationale_markdown",
          "turn_ids"
        ],
        "title": "ChatPersonV1",
        "description": "A person Chat showed, across the chat's turns (one row per person: their latest card,\nwith what earlier cards said where the latest one is shorter or leaves it out)."
      },
      "ChatQuestionOptionV1": {
        "properties": {
          "label": {
            "type": "string",
            "title": "Label",
            "description": "The option, as answers[].selected takes it"
          },
          "description": {
            "type": "string",
            "title": "Description",
            "description": "What choosing it means"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "label",
          "description"
        ],
        "title": "ChatQuestionOptionV1"
      },
      "ChatQuestionV1": {
        "properties": {
          "index": {
            "type": "integer",
            "title": "Index",
            "description": "Its index, as answers[].question_index takes it"
          },
          "header": {
            "type": "string",
            "title": "Header",
            "description": "A one to three word label"
          },
          "question": {
            "type": "string",
            "title": "Question"
          },
          "options": {
            "items": {
              "$ref": "#/components/schemas/ChatQuestionOptionV1"
            },
            "type": "array",
            "title": "Options"
          },
          "multi_select": {
            "type": "boolean",
            "title": "Multi Select",
            "description": "Whether more than one option may be chosen"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "index",
          "header",
          "question",
          "options",
          "multi_select"
        ],
        "title": "ChatQuestionV1",
        "description": "A question Chat asked the user, with options to choose from."
      },
      "ChatReplyV1": {
        "properties": {
          "markdown": {
            "type": "string",
            "title": "Markdown",
            "description": "Chat's reply, as markdown with absolute links: its latest message, and every message with people or drafts. People appear as list items and drafts as quoted blocks; read them as data with /people and /drafts. Grows while the turn runs."
          },
          "updates": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Updates",
            "description": "Chat's earlier notes in this turn that hold no people or drafts, such as 'searching now' or a reply to a message that joined the turn. Not part of the answer."
          },
          "people_count": {
            "type": "integer",
            "title": "People Count",
            "description": "People shown in this turn"
          },
          "people_new_count": {
            "type": "integer",
            "title": "People New Count",
            "description": "People shown in this turn who weren't shown in an earlier one"
          },
          "drafts_count": {
            "type": "integer",
            "title": "Drafts Count",
            "description": "Message drafts written in this turn"
          },
          "searches": {
            "items": {
              "$ref": "#/components/schemas/ChatSearchV1"
            },
            "type": "array",
            "title": "Searches",
            "description": "People searches run in this turn"
          },
          "suggested_followup": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Suggested Followup",
            "description": "A next message Chat suggests, in the user's voice, when it offers one"
          },
          "questions": {
            "items": {
              "$ref": "#/components/schemas/ChatQuestionV1"
            },
            "type": "array",
            "title": "Questions",
            "description": "The last questions Chat asked the user in this turn. When the turn ends with stop_reason needs_input, Chat waits for their answers: send them with POST /v1/chat/{chat_id}/messages (answers, or a message). Answer from what you know of the user's goal; ask the user when you don't know."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "markdown",
          "people_count",
          "people_new_count",
          "drafts_count"
        ],
        "title": "ChatReplyV1"
      },
      "ChatScheduleV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "instruction": {
            "type": "string",
            "title": "Instruction",
            "description": "What Chat does on each run"
          },
          "cron": {
            "type": "string",
            "title": "Cron",
            "description": "5-field cron expression (minute hour day-of-month month day-of-week)"
          },
          "timezone": {
            "type": "string",
            "title": "Timezone",
            "description": "IANA timezone the cron is read in"
          },
          "next_run_at": {
            "type": "string",
            "title": "Next Run At",
            "description": "When it next comes due (ISO 8601, UTC like every time in this API). A paused task does not run."
          },
          "paused": {
            "type": "boolean",
            "title": "Paused"
          },
          "paused_reason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "inactive",
                  "by_user"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Paused Reason",
            "description": "Why it is paused: inactive (no message to the chat for 8 of its periods; a message re-arms it) or by_user"
          },
          "email_enabled": {
            "type": "boolean",
            "title": "Email Enabled",
            "description": "Whether each finished run also emails the user a link to the chat"
          },
          "push_enabled": {
            "type": "boolean",
            "title": "Push Enabled",
            "description": "Whether each finished run also notifies the user's Happenstance phone app"
          },
          "created_at": {
            "type": "string",
            "title": "Created At"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "instruction",
          "cron",
          "timezone",
          "next_run_at",
          "paused",
          "email_enabled",
          "push_enabled",
          "created_at"
        ],
        "title": "ChatScheduleV1",
        "description": "A scheduled task of a chat started in the app: Chat runs its instruction in the chat on a\ncron schedule. Tasks are set up and changed in the app."
      },
      "ChatScopeV1": {
        "properties": {
          "my_connections": {
            "type": "boolean",
            "title": "My Connections",
            "description": "The user's own connections"
          },
          "friends_connections": {
            "type": "boolean",
            "title": "Friends Connections",
            "description": "The user's friends' connections"
          },
          "all_groups": {
            "type": "boolean",
            "title": "All Groups",
            "description": "Every group the user is in"
          },
          "group_ids": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Group Ids",
            "description": "Specific groups searched, when not all"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "my_connections",
          "friends_connections",
          "all_groups"
        ],
        "title": "ChatScopeV1",
        "description": "Whose networks the turn's searches covered (the union across its searches)."
      },
      "ChatSearchV1": {
        "properties": {
          "search_id": {
            "type": "string",
            "title": "Search Id",
            "description": "The search's id, for GET /v1/search/{search_id}"
          },
          "page_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Page Id",
            "description": "The find-more page of that search, when this was one"
          },
          "turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Turn Id",
            "description": "The turn that ran it"
          },
          "query": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Query",
            "description": "What Chat searched for"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "failed",
              "stopped"
            ],
            "title": "Status",
            "description": "The search's status"
          },
          "results_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Results Count",
            "description": "How many people the search returned, once completed"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "search_id",
          "status"
        ],
        "title": "ChatSearchV1",
        "description": "A people search Chat ran. Read all its results with GET /v1/search/{search_id} (with\npage_id for a find-more page)."
      },
      "ChatTurnSummaryV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "started_by": {
            "type": "string",
            "enum": [
              "message",
              "schedule"
            ],
            "title": "Started By",
            "default": "message"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "cancelled"
            ],
            "title": "Status"
          },
          "created_at": {
            "type": "string",
            "title": "Created At"
          },
          "completed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Completed At"
          },
          "credits_charged": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Credits Charged",
            "description": "Credits charged for the turn, once billed"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "status",
          "created_at"
        ],
        "title": "ChatTurnSummaryV1"
      },
      "ChatTurnUsageV1": {
        "properties": {
          "credits_charged": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Credits Charged",
            "description": "Credits charged for the turn, to two decimal places. Null while the turn runs, for a few seconds after it finishes until billing records the charge, and for chats started in the Happenstance app."
          },
          "searches": {
            "type": "integer",
            "title": "Searches",
            "description": "People searches Chat ran"
          },
          "web_searches": {
            "type": "integer",
            "title": "Web Searches",
            "description": "Web searches and page reads Chat ran"
          },
          "model_calls": {
            "type": "integer",
            "title": "Model Calls",
            "description": "Model calls Chat made"
          },
          "people_reviewed": {
            "type": "integer",
            "title": "People Reviewed",
            "description": "People the searches returned for Chat to review"
          },
          "scope": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ChatScopeV1"
              },
              {
                "type": "null"
              }
            ],
            "description": "Whose networks were searched; null when nothing was"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "searches",
          "web_searches",
          "model_calls",
          "people_reviewed"
        ],
        "title": "ChatTurnUsageV1"
      },
      "ChatTurnV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "The turn's id"
          },
          "chat_id": {
            "type": "string",
            "title": "Chat Id",
            "description": "The chat's id"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "cancelled"
            ],
            "title": "Status",
            "description": "queued (not started), running, completed, failed (not charged) or cancelled"
          },
          "stop_reason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "done",
                  "needs_input",
                  "stopped",
                  "error"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Stop Reason",
            "description": "Why a finished turn ended: done; needs_input (Chat asked questions and waits for the answers, see reply.questions); stopped (cancelled); error. Null while running."
          },
          "started_by": {
            "type": "string",
            "enum": [
              "message",
              "schedule"
            ],
            "title": "Started By",
            "description": "message: a message or answers started the turn. schedule: one of the chat's scheduled tasks ran, and nobody sent a message (only a chat started in the app has scheduled tasks).",
            "default": "message"
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "The message that started the turn, or for a scheduled run the task's instruction"
          },
          "messages": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Messages",
            "description": "Every message in the turn: the first started it, any later one was sent while it ran and joined it. A scheduled run's turn has none."
          },
          "reply": {
            "$ref": "#/components/schemas/ChatReplyV1"
          },
          "usage": {
            "$ref": "#/components/schemas/ChatTurnUsageV1"
          },
          "created_at": {
            "type": "string",
            "title": "Created At",
            "description": "When the turn started (ISO 8601)"
          },
          "completed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Completed At",
            "description": "When the turn finished (ISO 8601)"
          },
          "last_activity_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Activity At",
            "description": "When Chat last made progress on the turn (a reply, a search starting or finishing). A running turn with no progress for several minutes is stuck or slow and can be cancelled."
          },
          "elapsed_seconds": {
            "type": "integer",
            "title": "Elapsed Seconds",
            "description": "Seconds since the turn started, or how long it took once finished"
          },
          "next_turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Turn Id",
            "description": "The chat's next turn, once one was started"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "chat_id",
          "status",
          "message",
          "messages",
          "reply",
          "usage",
          "created_at",
          "elapsed_seconds"
        ],
        "title": "ChatTurnV1",
        "description": "Response from GET /v1/chat/{chat_id}/turns/{turn_id}: a message and Chat's work on it."
      },
      "ChatV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title"
          },
          "source": {
            "type": "string",
            "enum": [
              "api",
              "app"
            ],
            "title": "Source",
            "description": "api: started through the API (you can send messages); app: started in the Happenstance app (read only here)"
          },
          "url": {
            "type": "string",
            "title": "Url",
            "description": "The chat in the Happenstance app"
          },
          "status": {
            "type": "string",
            "enum": [
              "idle",
              "running"
            ],
            "title": "Status"
          },
          "turn_count": {
            "type": "integer",
            "title": "Turn Count"
          },
          "schedule_count": {
            "type": "integer",
            "title": "Schedule Count",
            "description": "The chat's scheduled tasks (only a chat started in the app has them); read them with GET /v1/chat/{chat_id}",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "title": "Created At"
          },
          "last_activity_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Activity At"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "source",
          "url",
          "status",
          "turn_count",
          "created_at"
        ],
        "title": "ChatV1",
        "description": "A chat in GET /v1/chat."
      },
      "CreateChatRequestV1": {
        "properties": {
          "message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Message",
            "description": "The first message. Omit it to create an empty chat and send messages with POST /v1/chat/{chat_id}/messages."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "CreateChatRequestV1"
      },
      "CreateChatResponseV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "The chat's id"
          },
          "url": {
            "type": "string",
            "title": "Url",
            "description": "The chat in the Happenstance app"
          },
          "turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Turn Id",
            "description": "The first message's turn, when a message was sent"
          },
          "status": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "queued",
                  "running",
                  "completed",
                  "failed",
                  "cancelled"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Status",
            "description": "The turn's status, when a message was sent"
          },
          "warning": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Warning",
            "description": "Warning message when credit balance is low"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "url"
        ],
        "title": "CreateChatResponseV1",
        "description": "Response from POST /v1/chat."
      },
      "CreateResearchResponseV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the research job"
          },
          "url": {
            "type": "string",
            "title": "Url",
            "description": "URL to view the research profile on Happenstance"
          },
          "warning": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Warning",
            "description": "Warning message when credit balance is low"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "url"
        ],
        "title": "CreateResearchResponseV1",
        "description": "Response from POST /v1/research - creating a new research request."
      },
      "CreateSearchResponseV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the search request"
          },
          "url": {
            "type": "string",
            "title": "Url",
            "description": "URL to view the search results on Happenstance"
          },
          "warning": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Warning",
            "description": "Warning message when credit balance is low"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "url"
        ],
        "title": "CreateSearchResponseV1",
        "description": "Response from POST /v1/search - creating a new search request."
      },
      "CurrentLocationV1": {
        "properties": {
          "location": {
            "type": "string",
            "title": "Location",
            "description": "Location name (e.g., 'Palo Alto, California')"
          },
          "comments": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Comments",
            "description": "Notes or context about the location"
          },
          "urls": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Urls",
            "description": "URLs confirming this location"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "location"
        ],
        "title": "CurrentLocationV1",
        "description": "Current location information"
      },
      "EducationV1": {
        "properties": {
          "university_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "University Name",
            "description": "Name of the university or institution"
          },
          "degree": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Degree",
            "description": "Degree obtained (e.g., BS, MS, PhD)"
          },
          "start_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Start Date",
            "description": "Start date (YYYY-MM-DD format)"
          },
          "end_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "End Date",
            "description": "End date (YYYY-MM-DD format)"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description",
            "description": "Additional details about the education"
          },
          "urls": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Urls",
            "description": "Related URLs"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "EducationV1",
        "description": "Education history entry"
      },
      "EmploymentV1": {
        "properties": {
          "company_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Company Name",
            "description": "Name of the company"
          },
          "job_title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Job Title",
            "description": "Job title or role"
          },
          "start_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Start Date",
            "description": "Start date (YYYY-MM-DD format)"
          },
          "end_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "End Date",
            "description": "End date (YYYY-MM-DD format), null if current position"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description",
            "description": "Description of role and responsibilities"
          },
          "urls": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Urls",
            "description": "Related URLs (company website, LinkedIn, etc.)"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "EmploymentV1",
        "description": "Employment history entry"
      },
      "FindMoreSearchResponseV1": {
        "properties": {
          "page_id": {
            "type": "string",
            "title": "Page Id",
            "description": "Page identifier for the new result page. Use as the page_id query parameter on GET /v1/search/{id}?page_id={page_id} to retrieve results."
          },
          "parent_search_id": {
            "type": "string",
            "title": "Parent Search Id",
            "description": "ID of the original parent search"
          },
          "warning": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Warning",
            "description": "Warning message when credit balance is low"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "page_id",
          "parent_search_id"
        ],
        "title": "FindMoreSearchResponseV1",
        "description": "Response from POST /v1/search/{id}/find-more - finding more results for a search."
      },
      "FriendV1": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Friend's name"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "name"
        ],
        "title": "FriendV1",
        "description": "A friend of the current user."
      },
      "GetChatDraftsResponseV1": {
        "properties": {
          "chat_id": {
            "type": "string",
            "title": "Chat Id"
          },
          "total": {
            "type": "integer",
            "title": "Total"
          },
          "drafts": {
            "items": {
              "$ref": "#/components/schemas/ChatDraftV1"
            },
            "type": "array",
            "title": "Drafts"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "chat_id",
          "total",
          "drafts"
        ],
        "title": "GetChatDraftsResponseV1",
        "description": "Response from GET /v1/chat/{chat_id}/drafts."
      },
      "GetChatPeopleResponseV1": {
        "properties": {
          "chat_id": {
            "type": "string",
            "title": "Chat Id"
          },
          "turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Turn Id",
            "description": "The turn the list is limited to, when one was given"
          },
          "page": {
            "type": "integer",
            "title": "Page",
            "description": "This page, starting at 0"
          },
          "page_size": {
            "type": "integer",
            "title": "Page Size"
          },
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "People in the whole list"
          },
          "has_more": {
            "type": "boolean",
            "title": "Has More"
          },
          "people": {
            "items": {
              "$ref": "#/components/schemas/ChatPersonV1"
            },
            "type": "array",
            "title": "People"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "chat_id",
          "page",
          "page_size",
          "total",
          "has_more",
          "people"
        ],
        "title": "GetChatPeopleResponseV1",
        "description": "Response from GET /v1/chat/{chat_id}/people."
      },
      "GetChatResponseV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title"
          },
          "source": {
            "type": "string",
            "enum": [
              "api",
              "app"
            ],
            "title": "Source"
          },
          "url": {
            "type": "string",
            "title": "Url"
          },
          "status": {
            "type": "string",
            "enum": [
              "idle",
              "running"
            ],
            "title": "Status"
          },
          "created_at": {
            "type": "string",
            "title": "Created At"
          },
          "memory": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Memory",
            "description": "Chat's notes on the user and the goal (preferences, exclusions, style), kept across turns"
          },
          "history_summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "History Summary",
            "description": "Chat's summary of the older part of a long conversation"
          },
          "credits_charged": {
            "type": "number",
            "title": "Credits Charged",
            "description": "Credits charged for the chat's turns so far"
          },
          "turns": {
            "items": {
              "$ref": "#/components/schemas/ChatTurnSummaryV1"
            },
            "type": "array",
            "title": "Turns"
          },
          "messages": {
            "items": {
              "$ref": "#/components/schemas/ChatMessageV1"
            },
            "type": "array",
            "title": "Messages"
          },
          "searches": {
            "items": {
              "$ref": "#/components/schemas/ChatSearchV1"
            },
            "type": "array",
            "title": "Searches"
          },
          "schedules": {
            "items": {
              "$ref": "#/components/schemas/ChatScheduleV1"
            },
            "type": "array",
            "title": "Schedules",
            "description": "The chat's scheduled tasks. Only a chat started in the app has them. A chat started through the API has none: to run it on a schedule, send it a message on yours."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "source",
          "url",
          "status",
          "created_at",
          "credits_charged",
          "turns",
          "messages",
          "searches"
        ],
        "title": "GetChatResponseV1",
        "description": "Response from GET /v1/chat/{chat_id}: the conversation and what Chat keeps about it."
      },
      "GetChatsResponseV1": {
        "properties": {
          "chats": {
            "items": {
              "$ref": "#/components/schemas/ChatV1"
            },
            "type": "array",
            "title": "Chats"
          },
          "page": {
            "type": "integer",
            "title": "Page"
          },
          "has_more": {
            "type": "boolean",
            "title": "Has More"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "chats",
          "page",
          "has_more"
        ],
        "title": "GetChatsResponseV1",
        "description": "Response from GET /v1/chat."
      },
      "GetGroupResponseV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the group"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Name of the group"
          },
          "slug": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Slug",
            "description": "URL slug for the group"
          },
          "member_count": {
            "type": "integer",
            "title": "Member Count",
            "description": "Number of members in the group"
          },
          "members": {
            "items": {
              "$ref": "#/components/schemas/GroupMemberV1"
            },
            "type": "array",
            "title": "Members",
            "description": "List of group members"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "name",
          "member_count",
          "members"
        ],
        "title": "GetGroupResponseV1",
        "description": "Response from GET /v1/groups/{group_id} - retrieving group details."
      },
      "GetGroupsResponseV1": {
        "properties": {
          "groups": {
            "items": {
              "$ref": "#/components/schemas/GroupV1"
            },
            "type": "array",
            "title": "Groups",
            "description": "List of groups the user has access to"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "groups"
        ],
        "title": "GetGroupsResponseV1",
        "description": "Response from GET /v1/groups - retrieving user's groups."
      },
      "GetResearchResponseV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the research job"
          },
          "status": {
            "type": "string",
            "title": "Status",
            "description": "Status of the research job (RUNNING, COMPLETED, FAILED, FAILED_AMBIGUOUS)"
          },
          "query": {
            "type": "string",
            "title": "Query",
            "description": "Original research query"
          },
          "created_at": {
            "type": "string",
            "title": "Created At",
            "description": "Timestamp when research was created (ISO 8601 format)"
          },
          "updated_at": {
            "type": "string",
            "title": "Updated At",
            "description": "Timestamp when research was last updated (ISO 8601 format)"
          },
          "profile": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ProfileV1"
              },
              {
                "type": "null"
              }
            ],
            "description": "Research results (only populated when status is COMPLETED)"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "status",
          "query",
          "created_at",
          "updated_at"
        ],
        "title": "GetResearchResponseV1",
        "description": "Response from GET /v1/research/{id} - retrieving research status and results."
      },
      "GetSearchResponseV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the search request"
          },
          "url": {
            "type": "string",
            "title": "Url",
            "description": "URL to view the search results on Happenstance (points to parent search for continued searches)"
          },
          "status": {
            "type": "string",
            "title": "Status",
            "description": "Status of the search (RUNNING, COMPLETED, FAILED)"
          },
          "text": {
            "type": "string",
            "title": "Text",
            "description": "Original search query text"
          },
          "created_at": {
            "type": "string",
            "title": "Created At",
            "description": "Timestamp when search was created (ISO 8601 format)"
          },
          "updated_at": {
            "type": "string",
            "title": "Updated At",
            "description": "Timestamp when search was last updated (ISO 8601 format)"
          },
          "group_ids": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Group Ids",
            "description": "List of group IDs that were searched"
          },
          "include_friends_connections": {
            "type": "boolean",
            "title": "Include Friends Connections",
            "description": "Whether the search included friends' connections",
            "default": false
          },
          "include_my_connections": {
            "type": "boolean",
            "title": "Include My Connections",
            "description": "Whether the search included the user's own connections",
            "default": false
          },
          "mutuals": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/SearchMutualV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Mutuals",
            "description": "All unique mutual connections across results. Results reference these by index."
          },
          "traits": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/SearchTraitV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Traits",
            "description": "All trait definitions for this search. Results reference these by index."
          },
          "results": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/SearchPersonV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Results",
            "description": "Search results (only populated when status is COMPLETED)"
          },
          "page_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Page Id",
            "description": "Page identifier for the current result page. Null for the first page (the parent search itself). For subsequent pages, this is the page_id returned by POST /v1/search/{id}/find-more."
          },
          "next_page": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Page",
            "description": "Page identifier for the next result page. Use as the page_id query parameter on GET /v1/search/{id}?page_id={next_page} to retrieve the next page. Null if no next page exists."
          },
          "has_more": {
            "type": "boolean",
            "title": "Has More",
            "description": "Whether more results may be available via POST /v1/search/{id}/find-more. Searches return up to 30 results at a time.",
            "default": false
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "url",
          "status",
          "text",
          "created_at",
          "updated_at"
        ],
        "title": "GetSearchResponseV1",
        "description": "Response from GET /v1/search/{id} - retrieving search status and results."
      },
      "GetUsageResponseV1": {
        "properties": {
          "balance_credits": {
            "type": "number",
            "title": "Balance Credits",
            "description": "Current credit balance, to two decimal places (can be negative if credits consumed without sufficient balance)"
          },
          "has_credits": {
            "type": "boolean",
            "title": "Has Credits",
            "description": "Whether the user has credits available (balance > 0)"
          },
          "purchases": {
            "items": {
              "$ref": "#/components/schemas/ApiPurchaseV1"
            },
            "type": "array",
            "title": "Purchases",
            "description": "List of credit purchases, most recent first"
          },
          "usage": {
            "items": {
              "$ref": "#/components/schemas/ApiUsageV1"
            },
            "type": "array",
            "title": "Usage",
            "description": "List of credit usage records, most recent first. Limited to the 500 most recent records."
          },
          "auto_reload": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AutoReloadSettingsV1"
              },
              {
                "type": "null"
              }
            ],
            "description": "Auto Reload settings if configured"
          },
          "top_up_url": {
            "type": "string",
            "title": "Top Up Url",
            "description": "URL to purchase more credits",
            "default": "https://happenstance.ai/integrations/keys"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "balance_credits",
          "has_credits",
          "purchases",
          "usage"
        ],
        "title": "GetUsageResponseV1",
        "description": "Response from GET /v1/usage - retrieving user's credit purchases and usage history."
      },
      "GroupMemberV1": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Member's name"
          },
          "connections_count": {
            "type": "integer",
            "title": "Connections Count",
            "description": "How many connections the member has added (refreshed every few minutes). A member with none adds nobody to group searches.",
            "default": 0
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "name"
        ],
        "title": "GroupMemberV1",
        "description": "A member of a group. Use member names as @mentions in search queries to filter results to their connections."
      },
      "GroupV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the group"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Name of the group"
          },
          "supports_mutuals": {
            "type": "boolean",
            "title": "Supports Mutuals",
            "description": "Whether this group supports mutual connection lookups. False for directories and groups without an organization."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "name",
          "supports_mutuals"
        ],
        "title": "GroupV1"
      },
      "HobbyV1": {
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description",
            "description": "Description of the hobby or interest"
          },
          "urls": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Urls",
            "description": "Related URLs (blog, portfolio, etc.)"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "HobbyV1",
        "description": "Hobby or personal interest"
      },
      "PersonMetadataV1": {
        "properties": {
          "full_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Full Name",
            "description": "Primary full name of the person"
          },
          "alternate_names": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Alternate Names",
            "description": "List of alternate names, nicknames, or aliases"
          },
          "profile_urls": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Profile Urls",
            "description": "URLs to online profiles (LinkedIn, Twitter, etc.)"
          },
          "current_locations": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/CurrentLocationV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Locations",
            "description": "Current location(s) of the person"
          },
          "tagline": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tagline",
            "description": "Professional tagline or headline"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "PersonMetadataV1",
        "description": "Metadata about a person"
      },
      "ProblemDetailV1": {
        "properties": {
          "type": {
            "type": "string",
            "title": "Type",
            "description": "A URI reference that identifies the problem type",
            "default": "https://developer.happenstance.ai/api-reference/introduction#error-response-format"
          },
          "title": {
            "type": "string",
            "title": "Title",
            "description": "A short, human-readable summary of the problem"
          },
          "status": {
            "type": "integer",
            "title": "Status",
            "description": "The HTTP status code"
          },
          "detail": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Detail",
            "description": "A human-readable explanation specific to this occurrence"
          },
          "instance": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Instance",
            "description": "A URI reference that identifies the specific occurrence of the problem"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "title",
          "status"
        ],
        "title": "ProblemDetailV1",
        "description": "RFC 7807 Problem Details for HTTP APIs"
      },
      "ProfileV1": {
        "properties": {
          "person_metadata": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PersonMetadataV1"
              },
              {
                "type": "null"
              }
            ],
            "description": "Basic metadata about the person"
          },
          "employment": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/EmploymentV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Employment",
            "description": "Employment history"
          },
          "education": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/EducationV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Education",
            "description": "Education history"
          },
          "projects": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/ProjectV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Projects",
            "description": "Projects and achievements"
          },
          "writings": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/WritingV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Writings",
            "description": "Writings and publications"
          },
          "hobbies": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/HobbyV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Hobbies",
            "description": "Hobbies and personal interests"
          },
          "summary": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/SummaryV1"
              },
              {
                "type": "null"
              }
            ],
            "description": "Comprehensive summary of the person's profile"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "ProfileV1",
        "description": "Complete profile of a researched person"
      },
      "ProjectV1": {
        "properties": {
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title",
            "description": "Title of the project"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description",
            "description": "Description of the project and achievements"
          },
          "start_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Start Date",
            "description": "Start date (YYYY-MM-DD format)"
          },
          "end_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "End Date",
            "description": "End date (YYYY-MM-DD format)"
          },
          "urls": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Urls",
            "description": "Related URLs (project website, GitHub, etc.)"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "ProjectV1",
        "description": "Project or achievement"
      },
      "ResearchRequestV1": {
        "properties": {
          "description": {
            "type": "string",
            "title": "Description",
            "description": "Description of the person to research"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "description"
        ],
        "title": "ResearchRequestV1"
      },
      "SearchMutualRefV1": {
        "properties": {
          "index": {
            "type": "integer",
            "title": "Index",
            "description": "Index into the top-level mutuals array"
          },
          "affinity_score": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Affinity Score",
            "description": "Affinity score indicating connection strength between the mutual and this person. Higher values indicate stronger connections."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "index"
        ],
        "title": "SearchMutualRefV1",
        "description": "Reference to a mutual with result-specific affinity score"
      },
      "SearchMutualV1": {
        "properties": {
          "index": {
            "type": "integer",
            "title": "Index",
            "description": "Index of this mutual in the mutuals array"
          },
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the mutual connection"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Name of the mutual connection"
          },
          "happenstance_url": {
            "type": "string",
            "title": "Happenstance Url",
            "description": "URL to the mutual's Happenstance profile"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "index",
          "id",
          "name",
          "happenstance_url"
        ],
        "title": "SearchMutualV1",
        "description": "A mutual connection who can introduce you to search results (normalized, top-level)"
      },
      "SearchPersonV1": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Unique identifier for the person"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Person's name"
          },
          "weighted_traits_score": {
            "type": "number",
            "title": "Weighted Traits Score",
            "description": "Overall relevance score based on trait evaluations. Calculated as sum of trait scores minus penalties for traits scored zero. Can be negative."
          },
          "current_title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Title",
            "description": "Current job title"
          },
          "current_company": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Company",
            "description": "Current company"
          },
          "summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Summary",
            "description": "AI-generated summary of why this person matches"
          },
          "socials": {
            "$ref": "#/components/schemas/SocialsV1",
            "description": "Profile URLs"
          },
          "mutuals": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/SearchMutualRefV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Mutuals",
            "description": "References to mutual connections (indices into top-level mutuals array)"
          },
          "traits": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/SearchTraitScoreV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Traits",
            "description": "Trait scores for this person (indices into top-level traits array)"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "name",
          "weighted_traits_score",
          "socials"
        ],
        "title": "SearchPersonV1",
        "description": "Individual search result representing a person"
      },
      "SearchRequestV1": {
        "properties": {
          "text": {
            "type": "string",
            "title": "Text",
            "description": "Search query text. Use @mentions to filter results to a specific person's connections (e.g., 'engineers @Jane Smith knows')."
          },
          "group_ids": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Group Ids",
            "description": "List of group IDs to search within."
          },
          "include_friends_connections": {
            "type": "boolean",
            "title": "Include Friends Connections",
            "description": "Search across your friends' connections",
            "default": false
          },
          "include_my_connections": {
            "type": "boolean",
            "title": "Include My Connections",
            "description": "Search across your own connections",
            "default": false
          },
          "search_everyone": {
            "type": "boolean",
            "title": "Search Everyone",
            "default": false
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "text"
        ],
        "title": "SearchRequestV1"
      },
      "SearchTraitScoreV1": {
        "properties": {
          "index": {
            "type": "integer",
            "title": "Index",
            "description": "Index into the top-level traits array"
          },
          "score": {
            "type": "number",
            "title": "Score",
            "description": "Score for this trait (0, 0.5, or 1)"
          },
          "evidence": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Evidence",
            "description": "Supporting quote or citation from the person's profile"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "index",
          "score"
        ],
        "title": "SearchTraitScoreV1",
        "description": "Reference to a trait with result-specific score and evidence"
      },
      "SearchTraitV1": {
        "properties": {
          "index": {
            "type": "integer",
            "title": "Index",
            "description": "Index of this trait in the traits array"
          },
          "header": {
            "type": "string",
            "title": "Header",
            "description": "Short label for the trait (e.g., 'Undergrad')"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description",
            "description": "Full trait description explaining what was evaluated"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "index",
          "header"
        ],
        "title": "SearchTraitV1",
        "description": "A trait definition (normalized, top-level)"
      },
      "SendChatMessageRequestV1": {
        "properties": {
          "message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Message",
            "description": "The message to send, in plain text. While Chat waits on its questions (a turn with stop_reason needs_input), a message answers them in words."
          },
          "answers": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/ChatAnswerV1"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Answers",
            "description": "Answers to Chat's open questions, one per question you answer. Send answers, a message, or both (the message then adds to the answers)."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "SendChatMessageRequestV1"
      },
      "SendChatMessageResponseV1": {
        "properties": {
          "chat_id": {
            "type": "string",
            "title": "Chat Id",
            "description": "The chat's id"
          },
          "url": {
            "type": "string",
            "title": "Url",
            "description": "The chat in the Happenstance app"
          },
          "turn_id": {
            "type": "string",
            "title": "Turn Id",
            "description": "The turn to poll: the one this message started, or the running turn it joined"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "cancelled"
            ],
            "title": "Status",
            "description": "The turn's status"
          },
          "joined": {
            "type": "boolean",
            "title": "Joined",
            "description": "True when the message joined the turn that was still running: Chat takes it into that turn's work, and the turn's reply and charge cover both messages",
            "default": false
          },
          "answered": {
            "type": "boolean",
            "title": "Answered",
            "description": "True when the message or answers answered Chat's open questions",
            "default": false
          },
          "warning": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Warning",
            "description": "Warning message when credit balance is low"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "chat_id",
          "url",
          "turn_id",
          "status"
        ],
        "title": "SendChatMessageResponseV1",
        "description": "Response from POST /v1/chat/{chat_id}/messages."
      },
      "SocialsV1": {
        "properties": {
          "happenstance_url": {
            "type": "string",
            "title": "Happenstance Url",
            "description": "URL to the person's Happenstance profile"
          },
          "linkedin_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Linkedin Url",
            "description": "LinkedIn profile URL"
          },
          "twitter_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Twitter Url",
            "description": "Twitter/X profile URL"
          },
          "instagram_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Instagram Url",
            "description": "Instagram profile URL"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "happenstance_url"
        ],
        "title": "SocialsV1",
        "description": "Profile URLs for a person"
      },
      "SummaryV1": {
        "properties": {
          "text": {
            "type": "string",
            "title": "Text",
            "description": "Combined summary text"
          },
          "urls": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Urls",
            "description": "Deduplicated URLs supporting the summary"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "text"
        ],
        "title": "SummaryV1",
        "description": "Comprehensive summary of the person's profile"
      },
      "UserSourceV1": {
        "properties": {
          "source": {
            "type": "string",
            "title": "Source",
            "description": "LinkedIn, Gmail, Google Contacts, Google Calendar, Outlook, Apple Contacts, Instagram or Twitter"
          },
          "account": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Account",
            "description": "The connected account (an email), for sign-in sources"
          },
          "stage": {
            "type": "string",
            "title": "Stage",
            "description": "ready, importing (first import), refreshing, uploading, needs_reconnect, failed, ..."
          },
          "connections": {
            "type": "integer",
            "title": "Connections",
            "description": "People this source brought into the network"
          },
          "last_synced_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Synced At",
            "description": "When its connections last finished importing (ISO 8601)"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "source",
          "stage",
          "connections"
        ],
        "title": "UserSourceV1",
        "description": "A data source the user connected, whose people are searchable."
      },
      "UserV1": {
        "properties": {
          "email": {
            "type": "string",
            "title": "Email",
            "description": "User's email address"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "User's name"
          },
          "friends": {
            "items": {
              "$ref": "#/components/schemas/FriendV1"
            },
            "type": "array",
            "title": "Friends",
            "description": "List of the user's friends"
          },
          "friends_count": {
            "type": "integer",
            "title": "Friends Count",
            "description": "How many Happenstance friends the user has",
            "default": 0
          },
          "connections_count": {
            "type": "integer",
            "title": "Connections Count",
            "description": "How many people the user's own connected sources hold (their own connections, searchable by them and their friends)",
            "default": 0
          },
          "sources": {
            "items": {
              "$ref": "#/components/schemas/UserSourceV1"
            },
            "type": "array",
            "title": "Sources",
            "description": "The user's connected sources, newest activity first. Empty means the user hasn't added their own connections, so searches cover only friends' and groups'."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "email",
          "name",
          "friends"
        ],
        "title": "UserV1",
        "description": "Response from GET /v1/users/me - retrieving the current user's profile."
      },
      "ValidateKeyResponseV1": {
        "properties": {
          "valid": {
            "type": "boolean",
            "title": "Valid",
            "description": "Whether the API key is valid"
          },
          "user_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "User Id",
            "description": "User ID associated with the API key"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "valid"
        ],
        "title": "ValidateKeyResponseV1"
      },
      "WritingV1": {
        "properties": {
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title",
            "description": "Title of the writing or publication"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description",
            "description": "Summary or description of the content"
          },
          "date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Date",
            "description": "Publication date (YYYY-MM-DD format)"
          },
          "urls": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Urls",
            "description": "URLs to the publication"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "WritingV1",
        "description": "Writing or publication"
      }
    },
    "securitySchemes": {
      "HTTPBearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "servers": [
    {
      "url": "https://api.happenstance.ai",
      "description": "Production"
    }
  ]
}

View source