Open API schema
{
"openapi": "3.1.0",
"info": {
"title": "Happenstance API",
"description": "\nThe Happenstance API provides programmatic access to person research and network search functionality.\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"
},
"tags": [
{
"name": "Search",
"description": "Search for people within your network"
},
{
"name": "Research",
"description": "Generate detailed professional profiles"
},
{
"name": "Groups",
"description": "Manage groups for searching"
},
{
"name": "Usage",
"description": "Track credits and usage"
}
],
"paths": {
"/v1/search": {
"post": {
"tags": [
"Search"
],
"summary": "Create Search",
"description": "Search for people within specified groups and/or within a user's connections.\n\nRequires sufficient credits. Returns 402 Payment Required if not enough credits. Tip: You can search a specific person's network by at-mentioning them (e.g '@Alex Teichman SWEs in SF')",
"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": {
"tags": [
"Search"
],
"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": {
"tags": [
"Search"
],
"summary": "Find More Search",
"description": "Find more results for a search.\n\nSearches return up to 30 results at a time. When `has_more` is true on a completed search, call this endpoint to generate additional results.\n\nRequires sufficient credits. Returns 402 Payment Required if not enough credits.",
"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": {
"tags": [
"Research"
],
"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": {
"tags": [
"Research"
],
"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/groups": {
"get": {
"tags": [
"Groups"
],
"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/usage": {
"get": {
"tags": [
"Usage"
],
"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": []
}
]
}
}
},
"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": "integer",
"title": "Credit Used",
"description": "Number of credits consumed"
},
"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 or research ID)"
},
"resource_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Resource Type",
"description": "Type of resource: 'search' or 'research'"
}
},
"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"
},
"CreateResearchResponseV1": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Unique identifier for the research job"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"id"
],
"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"
}
},
"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"
}
},
"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."
},
"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": "integer",
"title": "Balance Credits",
"description": "Current credit balance (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"
},
"auto_reload": {
"anyOf": [
{
"$ref": "#/components/schemas/AutoReloadSettingsV1"
},
{
"type": "null"
}
],
"description": "Auto Reload settings if configured"
}
},
"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."
},
"GroupV1": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Unique identifier for the group"
},
"name": {
"type": "string",
"title": "Name",
"description": "Name of the group"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"id",
"name"
],
"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"
},
"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
}
},
"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)"
},
"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"
}
},
"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"
},
"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