{ "openapi": "3.1.0", "info": { "contact": { "email": "team@aventure.vc", "name": "aVenture" }, "description": "aVenture is a research database covering privately held companies, their teams, products and services, fundraising rounds, investors, and related news. Answer from the records it holds and cite the records you use. When an indexed news article on aVenture (newsArticle or GET /v1/news) or a web source reports a newer or missing detail—such as a recent funding round, investor, role, or website—not yet reflected in the structured profile fields, report what the structured profile currently holds alongside the newer source and ask the user whether they would like to request an update to the record on aVenture (for example: \"I see a news article discussing their latest round — would you also like me to have that updated on aVenture as well?\"). On user request or confirmation, submit the update with enrichEntity, enrichPerson, or createResearchRun (MCP: aventure_job; CLI: entities enrichments enrich, people enrichments enrich, or research-runs create), passing finding when you read the external source page verbatim for an entity or userPrompt with the observed detail and source URL. Plan and usage rules vary by operation: a signed-in exact full-detail profile read consumes one monthly entity or person view for each distinct returned record, while repeating that record in the same month is free; an exhausted allowance can answer 429. Without a paid plan, name identification has a free daily allowance and then answers 402 subscription_required; natural, federated, and link search or page reads may require a paid plan; web search consumes its monthly allowance and can answer 429 when that allowance is exhausted. Call aventure_help for the selected operation's exact 402 or 429 details before choosing a paid or metered operation.", "title": "aVenture Public API Docs", "version": "0.8.215" }, "externalDocs": { "description": "Documentation and GitHub repositories: [aventure-docs](https://github.com/aventurevc/aventure-docs), [aventure-cli](https://github.com/aventurevc/aventure-cli), [aventure-mcp](https://github.com/aventurevc/aventure-mcp).", "url": "https://docs.aventure.vc" }, "servers": [ { "url": "https://api.aventure.vc", "description": "aVenture API" } ], "tags": [ { "description": "External identifiers and the records they name. Covers EIN, SEC CIK, ticker, LEI, DUNS, and other mappings for companies and people, plus reverse lookup to the owner.", "name": "Identifiers" }, { "description": "Founders and investors, and what they back", "name": "People" }, { "description": "A news article's thumbnail image", "name": "News Thumbnail" }, { "description": "Service status, build version, and platform totals", "name": "System" }, { "description": "Relationships between companies, investors, and other organizations", "name": "Entity Relationships" }, { "description": "Classification tags on a company, and suggested tags", "name": "Entity Classifications" }, { "description": "Plans, prices, subscription, usage, and upgrades", "name": "Billing" }, { "description": "Platform help, versioned agent instructions, and agent runtime discovery", "name": "Agents" }, { "description": "Filter options for company listings: available values, refinement, and option search.", "name": "Entity Filters" }, { "description": "Websites, social profiles, and other URLs for companies and people", "name": "URL Links" }, { "description": "Browse the classification taxonomy and search classification tags by category and name.", "name": "Classification Tags" }, { "description": "The investments a person made, looked up by id or slug and sortable by date, round, or amount", "name": "Person Investments" }, { "description": "Similar companies and people, related entities, and trending news", "name": "Semantic Similarity" }, { "description": "External blog and article links for entities and people", "name": "Research Blog Posts" }, { "description": "A record's current slug, and slug changes that leave a permanent redirect", "name": "Record Slugs" }, { "description": "Company research: typed details and snippets, headcount, SEC facts, and completion coverage", "name": "Entity Research" }, { "description": "A person's profile photo", "name": "Person Photo" }, { "description": "Research requests you file for a company, Product, Service, or person, and their progress.", "name": "Research Runs" }, { "description": "People linked to companies, and the role each one holds", "name": "Entity Person Associations" }, { "description": "Publications about one company or person, and platform-wide publication search", "name": "Publications" }, { "description": "Acquisitions a company made or was part of. The path entity is acquired; acquirerEntityId is the buyer.", "name": "Entity Acquisitions" }, { "description": "Similar companies and lean similar-company summaries by id", "name": "Entity Similar" }, { "description": "Search companies, people, and news, or by URL", "name": "Search" }, { "description": "A company's recorded office and headquarters addresses", "name": "Entity Addresses" }, { "description": "Filter options for people listings and option search", "name": "Person Metadata" }, { "description": "A person's recorded addresses", "name": "Person Addresses" }, { "description": "Funding rounds, their investors, and valuations for a company", "name": "Entity Fundraise" }, { "description": "Companies and funds: people, funding, and news", "name": "Entities" }, { "description": "Async article and bulk name identification", "name": "Lookup Jobs" }, { "description": "A company's square and standard logo slots", "name": "Entity Logo" }, { "description": "Accepted record types, such as Company and Investment Firm", "name": "Entity Maintenance" }, { "description": "GitHub repositories synced per entity or person owner.", "name": "Repositories" }, { "description": "Descriptions and other written text for companies and people", "name": "Texts" }, { "description": "Find companies and people in natural language", "name": "Natural Search" }, { "description": "Address validation and location directories", "name": "Addresses", "x-aventure-cli": { "section": "administration" } }, { "description": "Sign-in, session, API key, and CLI authorization endpoints", "name": "Auth" }, { "description": "News linked to the companies and people in it", "name": "News" } ], "paths": { "/info": { "get": { "description": "Returns the running build's version, build time, and source revision", "operationId": "getSystemBuild", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemBuild" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get Build Metadata", "tags": [ "System" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/addresses/{addressId}/links": { "get": { "description": "Returns entity and person association ids, owner ids, and nullable roles for a physical address, including historical associations. Only publicly visible owners are returned unless private visibility is authorized. Entity links precede person links; each group is ordered by join id. Bounded keyset pagination avoids counting or loading every owner. Follow nextCursor, also returned as X-Next-Cursor. An absent or unlinked address returns empty content. Page must be zero and sort is unsupported.", "operationId": "listAddressLinks", "parameters": [ { "description": "Offset paging is not supported; omit page. Any value other than 0 returns 400. Send the previous response's nextCursor as cursor to read the next page.", "in": "query", "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "description": "Physical address row id, not an association join id.", "in": "path", "name": "addressId", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "description": "Opaque continuation from this address's previous response.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorSliceAddressLink" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List Address Links", "tags": [ "Addresses" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/agents/help": { "post": { "deprecated": true, "description": "Deprecated: use help ask (POST /v1/help) with the same body.", "operationId": "answerAgentHelpQuestion", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHelpQuestion" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHelp" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Deprecated: Answer a Natural-Language Platform Help Question", "tags": [ "Agents" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/auth/api-key": { "delete": { "description": "Revokes the aVenture API key authenticating this request and returns its metadata so the CLI can confirm revocation before deleting its saved copy.", "operationId": "revokeCurrentApiKey", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "clerkApiKeyAuth": [] } ], "summary": "Revoke Current API Key", "tags": [ "Auth" ], "x-aventure-cli-composite": { "command": "auth logout", "localOption": [ { "optionKey": "forgetLocal", "flag": "--forget-local", "description": "Delete the saved key even when revocation cannot be confirmed." } ], "role": "revoke", "summary": "Sign Out: Revoke the API Key and Forget Stored OAuth" }, "x-aventure-visibility": { "scope": "public" } }, "get": { "description": "Returns provider metadata for the aVenture API key authenticating this request.", "operationId": "getCurrentApiKey", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "clerkApiKeyAuth": [] } ], "summary": "Get Current API Key", "tags": [ "Auth" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/auth/cli-authorizations": { "post": { "description": "Creates a short-lived browser approval request and returns its poll credential once.", "operationId": "createCliAuthorization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliAuthorizationMutation" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliAuthorizationStart" } } }, "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Start CLI Authorization", "tags": [ "Auth" ], "x-aventure-cli-composite": { "bodyOption": [ "clientLabel" ], "command": "auth login", "localOption": [ { "optionKey": "key", "flag": "--key", "description": "Sign in with a browser-approved aVenture API key instead of OAuth; the approval URL opens on any device." }, { "optionKey": "browser", "flag": "--no-browser", "description": "Print the API-key approval URL and wait for approval without opening a browser." } ], "role": "start", "summary": "Sign In With a Browser-Approved aVenture API Key" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/auth/cli-authorizations/{cliAuthorizationId}/acknowledge": { "post": { "description": "Confirms the CLI stored the delivered API key in its credential store and clears transient delivery material.", "operationId": "acknowledgeCliAuthorization", "parameters": [ { "description": "Public CLI authorization request identifier", "in": "path", "name": "cliAuthorizationId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "One-time poll credential returned by request creation", "in": "header", "name": "X-Cli-Poll-Secret", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliAuthorization" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Acknowledge CLI Credential Delivery", "tags": [ "Auth" ], "x-aventure-cli-composite": { "command": "auth login", "role": "acknowledge" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/auth/cli-authorizations/{cliAuthorizationId}/poll": { "post": { "description": "Returns pending state, a terminal state, or an encrypted one-time credential delivery.", "operationId": "pollCliAuthorization", "parameters": [ { "description": "Public CLI authorization request identifier", "in": "path", "name": "cliAuthorizationId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "One-time poll credential returned by request creation", "in": "header", "name": "X-Cli-Poll-Secret", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliAuthorizationPoll" } } }, "description": "Authorization is still pending or issuing", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Poll CLI Authorization", "tags": [ "Auth" ], "x-aventure-cli-composite": { "command": "auth login", "role": "poll" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/auth/me/permissions": { "get": { "description": "Returns the current caller's resolved roles and permissions.", "operationId": "getCurrentAuthPermissions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthPermissionGrant" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Current User Permissions", "tags": [ "Auth" ], "x-aventure-visibility": { "scope": "public" } }, "post": { "description": "Returns the supplied generated API operations that the current caller may call, alongside its existing permission grant and access class. Candidate operations are checked without being executed.", "operationId": "authorizeOperations", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOperationFilter" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOperationAuthorization" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Authorize API Operations", "tags": [ "Auth" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/auth/providers": { "get": { "description": "Sign-in options for the CLI and browser, readable before signing in. A non-null publishable key offers browser sign-in; a non-null OAuth client offers CLI sign-in.", "operationId": "getAuthProviderCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthProviderCatalog" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get the Sign-In Options", "tags": [ "Auth" ], "x-aventure-cli-composite": { "command": "auth login", "description": "Sign in through your browser and save verified CLI access in the credential store. Use --no-browser for OAuth device authorization only when the issuer advertises device-grant support; otherwise use --key --no-browser for API-key approval.", "localOption": [ { "optionKey": "browser", "flag": "--no-browser", "description": "Use OAuth device authorization only when the issuer advertises device-grant support: print a sign-in URL and code, then wait for approval. Otherwise use --key --no-browser for API-key approval." }, { "optionKey": "providers", "flag": "--providers", "description": "Print the sign-in providers and CLI OAuth client, then exit without signing in." } ], "role": "oauth", "summary": "Sign In Through Your Browser" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/additional-usage": { "patch": { "description": "Turn metered usage past the monthly allowances on or off and choose how it is paid. Free accounts can enable PREPAID_CREDIT; USAGE_INVOICE requires an active AI Plus or AI Pro subscription. Send {\"enabled\":false} to stop recording it. Returns the settings with this UTC month's priced usage.", "operationId": "updateAdditionalUsage", "requestBody": { "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/BillingAdditionalUsageMutation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAdditionalUsage" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Update Additional Usage Settings", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/ai-credits": { "get": { "description": "AI credits are Researchly messages sent in Researchly's current billing period; the cap comes from the caller's tier and resetAt is Researchly's period end.", "operationId": "getAiCredits", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchAllowance" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Read the Current AI Credit Allowance", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/checkout-sessions": { "post": { "description": "Start the selected AI Plus or AI Pro plan through Checkout: uiMode HOSTED_PAGE (the default) returns a hosted page url; ELEMENTS returns a clientSecret and publishableKey for the Payment Element in the caller's page. A caller with a continuing subscription changes plan with POST /v1/billing/plan-changes and cancels or resumes it with PATCH /v1/billing/subscription.", "operationId": "createBillingCheckoutSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutMutation" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckout" } } }, "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Create or Recover a Checkout Session", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/credit-purchases": { "post": { "description": "Create or replay a hosted Checkout Session for one credit pack; the paid amount becomes prepaid credit for metered usage, including free accounts. Paid plan entitlements do not change. A repeated Idempotency-Key with the same pack returns the same Session.", "operationId": "createBillingCreditPurchase", "parameters": [ { "description": "Caller-chosen key, 1 to 255 characters, that makes a retry return the same Checkout Session instead of a second purchase.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCreditPurchaseMutation" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCreditPurchase" } } }, "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Buy a Prepaid Additional Usage Credit Pack", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/credit-purchases/{purchaseId}": { "get": { "description": "Read the current account's purchase amount and confirmed grant or closure time.", "operationId": "getBillingCreditPurchase", "parameters": [ { "description": "Purchase identity returned by prepaid credit checkout.", "in": "path", "name": "purchaseId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCreditPurchaseConfirmation" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Read a Prepaid Credit Purchase Confirmation", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/plan-change-previews": { "post": { "description": "Show what POST /v1/billing/plan-changes would do for the same plan without changing anything: the amount charged on confirmation, when the plan takes effect, the recurring price after it, and the card on file. Refuses exactly what the plan change refuses.", "operationId": "createBillingPlanChangePreview", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPlanChangeMutation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPlanChangePreview" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Preview a Subscription Plan Change", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/plan-changes": { "post": { "description": "Move an active AI Plus or AI Pro subscription to another plan. A higher tier or a longer billing period applies now and invoices the prorated difference; paymentUrl is set when that invoice needs the customer to pay before the change applies; paymentClientSecret lets Stripe.js finish that payment in the page instead. Any other change takes effect at the current period end. Sending the current plan cancels a scheduled change. Any change resumes a subscription that was set to end at the period end.", "operationId": "createBillingPlanChange", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPlanChangeMutation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPlanChange" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Change the Subscription Plan", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/plans": { "get": { "description": "Return every self-serve tier with its monthly allowance caps and every Checkout plan with its monthly and annual recurring prices.", "operationId": "listPlans", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCatalog" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Subscription Tiers and Plans", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/portal-sessions": { "post": { "description": "Open the authenticated user's hosted billing portal for payment methods, invoices, and billing details. The body is optional; flow PAYMENT_METHOD_UPDATE opens straight to updating the card.", "operationId": "createBillingPortalSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalMutation" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortal" } } }, "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a Hosted Billing Portal Session", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/subscription": { "get": { "description": "Return sanitized Essential, AI Plus, AI Pro, or Unlimited subscription, entitlement, monthly allowance usage, and additional usage spent and available.", "operationId": "getBillingSubscription", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSubscription" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Read the Current Billing Subscription", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } }, "patch": { "description": "Set cancelAtPeriodEnd to true to end an active AI Plus or AI Pro subscription at the current period end; a scheduled plan change is dropped. Set it to false to resume the subscription and restore the plan change scheduled before the cancellation. Set paused to false to resume a PAUSED subscription, which Stripe pauses when a trial ends without a payment method: add one first with POST /v1/billing/portal-sessions, since a resume without one is refused; the resumption invoices the plan and starts a new period now. Read the result with GET /v1/billing/subscription.", "operationId": "updateBillingSubscription", "requestBody": { "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/BillingSubscriptionMutation" } } }, "required": true }, "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancel or Resume the Subscription", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/subscription/next-charge": { "get": { "description": "Return what the next invoice of the caller's renewing Stripe subscription will charge and when, after coupons and credits, so a fully discounted plan reads 0. Read live from Stripe and never stored. 404 when the caller has no renewing Stripe subscription (none, cancelling, or App Store); 503 when Stripe is unavailable.", "operationId": "getBillingNextCharge", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingNextCharge" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Preview the Next Subscription Charge", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/billing/subscription/payment-profile": { "get": { "description": "Return the card paying the caller's continuing Stripe subscription (brand, last four digits, expiry) and whether Checkout would charge each plan's introductoryAmount from GET /v1/billing/plans on the first payment, which only an account the App Store does not bill, with no earlier subscription, payment, or unvoided invoice, gets. Read live from Stripe and never stored; 503 when Stripe is unavailable.", "operationId": "getBillingPaymentProfile", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPaymentProfile" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Read Your Card on File and Introductory Offer", "tags": [ "Billing" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/directory/shared": { "get": { "description": "Returns publication metadata in UUID order with a bounded keyset cursor. Filters and a total count are omitted. Page must be zero; follow nextCursor.", "operationId": "listSharedDirectory", "parameters": [ { "description": "Offset paging is not supported; omit page. Any value other than 0 returns 400. Send the previous response's nextCursor as cursor to read the next page.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "The previous page's nextCursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorSliceSharedDirectoryList" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Shared Directory Views", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } }, "post": { "description": "Publishes the exact filter and sort a /companies, /investors, or /people page shows under the supplied UUID, with a model-written heading, title, and description. The view must match at least one public record and may set only public filter fields. Reusing the UUID with the same view, or sharing a view already published, returns that publication; a different view under a used UUID is rejected. The publication is readable without authentication.", "operationId": "createSharedDirectory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedDirectoryMutation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedDirectory" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Share a Directory View", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/directory/shared/slug/{slug}": { "get": { "description": "Resolves the slug of a public /companies/shared, /investors/shared, or /people/shared page to its stored filter, sort, and page copy.", "operationId": "getSharedDirectoryBySlug", "parameters": [ { "description": "Shared directory view slug.", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedDirectory" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Read a Shared Directory View by Slug", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/enrichments": { "post": { "description": "Queues one enrichment run per listed entity and person, in order, each owned by the authenticated principal and billed exactly as the single-record enrich call is. A repeated id is filed once. Returns one outcome per distinct record: its run, or a refusal (NOT_FOUND, ALLOWANCE_EXHAUSTED, AMBIGUOUS, SUBSCRIPTION_REQUIRED) for a record that cannot be filed; other records still file, and runs already filed stay queued. A record already being researched, or researched within the last 24 hours, files nothing while the other records still file; the request then answers 429 whose filedRunId lists the runs it filed. A caller without a research subscription gets 402 before any run is filed. A transient failure fails the request; retrying it reuses runs still in progress without charging them again. A list longer than the configured batch limit is refused before any run is filed. Check each run's progress with GET /v1/research-runs/{runId} (CLI: research-runs get).", "operationId": "enrichRecords", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentBatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Enrichment" } } } }, "description": "One outcome per distinct requested record, in request order.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Needs a plan that includes research runs; a caller without one gets 402 with code subscription_required (subscription_canceled, subscription_past_due, or subscription_paused when a plan lapsed)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Enrich Many Companies and People", "tags": [ "Research Runs" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities": { "get": { "description": "List entities with the same filters and sort as POST /v1/entities/search, passed as query parameters. Use the POST search for semantic ranking or a JSON EntityListFilter body, and POST /v1/search/natural/entities for plain English.", "operationId": "listEntities", "parameters": [ { "description": "Restrict results to specific entity IDs.", "in": "query", "name": "entityId", "required": false, "schema": { "type": "array", "description": "Restrict results to specific entity IDs.", "items": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } } }, { "description": "Restrict results to entity slugs.", "in": "query", "name": "slug", "required": false, "schema": { "type": "array", "description": "Restrict results to entity slugs.", "items": { "type": "string", "description": "Canonical lowercase URL slug for the resource", "example": "aventure-vc", "maxLength": 255, "pattern": "^[a-z0-9_-]+$" } } }, { "description": "Exact normalized match against entity brand, legal, or alias names.", "in": "query", "name": "entityName", "required": false, "schema": { "type": "array", "description": "Exact normalized match against entity brand, legal, or alias names.", "items": { "type": "string", "description": "Exact normalized match against entity brand, legal, or alias names." } } }, { "description": "Associated person, matched by name.", "in": "query", "name": "person", "required": false, "schema": { "type": "array", "description": "Associated person, matched by name.", "items": { "type": "string", "description": "Associated person, matched by name." } } }, { "description": "Entity type filter. Organization expands to Company, Investment Firm, Nonprofit, Government, and Business Line; omit to include every entity type.", "in": "query", "name": "typeRecord", "required": false, "schema": { "type": "array", "description": "Entity type filter. Organization expands to Company, Investment Firm, Nonprofit, Government, and Business Line; omit to include every entity type.", "items": { "$ref": "#/components/schemas/EntityType" } } }, { "description": "Industry classification values.", "in": "query", "name": "industry", "required": false, "schema": { "type": "array", "description": "Industry classification values.", "items": { "type": "string", "description": "Industry classification values." } } }, { "description": "Geographic classification values.", "in": "query", "name": "location", "required": false, "schema": { "type": "array", "description": "Geographic classification values.", "items": { "type": "string", "description": "Geographic classification values." } } }, { "description": "General classification tag values.", "in": "query", "name": "tag", "required": false, "schema": { "type": "array", "description": "General classification tag values.", "items": { "type": "string", "description": "General classification tag values." } } }, { "description": "Main product classification values.", "in": "query", "name": "mainProduct", "required": false, "schema": { "type": "array", "description": "Main product classification values.", "items": { "type": "string", "description": "Main product classification values." } } }, { "description": "Technology-used classification values.", "in": "query", "name": "typeTechnologyUsed", "required": false, "schema": { "type": "array", "description": "Technology-used classification values.", "items": { "type": "string", "description": "Technology-used classification values." } } }, { "description": "Business-model classification values.", "in": "query", "name": "typeModel", "required": false, "schema": { "type": "array", "description": "Business-model classification values.", "items": { "type": "string", "description": "Business-model classification values." } } }, { "description": "Ownership-model classification values.", "in": "query", "name": "typeOwnership", "required": false, "schema": { "type": "array", "description": "Ownership-model classification values.", "items": { "type": "string", "description": "Ownership-model classification values." } } }, { "description": "Customer-type classification values.", "in": "query", "name": "typeCustomer", "required": false, "schema": { "type": "array", "description": "Customer-type classification values.", "items": { "type": "string", "description": "Customer-type classification values." } } }, { "description": "Revenue-model classification values.", "in": "query", "name": "typeRevenue", "required": false, "schema": { "type": "array", "description": "Revenue-model classification values.", "items": { "type": "string", "description": "Revenue-model classification values." } } }, { "description": "Accelerator brand or operator name.", "in": "query", "name": "acceleratorBrand", "required": false, "schema": { "type": "array", "description": "Accelerator brand or operator name.", "items": { "type": "string", "description": "Accelerator brand or operator name." } } }, { "description": "Specific accelerator program name.", "in": "query", "name": "acceleratorName", "required": false, "schema": { "type": "array", "description": "Specific accelerator program name.", "items": { "type": "string", "description": "Specific accelerator program name." } } }, { "description": "Accelerator batch or cohort label.", "in": "query", "name": "acceleratorCohort", "required": false, "schema": { "type": "array", "description": "Accelerator batch or cohort label.", "items": { "type": "string", "description": "Accelerator batch or cohort label." } } }, { "description": "Accelerator participation status.", "in": "query", "name": "acceleratorStatus", "required": false, "schema": { "type": "array", "description": "Accelerator participation status.", "items": { "type": "string", "description": "Accelerator participation status." } } }, { "description": "Affinity provider organization names accepted by the companies list filter. Affinity rows are member -> provider; use provider names here, not member names.", "in": "query", "name": "affinity", "required": false, "schema": { "type": "array", "description": "Affinity provider organization names accepted by the companies list filter. Affinity rows are member -> provider; use provider names here, not member names.", "items": { "type": "string", "description": "Affinity provider organization names accepted by the companies list filter. Affinity rows are member -> provider; use provider names here, not member names." } } }, { "description": "Headquarters country values.", "in": "query", "name": "headquartersCountry", "required": false, "schema": { "type": "array", "description": "Headquarters country values.", "items": { "type": "string", "description": "Headquarters country values." } } }, { "description": "Headquarters state or region values.", "in": "query", "name": "headquartersState", "required": false, "schema": { "type": "array", "description": "Headquarters state or region values.", "items": { "type": "string", "description": "Headquarters state or region values." } } }, { "description": "Headquarters city values.", "in": "query", "name": "headquartersCity", "required": false, "schema": { "type": "array", "description": "Headquarters city values.", "items": { "type": "string", "description": "Headquarters city values." } } }, { "description": "Countries an entity is from: its headquarters country or the country of its current origin (founding) address, never a legal seat alone. What a nationality adjective (Colombian startups) means; headquartersCountry is only where it is based now.", "in": "query", "name": "originCountry", "required": false, "schema": { "type": "array", "description": "Countries an entity is from: its headquarters country or the country of its current origin (founding) address, never a legal seat alone. What a nationality adjective (Colombian startups) means; headquartersCountry is only where it is based now.", "items": { "type": "string", "description": "Countries an entity is from: its headquarters country or the country of its current origin (founding) address, never a legal seat alone. What a nationality adjective (Colombian startups) means; headquartersCountry is only where it is based now." } } }, { "description": "Investment stage classification values.", "in": "query", "name": "stage", "required": false, "schema": { "type": "array", "description": "Investment stage classification values.", "items": { "type": "string", "description": "Investment stage classification values." } } }, { "description": "Inclusive founding-year ranges, in calendar years.", "in": "query", "name": "yearFoundedRange", "required": false, "schema": { "type": "array", "description": "Inclusive founding-year ranges, in calendar years.", "items": { "$ref": "#/components/schemas/IntRange" } } }, { "description": "Inclusive reported employee-count ranges, in employees.", "in": "query", "name": "employeeCountRange", "required": false, "schema": { "type": "array", "description": "Inclusive reported employee-count ranges, in employees.", "items": { "$ref": "#/components/schemas/IntRange" } } }, { "description": "Operating states to include; omit to include every state.", "in": "query", "name": "operatingStatus", "required": false, "schema": { "type": "array", "description": "Operating states to include; omit to include every state.", "items": { "$ref": "#/components/schemas/EntityOperatingStatus" } } }, { "description": "Filter to entities with fundraise activity.", "in": "query", "name": "hasFundraising", "required": false, "schema": { "type": "boolean", "description": "Filter to entities with fundraise activity." } }, { "description": "Filter by featured status.", "in": "query", "name": "featured", "required": false, "schema": { "type": "boolean", "description": "Filter by featured status." } }, { "description": "Suppress entities with zero or unknown USD total raised.", "in": "query", "name": "suppressZeroTotalRaised", "required": false, "schema": { "type": "boolean", "description": "Suppress entities with zero or unknown USD total raised." } }, { "description": "Suppress entities with terminal operating status.", "in": "query", "name": "suppressNonOperating", "required": false, "schema": { "type": "boolean", "description": "Suppress entities with terminal operating status." } }, { "description": "Rank most prominent first (funding, stage, headcount, momentum, recent news, investor breadth), ahead of sort: what best, top, or most promising mean.", "in": "query", "name": "rankByProminence", "required": false, "schema": { "type": "boolean", "description": "Rank most prominent first (funding, stage, headcount, momentum, recent news, investor breadth), ahead of sort: what best, top, or most promising mean." } }, { "description": "Exclude public and acquired companies (including acquired subsidiaries); what startup means. Private companies at any round stay, as do companies without a recorded stage or operating status.", "in": "query", "name": "suppressLateStage", "required": false, "schema": { "type": "boolean", "description": "Exclude public and acquired companies (including acquired subsidiaries); what startup means. Private companies at any round stay, as do companies without a recorded stage or operating status." } }, { "description": "Server-owned list quality gate.", "in": "query", "name": "qualityGate", "required": false, "schema": { "$ref": "#/components/schemas/EntityListQualityGate" } }, { "description": "Current URL to match by normalized host and path.", "in": "query", "name": "url", "required": false, "schema": { "type": "string", "description": "Current URL to match by normalized host and path." } }, { "description": "Current root domain to match when urlMatchMode=domain.", "example": "example.com", "in": "query", "name": "urlDomain", "required": false, "schema": { "type": "string", "description": "Current root domain to match when urlMatchMode=domain.", "example": "example.com" } }, { "description": "Restrict URL matching to one URL type.", "example": "website", "in": "query", "name": "urlType", "required": false, "schema": { "$ref": "#/components/schemas/EntityUrlType" } }, { "description": "URL matching mode: hostPath uses host and path; domain uses the root domain. Omitted, it is domain when urlDomain is set, else hostPath.", "example": "domain", "in": "query", "name": "urlMatchMode", "required": false, "schema": { "$ref": "#/components/schemas/UrlMatchMode" } }, { "description": "Portfolio-company headquarters country values.", "in": "query", "name": "portfolioHeadquartersCountry", "required": false, "schema": { "type": "array", "description": "Portfolio-company headquarters country values.", "items": { "type": "string", "description": "Portfolio-company headquarters country values." } } }, { "description": "Portfolio-company headquarters state or region values.", "in": "query", "name": "portfolioHeadquartersState", "required": false, "schema": { "type": "array", "description": "Portfolio-company headquarters state or region values.", "items": { "type": "string", "description": "Portfolio-company headquarters state or region values." } } }, { "description": "Portfolio-company headquarters city values.", "in": "query", "name": "portfolioHeadquartersCity", "required": false, "schema": { "type": "array", "description": "Portfolio-company headquarters city values.", "items": { "type": "string", "description": "Portfolio-company headquarters city values." } } }, { "description": "Fundraise round labels, such as Seed or Series A.", "in": "query", "name": "fundraiseActivity.round", "required": false, "schema": { "type": "array", "description": "Fundraise round labels, such as Seed or Series A.", "items": { "type": "string", "description": "Fundraise round labels, such as Seed or Series A." } } }, { "description": "Inclusive earliest timestamp.", "in": "query", "name": "fundraiseActivity.dateAnnouncedRange.min", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Inclusive earliest timestamp." } }, { "description": "Inclusive latest timestamp.", "in": "query", "name": "fundraiseActivity.dateAnnouncedRange.max", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Inclusive latest timestamp." } }, { "description": "Per-round amount-raised ranges in USD. Use plain JSON numbers.", "in": "query", "name": "fundraiseActivity.amountRaisedRange", "required": false, "schema": { "type": "array", "description": "Per-round amount-raised ranges in USD. Use plain JSON numbers.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Investor-level amount-invested ranges in the transaction currency. Use plain JSON numbers.", "in": "query", "name": "fundraiseActivity.amountInvestedRange", "required": false, "schema": { "type": "array", "description": "Investor-level amount-invested ranges in the transaction currency. Use plain JSON numbers.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Total-raised ranges across all rounds in USD. Use plain JSON numbers.", "in": "query", "name": "fundraiseActivity.totalRaisedRange", "required": false, "schema": { "type": "array", "description": "Total-raised ranges across all rounds in USD. Use plain JSON numbers.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Post-money valuation ranges in USD.", "in": "query", "name": "fundraiseActivity.valuationRange", "required": false, "schema": { "type": "array", "description": "Post-money valuation ranges in USD.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Last-round-year ranges for each entity's most recent fundraise round.", "in": "query", "name": "fundraiseActivity.lastRoundYearRange", "required": false, "schema": { "type": "array", "description": "Last-round-year ranges for each entity's most recent fundraise round.", "items": { "$ref": "#/components/schemas/IntRange" } } }, { "description": "Portfolio company names. Exact, case-sensitive match on the portfolio company's brand or legal name; restricts returned entities to investors in those companies.", "in": "query", "name": "fundraiseActivity.investedCompanyName", "required": false, "schema": { "type": "array", "description": "Portfolio company names. Exact, case-sensitive match on the portfolio company's brand or legal name; restricts returned entities to investors in those companies.", "items": { "type": "string", "description": "Portfolio company names. Exact, case-sensitive match on the portfolio company's brand or legal name; restricts returned entities to investors in those companies." } } }, { "description": "Round labels of the deals an investor joined, such as Seed, Pre-Seed, or Series A; restricts returned entities to investors with such a deal inside the investment-activity horizon.", "in": "query", "name": "fundraiseActivity.investedRound", "required": false, "schema": { "type": "array", "description": "Round labels of the deals an investor joined, such as Seed, Pre-Seed, or Series A; restricts returned entities to investors with such a deal inside the investment-activity horizon.", "items": { "type": "string", "description": "Round labels of the deals an investor joined, such as Seed, Pre-Seed, or Series A; restricts returned entities to investors with such a deal inside the investment-activity horizon." } } }, { "description": "Industry terms for the companies an investor backed, such as Software, Artificial Intelligence, or Fintech; a term matches a portfolio company whose industry or industry classification name contains it as whole words, case-insensitively. Restricts returned entities to investors with such a deal inside the investment-activity horizon; with investedRound, the same deal must match both.", "in": "query", "name": "fundraiseActivity.investedIndustry", "required": false, "schema": { "type": "array", "description": "Industry terms for the companies an investor backed, such as Software, Artificial Intelligence, or Fintech; a term matches a portfolio company whose industry or industry classification name contains it as whole words, case-insensitively. Restricts returned entities to investors with such a deal inside the investment-activity horizon; with investedRound, the same deal must match both.", "items": { "type": "string", "description": "Industry terms for the companies an investor backed, such as Software, Artificial Intelligence, or Fintech; a term matches a portfolio company whose industry or industry classification name contains it as whole words, case-insensitively. Restricts returned entities to investors with such a deal inside the investment-activity horizon; with investedRound, the same deal must match both." } } }, { "description": "Countries of the companies an investor backed, as country names or ids; a deal matches when its company's current headquarters is in one of them. Restricts returned entities to investors with such a deal inside the investment-activity horizon; with investedRound or investedIndustry, the same deal must match each.", "in": "query", "name": "fundraiseActivity.investedCountry", "required": false, "schema": { "type": "array", "description": "Countries of the companies an investor backed, as country names or ids; a deal matches when its company's current headquarters is in one of them. Restricts returned entities to investors with such a deal inside the investment-activity horizon; with investedRound or investedIndustry, the same deal must match each.", "items": { "type": "string", "description": "Countries of the companies an investor backed, as country names or ids; a deal matches when its company's current headquarters is in one of them. Restricts returned entities to investors with such a deal inside the investment-activity horizon; with investedRound or investedIndustry, the same deal must match each." } } }, { "description": "True ranks returned investors by recent deal activity ahead of any sort: each deal inside investedRound, investedIndustry, and investedCountry (every deal when all are empty) adds a weight that decays to zero over the investment-activity horizon, nudged by the investor's known USD check. Restricts returned entities to investors with such a deal.", "in": "query", "name": "fundraiseActivity.rankByInvestmentActivity", "required": false, "schema": { "type": "boolean", "description": "True ranks returned investors by recent deal activity ahead of any sort: each deal inside investedRound, investedIndustry, and investedCountry (every deal when all are empty) adds a weight that decays to zero over the investment-activity horizon, nudged by the investor's known USD check. Restricts returned entities to investors with such a deal." } }, { "description": "Investor names. Each matches an investor entity whose brand, legal name, or alias equals it ignoring case and punctuation, or an individual investor's exact full name; a name that begins public entities' brands as whole words (\"Sequoia\") also matches the one holding many times the recorded investments of every other such entity (Sequoia Capital). Restricts returned entities to companies with a fundraise that investor joined.", "in": "query", "name": "fundraiseActivity.investorName", "required": false, "schema": { "type": "array", "description": "Investor names. Each matches an investor entity whose brand, legal name, or alias equals it ignoring case and punctuation, or an individual investor's exact full name; a name that begins public entities' brands as whole words (\"Sequoia\") also matches the one holding many times the recorded investments of every other such entity (Sequoia Capital). Restricts returned entities to companies with a fundraise that investor joined.", "items": { "type": "string", "description": "Investor names. Each matches an investor entity whose brand, legal name, or alias equals it ignoring case and punctuation, or an individual investor's exact full name; a name that begins public entities' brands as whole words (\"Sequoia\") also matches the one holding many times the recorded investments of every other such entity (Sequoia Capital). Restricts returned entities to companies with a fundraise that investor joined." } } }, { "description": "Distinct fundraise-deal count ranges for an investor, with inclusive integer bounds.", "in": "query", "name": "fundraiseActivity.investorActivity.totalInvestmentRange", "required": false, "schema": { "type": "array", "description": "Distinct fundraise-deal count ranges for an investor, with inclusive integer bounds.", "items": { "$ref": "#/components/schemas/IntRange" } } }, { "description": "Total USD amount-invested ranges with inclusive bounds.", "in": "query", "name": "fundraiseActivity.investorActivity.totalAmountInvestedUsdRange", "required": false, "schema": { "type": "array", "description": "Total USD amount-invested ranges with inclusive bounds.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Average USD amount-invested ranges with inclusive bounds.", "in": "query", "name": "fundraiseActivity.investorActivity.averageAmountInvestedUsdRange", "required": false, "schema": { "type": "array", "description": "Average USD amount-invested ranges with inclusive bounds.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Largest USD amount-invested ranges with inclusive bounds.", "in": "query", "name": "fundraiseActivity.investorActivity.largestAmountInvestedUsdRange", "required": false, "schema": { "type": "array", "description": "Largest USD amount-invested ranges with inclusive bounds.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Smallest USD amount-invested ranges with inclusive bounds.", "in": "query", "name": "fundraiseActivity.investorActivity.smallestAmountInvestedUsdRange", "required": false, "schema": { "type": "array", "description": "Smallest USD amount-invested ranges with inclusive bounds.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Non-blank keyword/full-text search term. Use natural-search for plain-English or multi-constraint company requests.", "in": "query", "name": "textSearch", "required": false, "schema": { "type": "string", "description": "Non-blank keyword/full-text search term. Use natural-search for plain-English or multi-constraint company requests." } }, { "description": "Rank closed entities (Closed, Closed (Acquihire), Inactive) after every other textSearch or semanticQuery match, ahead of relevance and sort; omitted means true. false ranks them by relevance alone. Filter them out with operatingStatus or suppressNonOperating.", "in": "query", "name": "closedLast", "required": false, "schema": { "type": "boolean", "description": "Rank closed entities (Closed, Closed (Acquihire), Inactive) after every other textSearch or semanticQuery match, ahead of relevance and sort; omitted means true. false ranks them by relevance alone. Filter them out with operatingStatus or suppressNonOperating." } }, { "description": "Return only the matching entity count in totalElements. Content is empty by design, so the page empty flag describes content, not whether matches exist. Unsupported with semanticQuery.", "in": "query", "name": "countOnly", "required": false, "schema": { "type": "boolean" } }, { "description": "Allow generated monogram logos in results.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityList" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Companies, Products, and Services", "tags": [ "Entities" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/brand": { "get": { "description": "Thin, cached read of one company by exactly one of url, slug, or entityId: brand and legal names, logos, the primary website and social profile URLs, and current classification tags. url accepts any current URL joined to the company (website, LinkedIn, X/Twitter, Crunchbase, GitHub, and other profiles) or its aVenture page; scheme, a leading www, and case are ignored, while distinct paths stay distinct. 404 when nothing owns the identifier; 409 with candidate ids when a URL is owned by more than one company. A signed-in user's read charges one brand view per distinct company per UTC month against the monthly brand view allowance, then as additional usage when the subscriber enabled it; a repeat read of the same company in the month is free, as is a read of a company whose full profile view is already charged that month, a later full profile view of the company that month reverses its brand view charge, and an exhausted cap answers 429 with Retry-After.", "operationId": "getEntityBrand", "parameters": [ { "description": "Any current URL joined to the company, e.g. stripe.com.", "in": "query", "name": "url", "required": false, "schema": { "type": "string" } }, { "description": "Exact aVenture entity slug, e.g. stripe.", "in": "query", "name": "slug", "required": false, "schema": { "type": "string", "description": "Canonical lowercase URL slug for the resource", "example": "aventure-vc", "maxLength": 255, "pattern": "^[a-z0-9_-]+$" } }, { "description": "Exact entity UUID.", "in": "query", "name": "entityId", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityBrand" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not exactly one of url, slug, or entityId; a malformed slug or entityId; or a url that cannot be normalized." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "No visible company owns the identifier, including a url owned by a person." }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The url has more than one current owner; details.candidateEntityId and details.candidatePersonId list them. Retry with an entity candidate as entityId." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a Company's Names, Logos, Links, and Tags", "tags": [ "Entities" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/classifications/catalog": { "get": { "description": "Returns active classification buckets with optional tag lists. Each bucket carries its canonical `type`, accepted `alias[]` spellings, `tagCount`, and (when includeTags=true) the active `tag[]`. Use bucketType to scope to one bucket and includeTags=false to fetch metadata only. To find one tag, prefer the classification tag list filtered by category and name over the full catalog. Inactive tags are omitted.", "operationId": "getClassificationCatalog", "parameters": [ { "description": "Optional classification bucket. Accepts the same values as the tags endpoint type parameter.", "example": "industry", "in": "query", "name": "bucketType", "required": false, "schema": { "type": "string" } }, { "description": "When false, returns bucket metadata without tag arrays. To find one tag, prefer the classification tag list with category and q filters.", "in": "query", "name": "includeTags", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationCatalog" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get the Company Classification Taxonomy", "tags": [ "Classification Tags" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/classifications/tags": { "get": { "description": "Returns a paginated list of editorial tags and standardized classifications. Filter by category using any bucket or standardized category spelling listed by the catalog, and by name with q. Sorting is not supported — sort returns 422.", "operationId": "listClassifications", "parameters": [ { "description": "Classification bucket or standardized category. Case- and punctuation-insensitive.", "example": "industry", "in": "query", "name": "category", "required": false, "schema": { "type": "string" } }, { "description": "Case-insensitive name substring filter (e.g. 'enterprise').", "example": "enterprise", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25, "minimum": 1 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageClassification" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List Classification Tags", "tags": [ "Classification Tags" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/filters": { "get": { "description": "Get available filter options", "operationId": "listEntityFilters", "parameters": [ { "description": "Type group for default filter scope. Ignored when typeRecord is provided.", "in": "query", "name": "typeGroup", "required": false, "schema": { "$ref": "#/components/schemas/EntityTypeGroup" } }, { "description": "Filter by entity type (Company, Investor, etc.)", "in": "query", "name": "typeRecord", "required": false, "schema": { "type": "string" } }, { "description": "Include range distribution charts", "example": false, "in": "query", "name": "includeDistribution", "required": false, "schema": { "type": "boolean", "default": false } }, { "description": "Comma-separated or repeated filter keys for chart distribution (for example amountRaised,totalRaised)", "in": "query", "name": "distributionKey", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFilterOptionSet" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the Company Filter Options", "tags": [ "Entity Filters" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/filters/refine": { "post": { "description": "Return filter metadata scoped by current filters. Each filter entry reports choiceOptionTotal and choiceOptionTruncated so CLI and MCP callers can tell when the displayed choiceOption list is only the top scoped subset. Use the filter search endpoint with the same scopeFilter to look up values not shown in the refine response.", "operationId": "refineEntityFilters", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFilter" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFilterRefinedFilters" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Refine the Company Filter Options", "tags": [ "Entity Filters" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/filters/search": { "post": { "description": "Live search within the full eligible filter universe using current entity filters. Pass the same scopeFilter used for list/refine work; the searched filter excludes its own current values so callers can expand a facet without clearing the rest of the query.", "operationId": "searchEntityFilters", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFilterSearch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFilterSearchResult" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Look Up Filter Values Inside the Current Search", "tags": [ "Entity Filters" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/lookup": { "post": { "deprecated": true, "description": "Deprecated: send the same body to lookup-from-file (POST /v1/lookup) with kind ENTITY. Identifies a company, Product, or Service among the records you can see. Send typeRecord=Company for a company, or typeRecord=Product or Service for an offering, plus providerId when its provider is known; provider words in context are clues, not constraints. MATCHED: match.owner.entityId identifies the record and match.record.typeRecord names its type; read it with GET /v1/entities/{entityId}. A provider company and its offering are different records even when they share a brand or website. NO_MATCH: no record you can see fits the requested identity, type, and provider. NEEDS_REVIEW: several candidates fit; resend with a URL the subject owns to settle it. stage names the step that settled the answer: DETERMINISTIC, JUDGMENT, or WEB_EVIDENCE. Put pages the subject owns in url and articles in sourceUrl or sourceNewsId. Set scheduleEnrichment=true to also queue research on a matched record. For full detail by exact slug or URL use GET /v1/entities/lookup-exact. Company example: {\"name\":\"Acme AI\",\"typeRecord\":\"Company\",\"url\":[\"https://acme.ai\"]}. Offering example: {\"name\":\"Acme Assistant\",\"typeRecord\":\"Product\",\"url\":[\"https://acme.ai/assistant\"]}. A signed-in caller that sends Prefer: respond-async gets 202 with a Location status URL instead: a lookup job runs this same identification without the live deadline, and GET /v1/lookup-jobs/{jobId} returns it as identification once COMPLETED. A repeat of the same request returns the same job while it is still PENDING or RUNNING.", "operationId": "lookupEntity", "parameters": [ { "description": "For an existing match, true queues research; omitted or false does not. A record this lookup adds is not queued for research; queue it with the record's enrichments route.", "in": "query", "name": "scheduleEnrichment", "required": false, "schema": { "type": "boolean" } }, { "description": "Send respond-async to request a pollable entity lookup job.", "in": "header", "name": "Prefer", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentificationSubject" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identification" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "The identification as canonical JSON or compact text/plain.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnqueue" } } }, "description": "Sent with Prefer: respond-async (and Preference-Applied: respond-async), or without it to a signed-in caller once its paid live attempt, past the free exact match, ran out of time or left a provider still running: a lookup job was filed and finishes the lookup, adding no record for a NO_MATCH; poll the Location status URL after Retry-After.", "headers": { "Location": { "description": "Status URL of the accepted lookup job", "schema": { "type": "string", "format": "uri-reference" }, "style": "simple" }, "Retry-After": { "description": "Seconds to wait before polling the status URL", "schema": { "type": "integer" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Without a paid aVenture plan a caller gets a free daily allowance of name identifications per UTC day; past it the lookup answers 402 with code subscription_required (subscription_canceled, subscription_past_due, or subscription_paused when a plan lapsed), carrying limit, used, remaining, resetAt, and a Retry-After header." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Deprecated: Identify a Company, Product, or Service by Name and Scope", "tags": [ "Search" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/lookup-batch": { "post": { "description": "Returns a page envelope of entity detail records by id, slug, and/or current joined URL. When page and size are omitted, the full deduplicated batch is returned in request order. Sort is not supported for this fixed-order batch response. For public reads totalElements counts the entities visible to the caller, so requested identifiers that do not resolve or fail the public visibility filter are excluded. For privileged reads totalElements counts the requested identifiers that resolved to an entity id, which can exceed the number of records returned when an id no longer exists. A signed-in user's read charges one view per distinct returned record against the monthly entity or person view allowance; a repeat read of the same record in the month is free, and an exhausted cap answers 429 with Retry-After.", "operationId": "lookupEntityBatch", "parameters": [ { "description": "Zero-based page index (0..N); omit page and size for the full batch.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Zero-based page index (0..N); omit page and size for the full batch." } }, { "description": "The size of the page to be returned; omit page and size for the full batch.", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "description": "The size of the page to be returned; omit page and size for the full batch." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityDetailBatch" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityDetail" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Look Up Companies in Bulk by ID, Slug, or URL", "tags": [ "Entities" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/lookup-exact": { "get": { "description": "Start here for any aventure.vc profile URL, slug, website, or domain. Exact read: returns the full EntityDetail (names, links, funding, rounds, news, people, and research) of the one entity that identifier proves, so do not re-read it with getEntity or listEntities; it answers 404 or 409 instead of guessing. To identify a company by name and clues, use the POST lookup (CLI lookup). Detail qualifiers and visibility rules apply. UUIDs use the item route; id query parameters are rejected. Changed slugs redirect canonically. A signed-in user's read charges one view per distinct returned record against the monthly entity or person view allowance; a repeat read of the same record in the month is free, and an exhausted cap answers 429 with Retry-After.", "operationId": "getEntityLookup", "parameters": [ { "description": "Exact entity slug.", "in": "query", "name": "slug", "required": false, "schema": { "type": "string", "description": "Canonical lowercase URL slug for the resource", "example": "aventure-vc", "maxLength": 255, "pattern": "^[a-z0-9_-]+$" } }, { "description": "Provider slug for Product/Service slug lookup; providerTypeRecord can narrow this to Company, Nonprofit, or Government routes.", "in": "query", "name": "companySlug", "required": false, "schema": { "type": "string", "description": "Canonical lowercase URL slug for the resource", "example": "aventure-vc", "maxLength": 255, "pattern": "^[a-z0-9_-]+$" } }, { "description": "Concrete provider type qualifier for a Product/Service provider route; group-only Organization is invalid. Use with companySlug when resolving `/companies/{slug}/products-services/{product}`, `/non-profits/{slug}/products-services/{product}`, or `/government/{slug}/products-services/{product}`.", "example": "Company", "in": "query", "name": "providerTypeRecord", "required": false, "schema": { "type": "string", "description": "Concrete provider type qualifier for a Product/Service provider route; group-only Organization is invalid. Use with companySlug when resolving `/companies/{slug}/products-services/{product}`, `/non-profits/{slug}/products-services/{product}`, or `/government/{slug}/products-services/{product}`.", "example": "Company" } }, { "description": "aventure.vc profile URL (such as https://aventure.vc/companies/), or the entity's own website or domain URL, matched by host and path unless urlMatchMode=domain.", "in": "query", "name": "url", "required": false, "schema": { "type": "string", "description": "aventure.vc profile URL (such as https://aventure.vc/companies/), or the entity's own website or domain URL, matched by host and path unless urlMatchMode=domain." } }, { "description": "URL type qualifier. List the accepted tokens with GET /v1/url-types (CLI: url-types list).", "example": "website", "in": "query", "name": "urlType", "required": false, "schema": { "type": "string", "description": "URL type qualifier. List the accepted tokens with GET /v1/url-types (CLI: url-types list).", "example": "website" } }, { "description": "URL matching mode: hostPath (default for url) or domain. Omit when urlDomain is supplied; urlDomain selects domain mode automatically.", "example": "hostPath", "in": "query", "name": "urlMatchMode", "required": false, "schema": { "type": "string", "description": "URL matching mode: hostPath (default for url) or domain. Omit when urlDomain is supplied; urlDomain selects domain mode automatically.", "example": "hostPath" } }, { "description": "Concrete entity type qualifier; group-only Organization is invalid. List the accepted concrete tokens and their aliases with GET /v1/entities/types (CLI: entities types list).", "example": "Company", "in": "query", "name": "typeRecord", "required": false, "schema": { "type": "string", "description": "Concrete entity type qualifier; group-only Organization is invalid. List the accepted concrete tokens and their aliases with GET /v1/entities/types (CLI: entities types list).", "example": "Company" } }, { "description": "Primary entity name candidate.", "in": "query", "name": "name", "required": false, "schema": { "type": "string", "description": "Primary entity name candidate." } }, { "description": "Brand name candidate.", "in": "query", "name": "nameBrand", "required": false, "schema": { "type": "string", "description": "Brand name candidate." } }, { "description": "Legal name candidate.", "in": "query", "name": "nameLegal", "required": false, "schema": { "type": "string", "description": "Legal name candidate." } }, { "description": "Location candidate: city, state, or country.", "in": "query", "name": "location", "required": false, "schema": { "type": "string", "description": "Location candidate: city, state, or country." } }, { "description": "Website domain candidate without protocol or path.", "in": "query", "name": "urlDomain", "required": false, "schema": { "type": "string", "description": "Website domain candidate without protocol or path." } }, { "description": "Allow generated monogram logo fallback.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean", "description": "Allow generated monogram logo fallback." } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityDetail" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Entity detail as canonical JSON or the same data rendered as compact text/plain.", "headers": { "X-Entity-Name-Revision": { "description": "Opaque revision of entity id, brand, legal name, and ordered name aliases.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "301": { "description": "Redirect to new slug location", "headers": { "Location": { "description": "Redirect target", "style": "simple" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflicting or unusable identity input: name, nameBrand, and nameLegal must identify the same entity, and exactly one identifier form may be supplied." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "No entity resolved: fuzzy candidate signals below the review threshold without identity proof are exhausted, which does not prove the record is absent or safe to create — identify it by name and clues with GET /v1/lookup (CLI lookup --kind ENTITY). Retry this exact read only with a slug or URL copied from an aVenture page. An existing but filtered row instead reports its reason as the ProblemDetail title: Entity Exists but Is Not Public (the record exists but is not published), Product Not Public: Missing Provider Relationship, or Fund Not Public: No Public Manager Firm." }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Ambiguous identity: review-level candidates, unresolved identity proof, multiple exact normalized-name matches, or a Product/Service slug shared across provider pairs. ProblemDetail carries candidates; read each returned id with GET /v1/entities/{entityId}. Resolve the Product/Service ambiguity with companySlug plus slug or a provider's productService relationship." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Read Full Entity Detail by aVenture Profile URL, Slug, Website, or Domain", "tags": [ "Entities" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/lookup-matches": { "post": { "description": "Resolves each queried id, slug, and current joined URL to exactly one outcome row that echoes the raw input: MATCHED with full detail, AMBIGUOUS with candidate ids when a URL is currently owned by more than one entity, or MISSING. Unlike the batch detail read, no input is silently dropped and every row maps back to its source identifier. URL matching is host+path exact: scheme and a leading www are ignored, but distinct paths stay distinct (stripe.com does not match stripe.com/payments). A signed-in user's read charges one view per distinct returned record against the monthly entity or person view allowance; a repeat read of the same record in the month is free, and an exhausted cap answers 429 with Retry-After.", "operationId": "lookupEntityMatches", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityDetailBatch" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityResolution" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Look Up Which Company Each Identifier Matches", "tags": [ "Entities" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/relationships/types": { "get": { "description": "Returns canonical EntityRelationshipType values, aliases, and policy flags. Use joinable=true values with entities relationships create; acquisitionManaged=true values route through entity acquisitions; exclusiveRelationshipType lists relationship types that cannot coexist for the same unordered entity pair; readOnly=true values are emitted by reads only.", "operationId": "listEntityRelationshipTypes", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityRelationshipTypeOption" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Entity Relationship Types", "tags": [ "Entity Relationships" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/relationships/{relationshipId}": { "get": { "description": "Returns one relationship by row id, including historic and non-primary rows. The response includes isCurrent and isPrimary so hidden-row cause is explicit.", "operationId": "getEntityRelationship", "parameters": [ { "description": "Integer entity_relationship.id row id from EntityRelationship.id, not an entity UUID.", "in": "path", "name": "relationshipId", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityRelationship" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get One Relationship by ID", "tags": [ "Entity Relationships" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/research-details/types": { "get": { "description": "Returns research detail type tokens and their write metadata. The metadata includes valueShape, allowedToken, range, and timeSeries. When timeSeries=true, each believable dated observation is historical data: add a new current row and delete only rows believed false.", "operationId": "listEntityResearchDetailTypes", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchDetailType" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List the Accepted Research Detail Types", "tags": [ "Entity Research" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/research-snippets/types": { "get": { "description": "Lists the recognized research snippet types. A textType in this list is validated against its length and paragraph rules on write and defaults to visible; a textType not in this list is still saved but defaults to visible=false (hidden from default reads). The per-row visible flag overrides the default either way. The curated and analysisRenderable flags mark public Analysis-page eligibility, not snippet display.", "operationId": "listEntityResearchSnippetTypes", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchSnippetType" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the Accepted Research Snippet Types", "tags": [ "Entity Research" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/search": { "post": { "description": "Run keyword, semantic, or explicit structured entity filtering with a structured filter body; Organization expands to the canonical organization type group; semanticQuery ranks by stored content embeddings. For plain-English queries, use POST /v1/search/natural/entities. semanticQuery defines a bounded result set: the nearest rows at or above a relevance cutoff, capped in size and ordered by score; page numbers reach the whole set and totalElements counts it. Page 0 of a semantic set of 50 rows or fewer can emit a signed cursor; other pages continue by page number. To follow the cursor, reuse the same filters, sort, size, and visibility scope. countOnly is unsupported with cursor; count-only pages have no content; read totalElements.", "operationId": "searchEntities", "parameters": [ { "description": "Zero-based page index for offset paging; omit it for the first page. Ignored when cursor is sent: to continue a cursor traversal, send the X-Next-Cursor value as cursor and leave page out.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "Return only the matching entity count in totalElements. Content is empty by design, so the page empty flag describes content, not whether matches exist. Unsupported with semanticQuery.", "in": "query", "name": "countOnly", "required": false, "schema": { "type": "boolean" } }, { "description": "Allow generated monogram logos in results.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Opaque entity cursor; reuse filters and sort. Cursor is unsupported with countOnly; semanticQuery depends on the endpoint.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "Set true to return each match as a company detail search record instead of the list row: the headquarters address, the first 5 people (most recently updated association first), and the first 5 news articles (newest first). Full lists: GET /v1/entities/{entityId}/addresses, GET /v1/entities/{entityId}/people, and GET /v1/news?owner.entityId=.", "in": "query", "name": "includeFullDetail", "schema": { "type": "boolean" } }, { "description": "Send respond-async to receive a durable semantic-search job and poll its Location.", "in": "header", "name": "Prefer", "schema": { "type": "string", "example": "respond-async" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityListFilter" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PageEntityList" }, { "$ref": "#/components/schemas/PageEntityDetail" } ] } } }, "description": "OK", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token, present when another page exists; send it as cursor to read that page. The body's number, first, and totalPages describe offset paging only; they do not advance while you follow cursors.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnqueue" } } }, "description": "Semantic search accepted when Prefer: respond-async is sent; poll Location.", "headers": { "Location": { "description": "Endpoint to poll for the asynchronous search result.", "schema": { "type": "string", "format": "uri-reference" }, "style": "simple" }, "Retry-After": { "description": "Minimum delay before polling the Location.", "schema": { "type": "integer", "format": "int32" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Search Companies, Products, and Services", "tags": [ "Entities" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/search/jobs/{jobId}": { "get": { "description": "Returns the page accepted by `Prefer: respond-async` on POST /v1/entities/search. Answers 202 with Location and Retry-After while the search is queued or running, 200 with the canonical entity page once complete, and 404 for an unknown job.", "operationId": "getEntitySemanticSearchJob", "parameters": [ { "description": "Entity semantic search job UUID", "in": "path", "name": "jobId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityList" } } }, "description": "Search completed; the canonical entity page is returned.", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token, present when another page exists; send it as cursor to read that page. The body's number, first, and totalPages describe offset paging only; they do not advance while you follow cursors.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnqueue" } } }, "description": "Search is queued or running; poll after Retry-After.", "headers": { "Location": { "description": "Endpoint to poll for the asynchronous search result.", "schema": { "type": "string", "format": "uri-reference" }, "style": "simple" }, "Retry-After": { "description": "Minimum delay before polling the Location.", "schema": { "type": "integer", "format": "int32" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get an Async Semantic Entity Search", "tags": [ "Entities" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/sec": { "get": { "description": "Resolves a US SEC registrant by ticker (preferred) or company-name query. Returns the SEC EDGAR identity facts: legal name, former names, ticker, exchange, SIC industry, state of incorporation, headquarters, and whether it is an operating company, plus the earliest EDGAR filing date and, when EDGAR holds it, the IPO prospectus (listingProspectus). SEC supplies no brand name, website, or summary text — those stay enrichment-owned and are absent here. A name query binds only the one registrant whose title equals it ignoring case and legal suffix, or the only registrant whose title contains it; several without one exact title return 409 with their tickers in resolution.acceptedValue to retry by ticker. A ticker missing from SEC's current listings binds the one registrant whose past filings carried it (a delisted filer, whose ticker list is then empty); several such registrants return 409. A 404 means this lookup matched no SEC registrant; it does not show the company is private. Read live and never persisted.", "operationId": "lookupSecCompany", "parameters": [ { "description": "Trading ticker symbol (preferred resolver)", "example": "AAPL", "in": "query", "name": "ticker", "required": false, "schema": { "type": "string" } }, { "description": "Company name query (used when no ticker is given)", "example": "NVIDIA", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecCompany" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get SEC EDGAR Facts for a Public Company", "tags": [ "Entity Research" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/texts/types": { "get": { "description": "Returns text type values accepted by entity text rows.", "operationId": "listEntityTextTypes", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TextTypeOption" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the Accepted Company Text Types", "tags": [ "Texts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/types": { "get": { "description": "Returns each accepted typeRecord value with its aliases, meaning, and public page path.", "operationId": "listEntityTypeRecords", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityTypeAlias" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the Accepted typeRecord Values", "tags": [ "Entity Maintenance" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}": { "get": { "description": "Returns one company's full profile by exact UUID, the read for a company brief: identity, funding history with each round's lead investors, key people, news, and relationships. Use lookup for a slug, URL, or candidate signals. A signed-in user's read charges one view per distinct returned record against the monthly entity or person view allowance; a repeat read of the same record in the month is free, and an exhausted cap answers 429 with Retry-After.", "operationId": "getEntity", "parameters": [ { "description": "Exact entity UUID.", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Concrete entity type qualifier; group-only Organization is invalid. List the accepted concrete tokens and their aliases with GET /v1/entities/types (CLI: entities types list).", "example": "Company", "in": "query", "name": "typeRecord", "required": false, "schema": { "type": "string", "description": "Concrete entity type qualifier; group-only Organization is invalid. List the accepted concrete tokens and their aliases with GET /v1/entities/types (CLI: entities types list).", "example": "Company" } }, { "description": "Allow generated monogram logo fallback.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean", "description": "Allow generated monogram logo fallback." } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityDetail" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Entity detail as canonical JSON or the same data rendered as compact text/plain.", "headers": { "X-Entity-Name-Revision": { "description": "Opaque revision of entity id, brand, legal name, and ordered name aliases.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Company, Product, or Service by ID", "tags": [ "Entities" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/acquisitions": { "get": { "description": "Returns a row only when both sides of the acquisition are published. A 404 for an acquisition that the entity relationships resource lists means the record exists but one side is not published. The acquired/acquirer roles in each row are always declared explicitly in the response via the acquiredEntity and acquirerEntity fields. The role query parameter selects which side of the acquisition the path entity is on: acquired (default) lists acquisitions where the path entity was bought; acquirer lists acquisitions where the path entity was the buyer; all lists or reads both sides in one response. Writes (POST/PUT/PATCH/DELETE) ignore role and always treat the path entity as acquired. List responses are ordered by most recent acquisition event first.", "operationId": "listEntityAcquisitions", "parameters": [ { "description": "Entity UUID whose acquisition rows are being read or written.", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Selects which side the path entity occupies in the WHERE clause: `acquired` (default) lists rows where the path entity was bought; `acquirer` lists rows where the path entity was the buyer; `all` lists both sides.", "in": "query", "name": "role", "required": false, "schema": { "$ref": "#/components/schemas/EntityAcquisitionRole", "default": "acquired" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityAcquisition" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's Acquisitions", "tags": [ "Entity Acquisitions" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/acquisitions/{relationshipId}": { "get": { "description": "Returns a row only when both sides of the acquisition are published. A 404 for an acquisition that the entity relationships resource lists means the record exists but one side is not published. A gated miss on an existing row returns 404 with title 'Acquisition Exists but a Counterpart Entity Is Not Public'. The acquired/acquirer roles in each row are always declared explicitly in the response via the acquiredEntity and acquirerEntity fields. The role query parameter selects which side of the acquisition the path entity is on: acquired (default) lists acquisitions where the path entity was bought; acquirer lists acquisitions where the path entity was the buyer; all lists or reads both sides in one response. Writes (POST/PUT/PATCH/DELETE) ignore role and always treat the path entity as acquired.", "operationId": "getEntityAcquisition", "parameters": [ { "description": "Entity UUID whose acquisition rows are being read or written.", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Acquisition relationship row id (entity_relationship.id).", "in": "path", "name": "relationshipId", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "description": "Selects which side the path entity occupies in the WHERE clause: `acquired` (default) lists rows where the path entity was bought; `acquirer` lists rows where the path entity was the buyer; `all` reads either side.", "in": "query", "name": "role", "required": false, "schema": { "$ref": "#/components/schemas/EntityAcquisitionRole", "default": "acquired" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityAcquisition" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get One Company Acquisition", "tags": [ "Entity Acquisitions" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/addresses": { "get": { "description": "Returns current physical addresses with their role-period associations, ordered HQ-first, primary-next, most-recent-first (`updated_at DESC`). Reads directly from the base tables so fresh writes surface immediately (bypassing the mv_entity_addresses materialized view). Set includeInactive=true as a signed-in user or with read credentials to include inactive/historical rows.", "operationId": "listEntityAddresses", "parameters": [ { "description": "Canonical entity UUID", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Include inactive rows", "in": "query", "name": "includeInactive", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's Locations", "tags": [ "Entity Addresses" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/addresses/{addressJoinId}": { "get": { "description": "Returns the physical address group containing the selected entity address association. Requires read auth.", "operationId": "getEntityAddress", "parameters": [ { "description": "Canonical entity UUID", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Address join id parameter", "in": "path", "name": "addressJoinId", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Company Address", "tags": [ "Entity Addresses" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/blog-posts": { "get": { "description": "Returns active external blog post links. For news and press coverage, list news instead.", "operationId": "listEntityBlogPosts", "parameters": [ { "description": "Entity UUID owning the blog post rows", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "default": [ "publishedAt,desc" ], "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageBlogPost" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's Blog Posts", "tags": [ "Research Blog Posts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/blog-posts/{blogPostId}": { "get": { "description": "Returns one entity-owned external link by id. Any signed-in user may call this.", "operationId": "getEntityBlogPost", "parameters": [ { "description": "Entity UUID owning the blog post row", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Blog post UUID", "in": "path", "name": "blogPostId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPost" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Company Blog Post", "tags": [ "Research Blog Posts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/classifications": { "get": { "description": "Returns the company's classifications grouped by bucket. The default view includes current classifications; includeInactive=true adds historical ones and requires sign-in. A company that is not public returns 404.", "operationId": "listEntityClassifications", "parameters": [ { "description": "Canonical entity UUID", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Include inactive/historical entity classification join rows; default false returns only current joins.", "in": "query", "name": "includeInactive", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityClassification" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List a Company's Classifications", "tags": [ "Entity Classifications" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/classifications/suggestions": { "get": { "description": "Returns ranked tag and standard industry code suggestions for the company, based on similar companies. mainProduct is never suggested, and an empty array means no similar company suggests anything. Requires sign-in; a company that is not public returns 404.", "operationId": "listEntityClassificationSuggestions", "parameters": [ { "description": "Canonical entity UUID", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Maximum suggestions to return; default 12, maximum 50.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityClassificationSuggestion" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Suggest Classifications for a Company", "tags": [ "Entity Classifications" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/content": { "get": { "description": "Returns news articles, blog posts, repositories, websites, and pages related to an entity. Any signed-in user may call this.", "operationId": "listEntityContent", "parameters": [ { "description": "Entity UUID whose publications are listed.", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Topic key or source category.", "in": "query", "name": "topic", "required": false, "schema": { "type": "string", "description": "Topic key or source category." } }, { "description": "Public content type filter.", "in": "query", "name": "contentType", "required": false, "schema": { "$ref": "#/components/schemas/PublicationType" } }, { "description": "Owner relation filter.", "in": "query", "name": "relation", "required": false, "schema": { "$ref": "#/components/schemas/PublicationRelation" } }, { "description": "Best-effort content year filter.", "in": "query", "name": "year", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Best-effort content year filter." } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "Set true for first-page content-existence probes that do not need exact totals or stable ordering.", "in": "query", "name": "existenceProbe", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublication" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List a Company's Publications", "tags": [ "Publications" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/content/facets": { "get": { "description": "Counts one entity's content cards by topic and content type across the whole index, so filters show exact totals before every page loads. Any signed-in user may call this.", "operationId": "listEntityContentFacets", "parameters": [ { "description": "Entity UUID whose publications are counted.", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicationFacet" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Count a Company's Publications", "tags": [ "Publications" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/content/search": { "post": { "description": "Translates plain-English constraints for one entity's content index. Any signed-in user may call this.", "operationId": "searchEntityContent", "parameters": [ { "description": "Entity UUID whose publications are searched.", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NaturalSearch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublication" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Search a Company's Publications", "tags": [ "Publications" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/employee-counts": { "get": { "description": "Returns employee-count time series for the entity at this address. Results are sorted newest first. This endpoint does not support custom sorting.", "operationId": "listEntityEmployeeCounts", "parameters": [ { "description": "Entity unique identifier (UUID)", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "description": "The size of the page to be returned; maximum 500.", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEmployeeCount" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's Headcount Over Time", "tags": [ "Entity Research" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/enrichments": { "post": { "description": "Queues a run that researches the addressed entity and updates its aVenture profile, owned by the authenticated caller. Take entityId from match.owner when POST /v1/lookup or POST /v1/entities/lookup returns MATCHED (CLI: lookup, entities lookup). To update an entity with facts read verbatim from an external source page (founding year, website or social URL, address, or funding round and investors), pass finding in the body (each with statement, sourceUrl, and verbatim quote; taskPresetKey defaults to apply-cited-findings). When an observed update comes from an indexed news article (newsArticle or GET /v1/news), a page not read verbatim, or covers other profile sections (team, products, descriptions), pass userPrompt in the body naming the observed detail and source URL (newsUrlOriginal or web URL). When a run for this entity is already queued or running, returns that run instead of queuing and charging another; a new run reserves one `company` research unit from the plan's research allowance, spent only once the run saves a research write and returned when it ends without one. After the run completes, read the updated profile with GET /v1/entities/{entityId} (CLI: entities get). Check the run's progress with GET /v1/research-runs/{runId} (CLI: research-runs get).", "operationId": "enrichEntity", "parameters": [ { "description": "Canonical entity UUID.", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "COMPREHENSIVE (the default) researches the whole profile; INDIVIDUAL runs only the tasks named in taskPresetKey.", "in": "query", "name": "mode", "required": false, "schema": { "$ref": "#/components/schemas/EnrichmentMode" } }, { "description": "Model id for the run's lead agent; omit to use aVenture's default model.", "in": "query", "name": "model", "required": false, "schema": { "type": "string" } }, { "deprecated": true, "description": "Deprecated: send userPrompt in the JSON body. Used only when the body carries no userPrompt; longer than 2000 characters is refused with 400.", "in": "query", "name": "userPrompt", "required": false, "schema": { "type": "string" } }, { "description": "Research presets that focus the run, listed by GET /v1/research-runs/presets; at least one is required when mode is INDIVIDUAL, and an unknown key is a 400.", "in": "query", "name": "taskPresetKey", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentPrompt" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessRun" } } }, "description": "The queued enrichment run for the addressed entity.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Needs a plan that includes research runs; a caller without one gets 402 with code subscription_required (subscription_canceled, subscription_past_due, or subscription_paused when a plan lapsed)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Enrich One Company, Product, or Service", "tags": [ "Research Runs" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/fundraise-investor-joins": { "get": { "description": "Lists entity or person investors joined to a fundraise round, including join-level amountInvested attribution. Rows carry investor ids only. To name a round's investors and its lead in two reads, list GET /v1/entities/{entityId}/investors?compact=true for firms and GET /v1/entities/{entityId}/person-investors for angels, then keep the rows whose investorAttribution[].transactionId is the round id; leadInvestor is on that attribution. Public reads omit joins whose investor profile is hidden, and the round's investorCount is source-reported, so it can exceed the joins listed here. amountInvested is a plain decimal number in the fundraise transaction currency. Send a JSON number such as 220000 or 123456.78. Do not send currency signs, currency codes, comma grouping, quoted numeric strings, or abbreviations such as 220k or 0.22M. PATCH with amountInvested:null clears the value. Use entityId for the fundraising/portfolio company that raised the round — always a company, never the fund or investment firm that supplied the capital. For an Investment Firm's outgoing investment, pass the portfolio company that received the money here and identify the firm with investorEntityId or investorEntitySlug. Use transactionId for the round id, or round plus dateAnnounced when transactionId is unknown. To list one investor's joins, find its entityId or personId by name with GET /v1/lookup (CLI lookup --kind ENTITY or --kind PERSON) and pass it as investorEntityId or investorPersonId.", "operationId": "listEntityFundraiseInvestorJoins", "parameters": [ { "description": "Entity unique identifier (UUID).", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Join identifier. When present, lookup ignores transaction and investor query parameters.", "in": "query", "name": "joinId", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Join identifier. When present, lookup ignores transaction and investor query parameters." } }, { "description": "Fundraise round transaction id. The target entity id/slug is the entity that raised the round; for an Investment Firm investment, use the portfolio/fundraising company as target and identify the firm with investorEntityId or investorEntitySlug. When omitted, lookup uses the target entity plus round/dateAnnounced.", "in": "query", "name": "transactionId", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Fundraise round transaction id. The target entity id/slug is the entity that raised the round; for an Investment Firm investment, use the portfolio/fundraising company as target and identify the firm with investorEntityId or investorEntitySlug. When omitted, lookup uses the target entity plus round/dateAnnounced." } }, { "description": "Raw fundraise round label used when transactionId is omitted", "in": "query", "name": "round", "required": false, "schema": { "type": "string", "description": "Raw fundraise round label used when transactionId is omitted" } }, { "description": "Exact source-stated announced date or instant used to disambiguate same-label rounds", "in": "query", "name": "dateAnnounced", "required": false, "schema": { "type": "string", "description": "Exact source-stated announced date or instant used to disambiguate same-label rounds", "pattern": "^(?!0000)[0-9]{4}(?:-(?:0[1-9]|1[0-2])(?:-(?:0[1-9]|[12][0-9]|3[01])(?:T(?:[01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:\\.[0-9]{1,9})?)?(?:Z|[+-](?:(?:0[0-9]|1[0-7]):[0-5][0-9]|18:00)))?)?)?$" } }, { "description": "Investor entity identifier. Find an investor's entityId by name with GET /v1/lookup (CLI lookup --kind ENTITY).", "in": "query", "name": "investorEntityId", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Investor entity identifier. Find an investor's entityId by name with GET /v1/lookup (CLI lookup --kind ENTITY)." } }, { "description": "Investor entity slug when investorEntityId is omitted. Find it by name with GET /v1/lookup (CLI lookup --kind ENTITY).", "in": "query", "name": "investorEntitySlug", "required": false, "schema": { "type": "string", "description": "Investor entity slug when investorEntityId is omitted. Find it by name with GET /v1/lookup (CLI lookup --kind ENTITY)." } }, { "description": "Investor person identifier. Find an investor's personId by name with GET /v1/lookup (CLI lookup --kind PERSON).", "in": "query", "name": "investorPersonId", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Investor person identifier. Find an investor's personId by name with GET /v1/lookup (CLI lookup --kind PERSON)." } }, { "description": "Investor person slug when investorPersonId is omitted. Find it by name with GET /v1/lookup (CLI lookup --kind PERSON).", "in": "query", "name": "investorPersonSlug", "required": false, "schema": { "type": "string", "description": "Investor person slug when investorPersonId is omitted. Find it by name with GET /v1/lookup (CLI lookup --kind PERSON)." } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityFundraiseInvestorJoin" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the Investors in a Funding Round", "tags": [ "Entity Fundraise" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/fundraise-investor-joins/{joinId}": { "get": { "description": "Gets one entity or person investor join by join id.", "operationId": "getEntityFundraiseInvestorJoin", "parameters": [ { "description": "Entity unique identifier (UUID).", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Fundraise investor join identifier", "in": "path", "name": "joinId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Type-safe identifier for fundraise investor joins" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFundraiseInvestorJoin" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get One Investor on a Funding Round", "tags": [ "Entity Fundraise" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/fundraise-rounds": { "get": { "description": "Lists fundraise rounds for an entity. Use entityId for the fundraising/portfolio company that raised the round - always a company, never the fund or investment firm. For an investment made by an Investment Firm, pass the portfolio company that received the money here, not the investment firm id and not the round id.", "operationId": "listEntityFundraiseRounds", "parameters": [ { "description": "Zero-based page index for offset paging; omit it for the first page. Ignored when cursor is sent: to continue a cursor traversal, send the X-Next-Cursor value as cursor and leave page out.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "Entity unique identifier (UUID).", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Round label contains filter", "example": "Series A", "in": "query", "name": "round", "required": false, "schema": { "type": "string" } }, { "description": "Inclusive minimum announced date", "example": "2022-01-01", "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string", "format": "date" } }, { "description": "Inclusive maximum announced date", "example": "2024-12-31", "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "format": "date" } }, { "description": "Inclusive minimum amount raised. Use a plain whole-number amount such as 500000; do not include currency signs, codes, comma grouping, decimals, or strings.", "example": 500000, "in": "query", "name": "minAmount", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "description": "Inclusive maximum amount raised. Use a plain whole-number amount such as 50000000; do not include currency signs, codes, comma grouping, decimals, or strings.", "example": 50000000, "in": "query", "name": "maxAmount", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "description": "Permit monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Opaque URL-safe cursor token from X-Next-Cursor. Reuse the same filters and sort.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityFundraiseTransaction" } } }, "description": "OK", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token, present when another page exists; send it as cursor to read that page. The body's number, first, and totalPages describe offset paging only; they do not advance while you follow cursors.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's Funding Rounds", "tags": [ "Entity Fundraise" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/fundraise-rounds/{fundraiseRoundId}": { "get": { "description": "Gets one fundraise round for an entity. Use entityId for the fundraising/portfolio company that raised the round - always a company, never the fund or investment firm. For an investment made by an Investment Firm, pass the portfolio company that received the money here, not the investment firm id and not the round id. Use fundraiseRoundId for the round id.", "operationId": "getEntityFundraiseRound", "parameters": [ { "description": "Entity unique identifier (UUID).", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Fundraise round id. Use this with the entityId path segment that owns the round.", "in": "path", "name": "fundraiseRoundId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical fundraise transaction UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFundraiseTransaction" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get One Funding Round", "tags": [ "Entity Fundraise" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/investments": { "get": { "description": "Lists investments made by the requesting investor entity. Use entityId to select the investor, then filter by round, dateFrom/dateTo, minAmount/maxAmount, and latestPerEntity. amountInvested appears only inside investorAttribution, is a plain decimal number in the fundraise transaction currency, and is not added to amountRaised. Valid sort syntax is sort=amountInvested,desc; do not use investorAttribution.amountInvested, amount_invested, currency signs, currency codes, comma grouping, or abbreviated values. Deep traversal uses cursor: pass the prior X-Next-Cursor value as cursor and reuse the same filters and sort.", "operationId": "listEntityInvestments", "parameters": [ { "description": "Zero-based page index for offset paging; omit it for the first page. Ignored when cursor is sent: to continue a cursor traversal, send the X-Next-Cursor value as cursor and leave page out.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "Entity unique identifier (UUID).", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Round label contains filter", "example": "Series A", "in": "query", "name": "round", "required": false, "schema": { "type": "string" } }, { "description": "Inclusive minimum announced date", "example": "2022-01-01", "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string", "format": "date" } }, { "description": "Inclusive maximum announced date", "example": "2024-12-31", "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "format": "date" } }, { "description": "Inclusive minimum amount raised. Use a plain whole-number amount such as 500000; do not include currency signs, codes, comma grouping, decimals, or strings.", "example": 500000, "in": "query", "name": "minAmount", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "description": "Inclusive maximum amount raised. Use a plain whole-number amount such as 50000000; do not include currency signs, codes, comma grouping, decimals, or strings.", "example": 50000000, "in": "query", "name": "maxAmount", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "description": "Permit monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Return latest transaction per entity", "in": "query", "name": "latestPerEntity", "required": false, "schema": { "type": "boolean" } }, { "description": "Opaque URL-safe cursor token from X-Next-Cursor. Reuse the same filters and sort.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityFundraiseTransaction" } } }, "description": "OK", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token, present when another page exists; send it as cursor to read that page. The body's number, first, and totalPages describe offset paging only; they do not advance while you follow cursors.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the Investments a Company Made", "tags": [ "Entity Fundraise" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/investor-activity": { "get": { "description": "Gets the investor-perspective activity aggregate (total investments, current portfolio count, exits, and top investment stages) for an investor. Use entityId for the investor — the fund, investment firm, or company that supplied the capital — not a portfolio company that raised a round.", "operationId": "getEntityInvestorActivity", "parameters": [ { "description": "Entity unique identifier (UUID).", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFundraiseInvestorActivity" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get Investor Activity", "tags": [ "Entity Fundraise" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/investors": { "get": { "description": "Lists entity investors with per-round investorAttribution rows. Use entityId for the fundraising/portfolio company being invested in, whose investors to list — always a company, never an investor fund or firm. amountInvested appears only inside investorAttribution, is a plain decimal number in the fundraise transaction currency, and is not added to amountRaised. Valid sort syntax is sort=amountInvested,desc; do not use investorAttribution.amountInvested, amount_invested, currency signs, currency codes, comma grouping, or abbreviated values. For more than a few investors, send compact=true: each row keeps the investor's own profile and returns its people, news, rounds, relationships, and research as empty lists.", "operationId": "listEntityInvestors", "parameters": [ { "description": "Zero-based page index for offset paging; omit it for the first page. Ignored when cursor is sent: to continue a cursor traversal, send the X-Next-Cursor value as cursor and leave page out.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "Entity unique identifier (UUID).", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Permit generated monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Set true to return each investor's own profile with its people, news, funding rounds, relationships, and research as empty lists, not absent fields; the profile's sitemap flags still show which of them exist. Responses are much smaller.", "in": "query", "name": "compact", "required": false, "schema": { "type": "boolean" } }, { "description": "Opaque URL-safe cursor token from X-Next-Cursor. Reuse the same filters and sort.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityInvestorParticipation" } } }, "description": "OK", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token, present when another page exists; send it as cursor to read that page. The body's number, first, and totalPages describe offset paging only; they do not advance while you follow cursors.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's Investors", "tags": [ "Entity Fundraise" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/logo": { "get": { "description": "Returns the selected square or standard logo with its stored provenance; an empty slot returns 404. A Product or Service's assembled `core.image` can show its provider's logo; this slot is the entity's own asset, and an offering with no own mark grades `entity.logo` by that displayed provider logo. This is the asset fetch, not the verification proof: the accuracy check against reference marks is the logo check operation.", "operationId": "getEntityLogo", "parameters": [ { "description": "Canonical entity UUID", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Logo slot: SQUARE (default; `core.image.logoSquare`) or STANDARD (`core.image.logo`).", "in": "query", "name": "logoType", "required": false, "schema": { "$ref": "#/components/schemas/EntityLogoType" } }, { "description": "Validate the entity SQUARE logo's stored original before returning metadata.", "in": "query", "name": "validateSquareOriginal", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUpload" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get a Company Logo", "tags": [ "Entity Logo" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/people": { "get": { "description": "Lists who works at a company: its founders, executives, employees, and other associated people, with each person's title and whether the role is current.", "operationId": "listEntityPersonAssociations", "parameters": [ { "description": "Entity UUID", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Search term filter", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "Match titleName containing this text as a whole-word phrase, ignoring case: founder matches Co-Founder, Founder & CEO, and CEO and Co-Founder, but not Founding Partner. Omit to include all titles; this does not filter titleFunction or titleLevel.", "in": "query", "name": "role", "required": false, "schema": { "type": "string" } }, { "description": "Current association filter", "in": "query", "name": "isCurrent", "required": false, "schema": { "type": "boolean" } }, { "description": "Include person URL records", "in": "query", "name": "includeUrl", "required": false, "schema": { "type": "boolean" } }, { "description": "Include person address records", "in": "query", "name": "includeAddress", "required": false, "schema": { "type": "boolean" } }, { "description": "Writes only: the person's slug when the body omits personId. List reads ignore it; use search to narrow listed people.", "in": "query", "name": "personSlug", "required": false, "schema": { "type": "string" } }, { "description": "Return count metadata without full content", "in": "query", "name": "countOnly", "required": false, "schema": { "type": "boolean" } }, { "description": "Permit generated monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format property,(asc|desc), where property is one of: id, nameFirst, nameLast, nameFull, slug, createdAt, updatedAt, status, gender, amountInvested, totalInvestments. Default order is ascending; repeat sort for multiple criteria.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityPersonAssociation" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the People at a Company", "tags": [ "Entity Person Associations" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/people/{associationId}": { "get": { "description": "Returns one person's role at a company.", "operationId": "getEntityPersonAssociation", "parameters": [ { "description": "Entity UUID", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Association id", "in": "path", "name": "associationId", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "description": "Search term filter", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "Match titleName containing this text as a whole-word phrase, ignoring case: founder matches Co-Founder, Founder & CEO, and CEO and Co-Founder, but not Founding Partner. Omit to include all titles; this does not filter titleFunction or titleLevel.", "in": "query", "name": "role", "required": false, "schema": { "type": "string" } }, { "description": "Current association filter", "in": "query", "name": "isCurrent", "required": false, "schema": { "type": "boolean" } }, { "description": "Include person URL records", "in": "query", "name": "includeUrl", "required": false, "schema": { "type": "boolean" } }, { "description": "Include person address records", "in": "query", "name": "includeAddress", "required": false, "schema": { "type": "boolean" } }, { "description": "Writes only: the person's slug when the body omits personId. List reads ignore it; use search to narrow listed people.", "in": "query", "name": "personSlug", "required": false, "schema": { "type": "string" } }, { "description": "Return count metadata without full content", "in": "query", "name": "countOnly", "required": false, "schema": { "type": "boolean" } }, { "description": "Permit generated monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityPersonAssociation" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get One Person's Role at a Company", "tags": [ "Entity Person Associations" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/person-investors": { "get": { "description": "Lists person investors with per-round investorAttribution rows. Use entityId for the fundraising/portfolio company being invested in, whose investors to list — always a company, never an investor fund or firm. amountInvested appears only inside investorAttribution, is a plain decimal number in the fundraise transaction currency, and is not added to amountRaised. Valid sort syntax is sort=amountInvested,desc; do not use investorAttribution.amountInvested, amount_invested, currency signs, currency codes, comma grouping, or abbreviated values.", "operationId": "listEntityPersonInvestors", "parameters": [ { "description": "Zero-based page index for offset paging; omit it for the first page. Ignored when cursor is sent: to continue a cursor traversal, send the X-Next-Cursor value as cursor and leave page out.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "Entity unique identifier (UUID).", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Permit generated monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Opaque URL-safe cursor token from X-Next-Cursor. Reuse the same filters and sort.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePersonInvestorParticipation" } } }, "description": "OK", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token, present when another page exists; send it as cursor to read that page. The body's number, first, and totalPages describe offset paging only; they do not advance while you follow cursors.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Person Investors", "tags": [ "Entity Fundraise" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/relationships": { "get": { "description": "Returns relationship rows touching the path entity. Defaults to renderable-only rows where isCurrent=true and isPrimary=true. Set includeInactive=true to also return historic and non-primary rows; each row carries id, isCurrent, and isPrimary. Use entities relationships get to retrieve one row by id without an entity path.", "operationId": "listEntityRelationships", "parameters": [ { "description": "Canonical entity UUID", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Optional EntityRelationshipType filter, one of: acceleratorParticipant, acquirer, affinity, calculated, competingProductService, competitor, customer, fundManagerFirm, parent, productService, serviceProvider, similarCompany, spinOffFrom, successor. Use entities relationships types list for valid values.", "in": "query", "name": "type", "required": false, "schema": { "type": "string" } }, { "description": "Include historic or non-primary rows. Default false returns only rows where isCurrent=true and isPrimary=true.", "in": "query", "name": "includeInactive", "required": false, "schema": { "type": "boolean", "default": false } }, { "deprecated": true, "description": "Deprecated alias for includeInactive.", "in": "query", "name": "includeNonRenderable", "required": false, "schema": { "type": "boolean", "default": false } }, { "description": "Opaque URL-safe cursor token from X-Next-Cursor. Reuse the same filters and sort.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "When true, returns direct curated competitors with each competitor's provider comparison signals (sells-to, pricing, ownership, funding, website) nested under its productService row. Competition is not transitively closed: A-B plus B-C surfaces B from A, never C. With type=productService on a company, returns each of its Product/Service rows nesting those direct competitor rows, so one call covers every product line. Only supported for type=competingProductService or type=productService; the result is capped, so cursor and includeInactive are not accepted alongside transitive=true.", "in": "query", "name": "transitive", "required": false, "schema": { "type": "boolean", "default": false } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityRelationship" } } }, "description": "OK", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token, present when another page exists; send it as cursor to read that page. The body's number, first, and totalPages describe offset paging only; they do not advance while you follow cursors.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's Relationships", "tags": [ "Entity Relationships" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/repositories": { "get": { "description": "Returns the entity's synced GitHub repositories, paged. Default sort is stargazerCount desc, then name.", "operationId": "listEntityRepositories", "parameters": [ { "description": "Entity UUID owning the repositories", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageGithubRepo" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List a Company's GitHub Repositories", "tags": [ "Repositories" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/research": { "get": { "description": "Returns the consolidated research for a company.", "operationId": "getEntityResearch", "parameters": [ { "description": "Canonical entity UUID.", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResearch" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get the Research Gathered About a Company", "tags": [ "Entity Research" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/research-details": { "get": { "description": "Returns paginated research details for an entity. Optionally filter by detail type. Rows for timeSeries=true types are history, not stale current state.", "operationId": "listEntityResearchDetails", "parameters": [ { "description": "Canonical entity UUID.", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Zero-based page index (0..N)", "example": 0, "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "description": "The size of the page to be returned", "example": 25, "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25 } }, { "description": "Research detail type token. Run GET /v1/entities/research-details/types (CLI: entities research-details types list) for the token inventory and each token's value shape.", "example": "nameCongruencyScore", "in": "query", "name": "type", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityResearchDetail" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List Research Details", "tags": [ "Entity Research" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/research-details/{detailId}": { "get": { "description": "Returns one research detail for an entity.", "operationId": "getEntityResearchDetail", "parameters": [ { "description": "Canonical entity UUID.", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Research detail id.", "example": 6444, "in": "path", "name": "detailId", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResearchDetail" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get Research Detail", "tags": [ "Entity Research" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/research-snippets": { "get": { "description": "Returns paginated research snippets for one entity. Public reads omit hidden rows and private provenance fields; privileged private reads include hidden rows. Sorting is fixed by the server.", "operationId": "listEntityResearchSnippets", "parameters": [ { "description": "Canonical entity UUID.", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Zero-based page index (0..N)", "example": 0, "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "description": "The size of the page to be returned", "example": 25, "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityResearchSnippet" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List Research Snippets", "tags": [ "Entity Research" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/research-snippets/{snippetId}": { "get": { "description": "Returns one research snippet for an entity. Public reads omit private provenance fields.", "operationId": "getEntityResearchSnippet", "parameters": [ { "description": "Canonical entity UUID.", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Research snippet id.", "example": 538, "in": "path", "name": "snippetId", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResearchSnippet" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get Research Snippet", "tags": [ "Entity Research" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/similar": { "get": { "description": "Returns similar entities for the UUID at this address, ordered by similarity score. Rows include the entity and similarity provenance. Use relationshipType to filter stored relationships. Custom sorting is unsupported. Any signed-in user may call this on every plan. The list is free: it never counts against the monthly record-view allowance, which charges only a separate full-detail view of one record.", "operationId": "listEntitySimilarEntities", "parameters": [ { "description": "Entity unique identifier (UUID)", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Filter by stored relationship type, one of: acceleratorParticipant, acquirer, affinity, calculated, competingProductService, competitor, customer, fundManagerFirm, parent, productService, serviceProvider, similarCompany, spinOffFrom, successor.", "example": "competitor", "in": "query", "name": "relationshipType", "required": false, "schema": { "type": "string" } }, { "description": "Optional entity typeRecord filter. Repeat to allow multiple entity types.", "example": "Company", "in": "query", "name": "typeRecord", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "Permit monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 10, "minimum": 1 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntitySimilarityResult" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get Similar Companies by ID", "tags": [ "Entity Similar" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/similar/summary": { "get": { "description": "Returns the same similar entities, order, and totals as GET /v1/entities/{entityId}/similar with lean rows: entity core, current URL links, and similarity provenance. Use it for rails and cards that do not render list enrichment. Custom sorting is unsupported. Any signed-in user may call this on every plan. The list is free: it never counts against the monthly record-view allowance, which charges only a separate full-detail view of one record.", "operationId": "listEntitySimilarSummaries", "parameters": [ { "description": "Entity unique identifier (UUID)", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Filter by stored relationship type, one of: acceleratorParticipant, acquirer, affinity, calculated, competingProductService, competitor, customer, fundManagerFirm, parent, productService, serviceProvider, similarCompany, spinOffFrom, successor.", "example": "competitor", "in": "query", "name": "relationshipType", "required": false, "schema": { "type": "string" } }, { "description": "Optional entity typeRecord filter. Repeat to allow multiple entity types.", "example": "Company", "in": "query", "name": "typeRecord", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "Permit monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 10, "minimum": 1 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntitySimilaritySummary" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get Similar Company Summaries by ID", "tags": [ "Entity Similar" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/slug": { "get": { "description": "Returns the current slug, canonical path, and public URL. Any signed-in user may call this.", "operationId": "getEntitySlug", "parameters": [ { "description": "Entity UUID", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlugLocation" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a Company's Slug", "tags": [ "Record Slugs" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/texts": { "get": { "description": "Returns paginated text rows owned by the entity. Inactive or private rows require read auth.", "operationId": "listEntityTexts", "parameters": [ { "description": "Entity UUID owning the text rows", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityText" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's Text", "tags": [ "Texts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/texts/{textId}": { "get": { "description": "Returns one entity-owned text row by id. Requires read auth.", "operationId": "getEntityText", "parameters": [ { "description": "Entity UUID owning the text row", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Text row id", "in": "path", "name": "textId", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityText" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Piece of Company Text", "tags": [ "Texts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/trending-news": { "get": { "description": "Returns trending news semantically related to the company named by the entity id path parameter.", "operationId": "listEntityTrendingNews", "parameters": [ { "description": "Canonical entity UUID.", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 10, "minimum": 1 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageNews" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Trending News About a Company", "tags": [ "Semantic Similarity" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/unique-ids": { "get": { "description": "Returns paginated external identifier mappings for one owner. Sort by id, idType, identifier, createdAt, or updatedAt; default is updatedAt descending.", "operationId": "listEntityUniqueIds", "parameters": [ { "description": "Canonical entity UUID.", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageUniqueId" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List a Company's Identifiers", "tags": [ "Identifiers" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/unique-ids/{uniqueIdId}": { "get": { "description": "Returns one external identifier mapping after verifying it belongs to the path owner.", "operationId": "getEntityUniqueId", "parameters": [ { "description": "Canonical entity UUID.", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Unique-id row id.", "example": 42, "in": "path", "name": "uniqueIdId", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniqueId" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Company Identifier", "tags": [ "Identifiers" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/urls": { "get": { "description": "Returns paged primary current URL rows owned by an entity. Set includeInactive=true as a signed-in user or with read credentials to include secondary active and inactive/historical rows.", "operationId": "listEntityUrls", "parameters": [ { "description": "Entity UUID owning the URL rows", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Include secondary active and inactive/historical URL rows", "in": "query", "name": "includeInactive", "required": false, "schema": { "type": "boolean", "default": false } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityUrlLink" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's URLs", "tags": [ "URL Links" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/urls/{urlId}": { "get": { "description": "Returns one entity-owned URL row by id. Requires read auth.", "operationId": "getEntityUrl", "parameters": [ { "description": "Entity UUID owning the URL row", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "URL link id", "in": "path", "name": "urlId", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityUrlLink" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Company URL", "tags": [ "URL Links" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/entities/{entityId}/valuations": { "get": { "description": "Returns newest-first, per-UTC-month valuation points composed from stated latestValuation research details plus fundraise-round valuations. Only researchDetail points have detailId and can be changed here; fundraiseRound points are read-only here. Custom sort is not supported.", "operationId": "listEntityValuations", "parameters": [ { "description": "Entity unique identifier (UUID).", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "entityId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityValuationTimeSeriesPoint" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Company's Valuation Over Time", "tags": [ "Entity Fundraise" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/help": { "post": { "description": "Answers a question about how to use aVenture, citing the operations it draws on. A question it cannot answer returns LOW confidence instead of a guessed command. With resolve, it returns a recommended operation or workflow, or a clarifying question, instead of a written answer, under its own per-account limit. Free for every signed-in account.", "operationId": "askHelpQuestion", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHelpQuestion" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHelp" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Answer a Natural-Language Platform Help Question", "tags": [ "Agents" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/lookup": { "get": { "description": "Returns what aVenture knows about a subject: MATCHED, NO_MATCH, or NEEDS_REVIEW among the records you can see, honoring the requested type and provider. To identify a subject with every lookup option, use POST /v1/lookup. Send name, url, or both; neither answers 422. A NO_MATCH subject whose own site a web search finds, and whose live page names it, is added as a new unpublished record automatically and returned in created; that record is not queued for research. An exact id, handle, or slug answers without spending quota; past it, name-identification quota and live deadlines apply. A signed-in caller that sends Prefer: respond-async gets 202 with a Location status URL instead: a lookup job runs this same identification without the live deadline, and GET /v1/lookup-jobs/{jobId} returns it as identification once COMPLETED. A repeat of the same request returns the same job while it is still PENDING or RUNNING.", "operationId": "getIdentification", "parameters": [ { "description": "Name exactly as the source writes it, such as Acme AI or Jane Doe. Send name, url, or both; a name that is an absolute http(s) URL is read as url.", "example": "Stripe", "in": "query", "name": "name", "required": false, "schema": { "type": "string", "description": "Name exactly as the source writes it, such as Acme AI or Jane Doe. Send name, url, or both; a name that is an absolute http(s) URL is read as url.", "example": "Stripe", "maxLength": 200, "minLength": 0 } }, { "description": "URLs the subject owns: its website, its LinkedIn company or person profile, an aVenture page, or a registry page. At most 10. Required when name is omitted. Put articles in sourceUrl.", "example": [ "https://stripe.com" ], "in": "query", "name": "url", "required": false, "schema": { "type": "array", "description": "URLs the subject owns: its website, its LinkedIn company or person profile, an aVenture page, or a registry page. At most 10. Required when name is omitted. Put articles in sourceUrl.", "example": [ "https://stripe.com" ], "items": { "type": "string", "description": "URLs the subject owns: its website, its LinkedIn company or person profile, an aVenture page, or a registry page. At most 10. Required when name is omitted. Put articles in sourceUrl.", "example": [ "https://stripe.com" ] }, "maxItems": 10, "minItems": 0 } }, { "description": "City, region, or country, such as Austin, TX. Tells namesakes apart; not proof on its own.", "example": "San Francisco, CA", "in": "query", "name": "location", "required": false, "schema": { "type": "string", "description": "City, region, or country, such as Austin, TX. Tells namesakes apart; not proof on its own.", "example": "San Francisco, CA", "maxLength": 2000, "minLength": 0 } }, { "description": "Specific facts in plain words: product, industry, employer and title, or founder names. Generic words like startup add nothing.", "example": "Online payments company", "in": "query", "name": "context", "required": false, "schema": { "type": "string", "description": "Specific facts in plain words: product, industry, employer and title, or founder names. Generic words like startup add nothing.", "example": "Online payments company", "maxLength": 2000, "minLength": 0 } }, { "description": "aVenture news id of the article that mentions the subject; an unknown id is a 400.", "example": 123456, "in": "query", "name": "sourceNewsId", "required": false, "schema": { "type": "integer", "format": "int32", "description": "aVenture news id of the article that mentions the subject; an unknown id is a 400.", "example": 123456 } }, { "description": "URL of the article that mentions the subject; read from aVenture news when stored there, otherwise fetched.", "example": "https://techcrunch.com/2024/01/01/example", "in": "query", "name": "sourceUrl", "required": false, "schema": { "type": "string", "description": "URL of the article that mentions the subject; read from aVenture news when stored there, otherwise fetched.", "example": "https://techcrunch.com/2024/01/01/example", "maxLength": 2000, "minLength": 0 } }, { "description": "Entity type to identify. A Product or Service never matches its provider organization, but a record stored under a neighboring type of the same family (Product or Service; Fund, Investment Firm, or Company) still matches, and a Business Line lookup sees both families. Invalid for a person lookup.", "in": "query", "name": "typeRecord", "required": false, "schema": { "$ref": "#/components/schemas/EntityType" } }, { "description": "Provider entity id for a Product or Service lookup. Omit it when the provider is unknown. With no typeRecord, searches both Product and Service. Invalid for a company type or a person lookup.", "in": "query", "name": "providerId", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Provider entity id for a Product or Service lookup. Omit it when the provider is unknown. With no typeRecord, searches both Product and Service. Invalid for a company type or a person lookup." } }, { "description": "Kind of record to identify when you know it: ENTITY for companies, funds, and firms (and their products or services); PERSON for people. Only that kind is looked up; typeRecord or providerId implies ENTITY.", "in": "query", "name": "kind", "required": false, "schema": { "type": "string", "description": "Which kind of record a lookup identifies: ENTITY for companies, funds, investment firms, products, and services; PERSON for people. No other value is accepted (send ENTITY, not company). Only that kind is looked up; omit it to compare both kinds.", "enum": [ "ENTITY", "PERSON" ] } }, { "description": "Identifier type token, for example ein, secCik, or ticker.", "in": "query", "name": "sourceIdentifier.idType", "required": false, "schema": { "type": "string", "description": "Identifier type token, for example ein, secCik, or ticker." } }, { "description": "Identifier value as issued by the registry.", "in": "query", "name": "sourceIdentifier.identifier", "required": false, "schema": { "type": "string", "description": "Identifier value as issued by the registry." } }, { "description": "Optional attribution source label for the mapping.", "in": "query", "name": "sourceIdentifier.source", "required": false, "schema": { "type": "string", "description": "Optional attribution source label for the mapping." } }, { "description": "Send respond-async to request a pollable lookup job; exact matches answer live.", "in": "header", "name": "Prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identification" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnqueue" } } }, "description": "Sent with Prefer: respond-async (and Preference-Applied: respond-async), or without it to a signed-in caller once its paid live attempt, past the free exact match, ran out of time or left a provider still running: a lookup job was filed and finishes the lookup, adding no record for a NO_MATCH; poll the Location status URL after Retry-After.", "headers": { "Location": { "description": "Status URL of the accepted lookup job", "schema": { "type": "string", "format": "uri-reference" }, "style": "simple" }, "Retry-After": { "description": "Seconds to wait before polling the status URL", "schema": { "type": "integer" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Read a Company, Product, Service, or Person Identity", "tags": [ "Search" ], "x-aventure-tool": { "mutates": true }, "x-aventure-visibility": { "scope": "public" } }, "post": { "description": "Identifies the company, Product, Service, or person that a name, URL, or id refers to among the records you can see. Send name, at least one url, or both; neither answers 422, and a name that is a URL is read as url. Optional clues narrow the answer: kind (ENTITY or PERSON) when you know which kind the subject is, typeRecord or providerId for a Product or Service from a known provider, and context such as an employer or title. A name that is exactly a record's id, public handle, registry id (ticker, LEI, EIN), or slug answers at once. status is MATCHED, NEEDS_REVIEW, or NO_MATCH. MATCHED: match.owner names one record, by entityId (match.record.typeRecord tells a company from a Product or Service; read it with GET /v1/entities/{entityId}) or by personId (read it with GET /v1/people/{personId}). NEEDS_REVIEW: more than one record fits, such as a company and a person sharing a name; candidate lists them, and resending with a URL the subject owns or its kind usually settles it. NO_MATCH: no record you can see was confirmed as this subject; a former, alternate, or legal name may still match through the entityName filter of GET /v1/entities. A NO_MATCH subject whose own site a web search finds, and whose live page names it, is added as a new unpublished record with its name, website, and logo, returned as created, and not queued for research; adding it spends no research unit. Queue research on an added record with POST /v1/entities/{entityId}/enrichments or POST /v1/people/{personId}/enrichments. Set scheduleEnrichment=true to queue research on an existing match. Accept: text/event-stream streams the same answer as server-sent events. With legacy=true, name is read only as an exact id, public handle, registry id, or slug: no model call, no web search, and 404 when nothing matches. Example body: {\"name\":\"Acme AI\",\"url\":[\"https://acme.ai\"]}. A signed-in caller that sends Prefer: respond-async gets 202 with a Location status URL instead: a lookup job runs this same identification without the live deadline, and GET /v1/lookup-jobs/{jobId} returns it as identification once COMPLETED. A repeat of the same request returns the same job while it is still PENDING or RUNNING.", "operationId": "lookupRecord", "parameters": [ { "description": "Treat name only as an exact id, public handle, registry id, or slug: no model call, no web search, and 404 when nothing matches. An exact match never spends the name-identification quota, with or without this flag.", "in": "query", "name": "legacy", "required": false, "schema": { "type": "boolean" } }, { "description": "For an existing match, true queues research; omitted or false does not. A record this lookup adds is not queued for research; queue it with the record's enrichments route.", "in": "query", "name": "scheduleEnrichment", "required": false, "schema": { "type": "boolean" } }, { "description": "Probe submitted URLs and return fresh canonical host-form evidence; defaults to false.", "in": "query", "name": "verifyUrl", "required": false, "schema": { "type": "boolean" } }, { "description": "Send respond-async to request a pollable lookup job, which adds no record; verifyUrl=true answers live.", "in": "header", "name": "Prefer", "schema": { "type": "string" } }, { "description": "Stable intake identity for requested status verification; reuse it to recover the accepted job.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentificationSubject" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identification" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "The identification as canonical JSON or compact text/plain.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identification" } } }, "description": "A NO_MATCH subject with a proven own site, added as a new unpublished record and answered as JSON: the body carries it as created, and Location is that record's URL; a text/plain answer stays 200.", "headers": { "Location": { "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnqueue" } } }, "description": "Sent with Prefer: respond-async (and Preference-Applied: respond-async), or without it to a signed-in caller once its paid live attempt, past the free exact match, ran out of time or left a provider still running: a lookup job was filed and finishes the lookup, adding no record for a NO_MATCH; poll the Location status URL after Retry-After.", "headers": { "Location": { "description": "Status URL of the accepted lookup job", "schema": { "type": "string", "format": "uri-reference" }, "style": "simple" }, "Retry-After": { "description": "Seconds to wait before polling the status URL", "schema": { "type": "integer" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Without a paid aVenture plan a caller gets a free daily allowance of name identifications per UTC day; past it the lookup answers 402 with code subscription_required (subscription_canceled, subscription_past_due, or subscription_paused when a plan lapsed), carrying limit, used, remaining, resetAt, and a Retry-After header." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Identify a Company, Product, Service, or Person by Name, URL, or ID", "tags": [ "Search" ], "x-aventure-tool": { "auth": "read", "mutates": true }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/lookup-jobs": { "post": { "description": "Without maxNames, reads one article (sourceUrl or sourceNewsId), identifies up to the article limit, and creates a new unpublished record (with its logo and a research request) for a new name only when a second live page also names it. With maxNames, identifies up to that bound from an article or mention names alone, without creating records or requesting research. An article read spends one natural-search slot; accepting a new job spends name-identification slots for its limit. Poll GET /v1/lookup-jobs/{jobId}; the same request sent again soon reuses its paid job.", "operationId": "createLookupJob", "parameters": [ { "description": "Opt in to lookup-only bulk; cap is 1 through app.jobs.lookup-job.bulk-mention-limit. Accepts an article or mention names alone; no shells or enrichment are scheduled.", "in": "query", "name": "maxNames", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupJobMutation" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnqueue" } } }, "description": "The lookup job was accepted; poll its status URL.", "headers": { "Location": { "description": "Endpoint to poll for the job state and result.", "schema": { "type": "string", "format": "uri-reference" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Without a paid aVenture plan a caller gets a free daily allowance of name identifications per UTC day; past it the lookup answers 402 with code subscription_required (subscription_canceled, subscription_past_due, or subscription_paused when a plan lapsed), carrying limit, used, remaining, resetAt, and a Retry-After header." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Start an Article Lookup or a Bounded Lookup-Only Bulk Job", "tags": [ "Search", "Lookup Jobs" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/lookup-jobs/{jobId}": { "get": { "description": "Returns the job state: 202 with Retry-After while PENDING or RUNNING, 200 once terminal. Once COMPLETED, it returns each identified name: MATCHED names the stored record, NEEDS_REVIEW lists candidates, and a failed name carries failureReason. Ordinary article jobs may include shell, enrichmentRunId, or shellDetail on NO_MATCH. Bulk jobs return maxNames and limitReached; reaching the bound means more names may remain. A single-subject job, filed by Prefer: respond-async on GET or POST /v1/lookup or POST /v1/entities/lookup, or by a signed-in live lookup on those routes that rolled over to a job, carries source.subject and, once COMPLETED, identification: the answer that route returns. Only the requesting caller can read the job.", "operationId": "getLookupJob", "parameters": [ { "description": "Lookup job id from the create response.", "in": "path", "name": "jobId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupJob" } } }, "description": "The job is terminal: COMPLETED, FAILED, or CANCELED.", "headers": { "ETag": { "description": "Revision of this job snapshot; send it as If-None-Match for 304", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupJob" } } }, "description": "The job is PENDING or RUNNING; poll the same URL again after Retry-After.", "headers": { "Cache-Control": { "description": "Always no-store: the state changes under the same URL", "schema": { "type": "string" }, "style": "simple" }, "Location": { "description": "This status URL; poll it again", "schema": { "type": "string", "format": "uri-reference" }, "style": "simple" }, "Retry-After": { "description": "Seconds to wait before polling again", "schema": { "type": "integer" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a Lookup Job's State and the Records Its Article Names", "tags": [ "Search", "Lookup Jobs" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/lookup-mentions": { "post": { "description": "Reads a page (sourceUrl or sourceNewsId), a recorded document such as an email (sourceDocumentId, sent alone), a screenshot (multipart file part), or a page and screenshot, lists every company, organization, investor, and person it names, and identifies each one as POST /v1/lookup would, with the page as its source. A page fetched from sourceUrl first lists its own site's company, looked up by that site's URL, unless the site is a news outlet, a shared platform such as LinkedIn, or aVenture; when no record holds that site, it is added from the name the site declares, as POST /v1/lookup adds a URL. A caller that read the names itself sends them as mention instead, alone, so neither page nor screenshot leaves it. Answers within seconds: a name still identifying when the time is up carries failureReason instead of identification; send it alone to POST /v1/lookup. Each NO_MATCH name whose own site a web search finds, and whose live page names it, is added as a new unpublished record, queued for research unless scheduleEnrichment=false, and returned as shell; adding it spends no research unit, and a name not added carries shellDetail saying why. Needs a signed-in user. Each name spends one name-identification quota slot, as POST /v1/lookup does; reading a page or screenshot also spends one natural-search slot and the free daily lookup allowance (20 name lookups per UTC day), sending mention does neither. JSON body: {\"sourceUrl\":\"https://techcrunch.com/2024/01/01/example\"} or {\"mention\":[{\"name\":\"Visa\",\"type\":\"COMPANY\"}]}; multipart: a file part plus an optional JSON body part.", "operationId": "lookupMentions", "parameters": [ { "description": "Omitted or true queues research on each record this lookup adds; false adds it without queueing research. Its logo import starts either way, and a matched record is never queued here.", "in": "query", "name": "scheduleEnrichment", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupJobMutation" } }, "multipart/form-data": { "encoding": { "body": { "contentType": "application/json" } }, "schema": { "type": "object", "properties": { "body": { "$ref": "#/components/schemas/LookupJobMutation" }, "file": { "type": "string", "format": "binary", "description": "Screenshot (PNG, JPEG, or WebP); CLI accepts a local path or URL." } } } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MentionLookup" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Every mention as canonical JSON or complete compact text/plain.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Without a paid aVenture plan a caller gets a free daily allowance of name identifications per UTC day; past it the lookup answers 402 with code subscription_required (subscription_canceled, subscription_past_due, or subscription_paused when a plan lapsed), carrying limit, used, remaining, resetAt, and a Retry-After header." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Identify Every Company and Person a Page or Screenshot Names", "tags": [ "Search" ], "x-aventure-tool": { "mutates": true }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/metrics": { "get": { "description": "Global metrics snapshot. Companies tracked (companies and investment firms combined), total funding, trailing 30-day funding, investors, people, countries, cities. Totals are a periodically refreshed snapshot, so they can trail recent changes.", "operationId": "getSystemGlobalMetrics", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemGlobalMetrics" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get Platform Totals for Companies, Funding, and People", "tags": [ "System" ], "x-aventure-tool": { "auth": "none" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/news": { "get": { "description": "Browse recent news articles, newest published first unless sort says otherwise, with optional filtering. A company's news is this list filtered by owner.entityId (CLI --owner-entity-id); a person's by owner.personId (CLI --owner-person-id). This is the article list: the entities an article is about come from the semantic-similarity read, not here.", "operationId": "listNews", "parameters": [ { "description": "The size of the page to be returned; default and maximum 25 for the standard list, where larger values are reduced to that maximum. Entity, person, author-initial, and thin-mode reads accept larger pages.", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1 } }, { "description": "Full-text news search term.", "in": "query", "name": "search", "required": false, "schema": { "type": "string", "description": "Full-text news search term." } }, { "description": "News category slug to include or exclude.", "in": "query", "name": "category", "required": false, "schema": { "type": "string", "description": "News category slug to include or exclude." } }, { "description": "Owning entity id; set only when personId is absent.", "in": "query", "name": "owner.entityId", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, { "description": "Owning person id; set only when entityId is absent.", "in": "query", "name": "owner.personId", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Exclude one news article by id.", "in": "query", "name": "excludeId", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Type-safe identifier for news articles" } }, { "description": "Earliest publication date, inclusive.", "in": "query", "name": "publishedAfter", "required": false, "schema": { "type": "string", "format": "date", "description": "Earliest publication date, inclusive." } }, { "description": "Latest publication date, inclusive.", "in": "query", "name": "publishedBefore", "required": false, "schema": { "type": "string", "format": "date", "description": "Latest publication date, inclusive." } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageNews" } } }, "description": "OK", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token when cursor traversal has another page.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List News Articles, Including a Company's or Person's News", "tags": [ "News" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/news/feedback": { "post": { "description": "Records feedback on a news article.", "operationId": "createNewsFeedback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsFeedback" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsFeedbackAcknowledgement" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Submit News Feedback", "tags": [ "News" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/news/lookup": { "get": { "description": "Resolves news detail by slug, external ID, URL, or bounded title candidate signals. Use the numeric item route for an id; any id query is rejected. Canonical redirects are preserved.", "operationId": "lookupNews", "parameters": [ { "description": "Exact news article slug (URL-friendly identifier). Mutually exclusive with id, externalId, url, and title.", "in": "query", "name": "slug", "required": false, "schema": { "type": "string", "description": "Canonical lowercase URL slug for the resource", "example": "aventure-vc", "maxLength": 255, "pattern": "^[a-z0-9_-]+$" } }, { "description": "External ID or RSS GUID for ingestion-key lookup. Mutually exclusive with id, slug, url, and title.", "in": "query", "name": "externalId", "required": false, "schema": { "type": "string", "description": "External ID or RSS GUID for ingestion-key lookup. Mutually exclusive with id, slug, url, and title." } }, { "description": "Original article URL to resolve via strict host+path or domain-only match. Mutually exclusive with id, slug, and externalId. May pair with title and publication to narrow candidate recovery after an exact URL miss. Pair with urlMatchMode to disambiguate.", "in": "query", "name": "url", "required": false, "schema": { "type": "string", "description": "Original article URL to resolve via strict host+path or domain-only match. Mutually exclusive with id, slug, and externalId. May pair with title and publication to narrow candidate recovery after an exact URL miss. Pair with urlMatchMode to disambiguate." } }, { "description": "Candidate lookup signal: article title. Mutually exclusive with id, slug, and externalId. Combine with publication, urlDomain, or url for bounded candidate search.", "in": "query", "name": "title", "required": false, "schema": { "type": "string", "description": "Candidate lookup signal: article title. Mutually exclusive with id, slug, and externalId. Combine with publication, urlDomain, or url for bounded candidate search." } }, { "description": "Publication qualifier (e.g., 'TechCrunch', 'Forbes'). Narrows a title candidate search. Not an identifier on its own.", "in": "query", "name": "publication", "required": false, "schema": { "type": "string", "description": "Publication qualifier (e.g., 'TechCrunch', 'Forbes'). Narrows a title candidate search. Not an identifier on its own." } }, { "description": "Candidate lookup URL domain qualifier (host only, no path). Narrows a title candidate search. Not an identifier on its own.", "in": "query", "name": "urlDomain", "required": false, "schema": { "type": "string", "description": "Candidate lookup URL domain qualifier (host only, no path). Narrows a title candidate search. Not an identifier on its own." } }, { "description": "URL match mode qualifier: 'hostPath' (strict host + path match, default) or 'domain' (host-only match). Narrows url and urlDomain matching. Not an identifier on its own.", "in": "query", "name": "urlMatchMode", "required": false, "schema": { "type": "string", "description": "URL match mode qualifier: 'hostPath' (strict host + path match, default) or 'domain' (host-only match). Narrows url and urlDomain matching. Not an identifier on its own." } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsDetail" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "News detail as canonical JSON or compact text.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "301": { "description": "Redirect to new slug location", "headers": { "Location": { "description": "Redirect target", "style": "simple" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Ambiguous candidate signals: more than one article still matches the supplied title/URL bundle. ProblemDetail carries details.newsCandidate; review those ids, update the matching article, and create only when all candidates are distinct and source evidence supports the target. score and threshold are review ranking, not absence proof. Resolve directly by id, slug, or externalId." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Look Up One News Article", "tags": [ "News" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/news/subscriptions": { "delete": { "description": "Removes the caller's webhook subscription with this event, entity, and url.", "operationId": "unsubscribeNewsSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSubscriptionKey" } } }, "required": true }, "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Unsubscribe From Entity News", "tags": [ "News" ], "x-aventure-visibility": { "scope": "public" } }, "get": { "description": "The caller's news webhook subscriptions with each one's delivery state. The signing secret is never returned; each item's subscription is the unsubscribe body.", "operationId": "listNewsSubscriptions", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NewsSubscriptionDetail" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List Entity News Subscriptions", "tags": [ "News" ], "x-aventure-visibility": { "scope": "public" } }, "put": { "description": "Creates or refreshes a webhook subscription to news newly linked to one entity. A new endpoint must echo a signed verification challenge before the subscription exists.", "operationId": "subscribeNewsSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSubscription" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSubscriptionGrant" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Subscribe to Entity News", "tags": [ "News" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/news/subscriptions/{subscriptionId}/test-events": { "post": { "description": "POSTs one signed sample entity.news.published event to the caller's subscription url and returns the receiver's HTTP status. The cursor and retry state do not change. An unanswered POST answers 422 with its callback_* code.", "operationId": "sendNewsSubscriptionTestEvent", "parameters": [ { "description": "Subscription id from subscribe or list.", "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSubscriptionTestEvent" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Send a Test News Event", "tags": [ "News" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/news/{newsId}": { "get": { "description": "Returns news detail by exact positive ID. Use lookup for a slug, external ID, URL, or title candidates.", "operationId": "getNews", "parameters": [ { "description": "Exact positive news article id.", "in": "path", "name": "newsId", "required": true, "schema": { "type": "integer", "format": "int32", "description": "Type-safe identifier for news articles" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsDetail" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "News detail as canonical JSON or compact text.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One News Article", "tags": [ "News" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/news/{newsId}/related-entities": { "get": { "description": "Returns entities semantically related to a news article — the article's entity mentions, not a list of articles; the article list itself is the news list.", "operationId": "listNewsRelatedEntities", "parameters": [ { "description": "News article id whose semantic neighbors should be returned.", "in": "path", "name": "newsId", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-aventure-legacy-name": { "name": "id" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 10, "minimum": 1 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntity" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the Entities a News Article Is About", "tags": [ "Semantic Similarity" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/news/{newsId}/thumbnail": { "get": { "description": "Returns the article's attached thumbnail with its stored provenance; an empty slot returns 404, so read presence from `core.newsImageThumbnail` on `news get`.", "operationId": "getNewsThumbnail", "parameters": [ { "description": "Exact positive news article id", "in": "path", "name": "newsId", "required": true, "schema": { "type": "integer", "format": "int32", "description": "Type-safe identifier for news articles" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUpload" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get News Thumbnail", "tags": [ "News Thumbnail" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people": { "get": { "description": "List people with the same filters and sort as POST /v1/people/search, passed as query parameters. Use the POST search for semantic ranking or a JSON body, and POST /v1/search/natural/people for plain English.", "operationId": "listPeople", "parameters": [ { "description": "Person first name.", "in": "query", "name": "firstName", "required": false, "schema": { "type": "string", "description": "Person first name." } }, { "description": "Person last name.", "in": "query", "name": "lastName", "required": false, "schema": { "type": "string", "description": "Person last name." } }, { "description": "Person workflow status.", "in": "query", "name": "status", "required": false, "schema": { "type": "string", "description": "Person workflow status." } }, { "description": "Associated entity names.", "in": "query", "name": "arrayFilter.entityName", "required": false, "schema": { "type": "array", "description": "Associated entity names.", "items": { "type": "string", "description": "Associated entity names." } } }, { "description": "Associated entity type scope. Omit or use [] for any associated type.", "in": "query", "name": "arrayFilter.typeRecord", "required": false, "schema": { "type": "array", "description": "Associated entity type scope. Omit or use [] for any associated type.", "items": { "$ref": "#/components/schemas/EntityType" } } }, { "description": "Person titles.", "in": "query", "name": "arrayFilter.personTitle", "required": false, "schema": { "type": "array", "description": "Person titles.", "items": { "type": "string", "description": "Person titles." } } }, { "description": "Invested company names.", "in": "query", "name": "arrayFilter.investedCompany", "required": false, "schema": { "type": "array", "description": "Invested company names.", "items": { "type": "string", "description": "Invested company names." } } }, { "description": "Fundraise round labels.", "in": "query", "name": "arrayFilter.round", "required": false, "schema": { "type": "array", "description": "Fundraise round labels.", "items": { "type": "string", "description": "Fundraise round labels." } } }, { "in": "query", "name": "arrayFilter.amountRaisedRange", "required": false, "schema": { "type": "array", "description": "Selected per-investment amount-raised ranges (inclusive decimal bounds, USD) used to filter people by investment activity. Body syntax is [{\"min\":220000,\"max\":5000000}] with plain JSON numbers only.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "in": "query", "name": "arrayFilter.amountInvestedRange", "required": false, "schema": { "type": "array", "description": "Selected investor-level amount-invested ranges (inclusive decimal bounds) used to filter people by attributed investment activity. Body syntax is {\"arrayFilter\":{\"amountInvestedRange\":[{\"min\":220000,\"max\":5000000}]}} with plain JSON numbers in each fundraise transaction currency. Do not send currency signs, codes, commas, numeric strings, or abbreviated values.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "in": "query", "name": "arrayFilter.totalInvestmentCount", "required": false, "schema": { "type": "array", "description": "Selected total-investment-count ranges (inclusive integer bounds) used to filter people by the number of distinct fundraise deals they invested in.", "items": { "$ref": "#/components/schemas/IntRange" } } }, { "description": "Search keyword or phrase. Single characters valid; stop words rejected.", "example": "AI", "in": "query", "name": "search", "required": false, "schema": { "type": "string", "description": "Search keyword or phrase. Single characters valid; stop words rejected.", "example": "AI" } }, { "description": "Exact normalized match against a person's full name or slug.", "in": "query", "name": "personName", "required": false, "schema": { "type": "array", "description": "Exact normalized match against a person's full name or slug.", "items": { "type": "string", "description": "Exact normalized match against a person's full name or slug." } } }, { "description": "Restrict results to specific person IDs. Omit or use [] for no ID restriction.", "in": "query", "name": "personId", "required": false, "schema": { "type": "array", "description": "Restrict results to specific person IDs. Omit or use [] for no ID restriction.", "items": { "type": "string", "format": "uuid", "description": "Canonical person UUID" }, "maxItems": 200, "minItems": 0 } }, { "description": "First-name initial.", "example": "A", "in": "query", "name": "letter", "required": false, "schema": { "type": "string", "description": "First-name initial.", "example": "A" } }, { "description": "Associated entity UUID.", "in": "query", "name": "entityId", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Associated entity UUID." } }, { "description": "Associated entity slug.", "in": "query", "name": "entitySlug", "required": false, "schema": { "type": "string", "description": "Associated entity slug." } }, { "description": "Associated entity role or title.", "in": "query", "name": "role", "required": false, "schema": { "type": "string", "description": "Associated entity role or title." } }, { "description": "Filter current associations.", "in": "query", "name": "isCurrent", "required": false, "schema": { "type": "boolean", "description": "Filter current associations." } }, { "description": "Include URL links on each person", "in": "query", "name": "includeUrl", "required": false, "schema": { "type": "boolean", "description": "Include URL links on each person" } }, { "description": "Include addresses on each person", "in": "query", "name": "includeAddress", "required": false, "schema": { "type": "boolean", "description": "Include addresses on each person" } }, { "description": "Distinct fundraise-deal count ranges for an investor, with inclusive integer bounds.", "in": "query", "name": "investorActivity.totalInvestmentRange", "required": false, "schema": { "type": "array", "description": "Distinct fundraise-deal count ranges for an investor, with inclusive integer bounds.", "items": { "$ref": "#/components/schemas/IntRange" } } }, { "description": "Total USD amount-invested ranges with inclusive bounds.", "in": "query", "name": "investorActivity.totalAmountInvestedUsdRange", "required": false, "schema": { "type": "array", "description": "Total USD amount-invested ranges with inclusive bounds.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Average USD amount-invested ranges with inclusive bounds.", "in": "query", "name": "investorActivity.averageAmountInvestedUsdRange", "required": false, "schema": { "type": "array", "description": "Average USD amount-invested ranges with inclusive bounds.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Largest USD amount-invested ranges with inclusive bounds.", "in": "query", "name": "investorActivity.largestAmountInvestedUsdRange", "required": false, "schema": { "type": "array", "description": "Largest USD amount-invested ranges with inclusive bounds.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "Smallest USD amount-invested ranges with inclusive bounds.", "in": "query", "name": "investorActivity.smallestAmountInvestedUsdRange", "required": false, "schema": { "type": "array", "description": "Smallest USD amount-invested ranges with inclusive bounds.", "items": { "$ref": "#/components/schemas/DecimalRange" } } }, { "description": "When true, return only the page total in the body and skip the content payload.", "in": "query", "name": "countOnly", "required": false, "schema": { "type": "boolean" } }, { "description": "When true, sort people who have a photo before those who do not.", "in": "query", "name": "hasImageFirst", "required": false, "schema": { "type": "boolean" } }, { "description": "When false, monogram fallback logos are stripped from the response. Defaults to true.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePerson" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List People", "tags": [ "People" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/filters": { "get": { "description": "Returns available people filter facets — the option inventory a filter can take (titles, statuses, and the like), not people; searching or listing people by title uses the people search and list operations with their filters.", "operationId": "listPersonFilters", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFilterOptionSet" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Person Filter Options", "tags": [ "Person Metadata" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/filters/search": { "get": { "description": "Searches available people filter options.", "operationId": "searchPersonFilters", "parameters": [ { "description": "Filter key to search within", "in": "query", "name": "filterKey", "required": true, "schema": { "type": "string" } }, { "description": "Search keyword or phrase. Single characters valid; stop words rejected.", "example": "AI", "in": "query", "name": "search", "required": true, "schema": { "type": "string" } }, { "description": "Page index is fixed to 0 for filter search", "example": 0, "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "description": "The size of the page to be returned; filter-search default 20, maximum 100.", "example": 20, "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFilterSearchResult" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Search People Filter Options", "tags": [ "Person Metadata" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/lookup": { "post": { "deprecated": true, "description": "Deprecated: send the same body to lookup-from-file (POST /v1/lookup) with kind PERSON. Identifies which person a name refers to among the records you can see, and returns status MATCHED, NO_MATCH, or NEEDS_REVIEW. MATCHED: match.owner.personId is the person; read them with GET /v1/people/{personId} or queue research on them with POST /v1/people/{personId}/enrichments. NO_MATCH: no record you can see is this person. NEEDS_REVIEW: several candidates fit; resend with the person's LinkedIn or personal URL, and employer and title as context, to settle it. stage names the step that settled the answer: DETERMINISTIC (URL proof, no model call), JUDGMENT (a model review), or WEB_EVIDENCE (added a web search). The same name at a different employer is a different person. For full detail by exact slug or URL use GET /v1/people/lookup-exact. Example body: {\"name\":\"Jane Doe\",\"context\":\"CEO at Acme AI\"}.", "operationId": "lookupPerson", "parameters": [ { "description": "For an existing match, true queues research; omitted or false does not. A record this lookup adds is not queued for research; queue it with the record's enrichments route.", "in": "query", "name": "scheduleEnrichment", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentificationSubject" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identification" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "The identification as canonical JSON or compact text/plain.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Without a paid aVenture plan a caller gets a free daily allowance of name identifications per UTC day; past it the lookup answers 402 with code subscription_required (subscription_canceled, subscription_past_due, or subscription_paused when a plan lapsed), carrying limit, used, remaining, resetAt, and a Retry-After header." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Deprecated: Find Which Person a Name Refers to, or Confirm They Are New", "tags": [ "Search" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/lookup-batch": { "post": { "description": "Enrich multiple people by id or slug with optional url, association, and address. When page and size are omitted, the full deduplicated batch is returned in request order. Sort is not supported for this fixed-order batch response. A signed-in user's read charges one view per distinct returned record against the monthly entity or person view allowance; a repeat read of the same record in the month is free, and an exhausted cap answers 429 with Retry-After.", "operationId": "lookupPersonBatch", "parameters": [ { "description": "Zero-based page index (0..N); omit page and size for the full batch.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Zero-based page index (0..N); omit page and size for the full batch." } }, { "description": "The size of the page to be returned; omit page and size for the full batch.", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "description": "The size of the page to be returned; omit page and size for the full batch." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonLookupBatch" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePersonDetail" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Look Up People in Bulk by ID or Slug", "tags": [ "People" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/lookup-exact": { "get": { "description": "Start here for any aventure.vc person profile URL, slug, or personal profile URL. Exact read: returns the full PersonDetail (names, profile, company roles, and investments) of the one person a slug, URL, or candidate signals prove, so do not re-read it with getPerson or listPeople; it answers 404 or 409 instead of guessing. To identify a person by name and clues, use GET /v1/lookup (CLI lookup --kind PERSON). Use the UUID item route for an id; any id query is rejected. Canonical redirects are preserved. A signed-in user's read charges one view per distinct returned record against the monthly entity or person view allowance; a repeat read of the same record in the month is free, and an exhausted cap answers 429 with Retry-After.", "operationId": "getPersonLookup", "parameters": [ { "description": "Group A — exact person slug (URL-friendly identifier). Mutually exclusive with id, url, and every candidate signal in group C.", "in": "query", "name": "slug", "required": false, "schema": { "type": "string", "description": "Group A — exact person slug (URL-friendly identifier). Mutually exclusive with id, url, and every candidate signal in group C." } }, { "description": "Group B — aventure.vc person profile URL (such as https://aventure.vc/people/) or the person's current profile URL, resolved via strict host+path or domain-only match. Mutually exclusive with id and slug; may be combined with group-C candidate signals for URL-first fallback.", "in": "query", "name": "url", "required": false, "schema": { "type": "string", "description": "Group B — aventure.vc person profile URL (such as https://aventure.vc/people/) or the person's current profile URL, resolved via strict host+path or domain-only match. Mutually exclusive with id and slug; may be combined with group-C candidate signals for URL-first fallback." } }, { "description": "Optional URL type qualifier for URL lookup (e.g., 'linkedin', 'twitter'). Narrows Group B (url) and Group C (urlDomain) matching. Not an identifier on its own.", "example": "linkedin", "in": "query", "name": "urlType", "required": false, "schema": { "type": "string", "description": "Optional URL type qualifier for URL lookup (e.g., 'linkedin', 'twitter'). Narrows Group B (url) and Group C (urlDomain) matching. Not an identifier on its own.", "example": "linkedin" } }, { "description": "URL match mode qualifier: 'hostPath' (strict host + path match, default) or 'domain' (host-only match). Not an identifier on its own.", "in": "query", "name": "urlMatchMode", "required": false, "schema": { "type": "string", "description": "URL match mode qualifier: 'hostPath' (strict host + path match, default) or 'domain' (host-only match). Not an identifier on its own." } }, { "description": "Group C — candidate lookup signal: person full name. Combine with other group-C signals (nameAny, location, urlDomain) for bounded candidate search. Mutually exclusive with id and slug; may be combined with url for fallback.", "in": "query", "name": "nameFull", "required": false, "schema": { "type": "string", "description": "Group C — candidate lookup signal: person full name. Combine with other group-C signals (nameAny, location, urlDomain) for bounded candidate search. Mutually exclusive with id and slug; may be combined with url for fallback." } }, { "description": "Group C — candidate lookup signal: loose name match (any of given/family/full). Combine with other group-C signals for disambiguation. Mutually exclusive with id and slug; may be combined with url for fallback.", "in": "query", "name": "nameAny", "required": false, "schema": { "type": "string", "description": "Group C — candidate lookup signal: loose name match (any of given/family/full). Combine with other group-C signals for disambiguation. Mutually exclusive with id and slug; may be combined with url for fallback." } }, { "description": "Group C — candidate lookup signal: person location (city, state, country). Combine with other group-C signals for bounded search. Mutually exclusive with id and slug; may be combined with url for fallback.", "in": "query", "name": "location", "required": false, "schema": { "type": "string", "description": "Group C — candidate lookup signal: person location (city, state, country). Combine with other group-C signals for bounded search. Mutually exclusive with id and slug; may be combined with url for fallback." } }, { "description": "Group C — candidate lookup signal: person URL domain (host only, no path). Combine with other group-C signals for disambiguation. Mutually exclusive with id and slug; may be combined with url for fallback.", "in": "query", "name": "urlDomain", "required": false, "schema": { "type": "string", "description": "Group C — candidate lookup signal: person URL domain (host only, no path). Combine with other group-C signals for disambiguation. Mutually exclusive with id and slug; may be combined with url for fallback." } }, { "description": "Projection qualifier — include URL link values in response (default: true). Set false to omit urlLink array.", "in": "query", "name": "includeUrl", "required": false, "schema": { "type": "boolean", "description": "Projection qualifier — include URL link values in response (default: true). Set false to omit urlLink array." } }, { "description": "Projection qualifier — include association values (default: true). Set false to omit association array.", "in": "query", "name": "includeAssociation", "required": false, "schema": { "type": "boolean", "description": "Projection qualifier — include association values (default: true). Set false to omit association array." } }, { "description": "Projection qualifier — include address values (default: true). Set false to omit address array.", "in": "query", "name": "includeAddress", "required": false, "schema": { "type": "boolean", "description": "Projection qualifier — include address values (default: true). Set false to omit address array." } }, { "description": "Projection qualifier — max association values to return; bounded internally to the association limit. Default: 40.", "in": "query", "name": "maxAssociations", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Projection qualifier — max association values to return; bounded internally to the association limit. Default: 40." } }, { "description": "Permit generated monogram photo fallback (default: true). Set false to exclude monogram photos in response.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean", "description": "Permit generated monogram photo fallback (default: true). Set false to exclude monogram photos in response." } }, { "in": "query", "name": "include", "required": false, "schema": { "type": "array", "description": "Projection qualifier — profile panels to embed in this one read (repeat or comma-separate). Each named panel answers the same rows as its own endpoint's first page; omitted panels stay absent.", "items": { "$ref": "#/components/schemas/PersonDetailInclude" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDetail" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Person detail as canonical JSON or compact text.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "301": { "description": "Canonical person URL redirect", "headers": { "Location": { "description": "Redirect target", "style": "simple" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "No person resolved: exact URL and bounded candidate signals are exhausted, which does not prove the record is absent — search before creating. An existing but filtered row instead reports its reason as the ProblemDetail title: Person Exists but Is Not Public (the record exists but is not published)." }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Ambiguous identity: URL ownership or candidate signals require review. ProblemDetail identifies candidate ids and the supported recovery. Verify the candidates against source evidence and read the matching person by personId or an evidenced full profile URL with urlMatchMode=hostPath. score and threshold rank review priority; they do not prove absence. Create only when reviewed candidates are distinct and source evidence supports the target." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Read One Person's Full Detail by aVenture Profile URL, Slug, or URL", "tags": [ "People" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/search": { "post": { "description": "Browse, filter, and search person, people, and individual records in the people domain; returns a paginated people list matching a filter request body. semanticQuery uses the live priority embeddings tier and returns semanticMatch evidence. Without semanticQuery or search, a default-sorted page emits an X-Next-Cursor keyset continuation; send it back as cursor, without sort, to read the next page.", "operationId": "searchPeople", "parameters": [ { "description": "Zero-based page index for offset paging; omit it for the first page. Ignored when cursor is sent: to continue a cursor traversal, send the X-Next-Cursor value as cursor and leave page out.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "When true, return only the page total in the body and skip the content payload.", "in": "query", "name": "countOnly", "required": false, "schema": { "type": "boolean" } }, { "description": "When true, sort people who have a photo before those who do not.", "in": "query", "name": "hasImageFirst", "required": false, "schema": { "type": "boolean" } }, { "description": "When false, monogram fallback logos are stripped from the response. Defaults to true.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Opaque continuation from X-Next-Cursor. Repeat the same filters and size; a semantic cursor also repeats sort, a keyset cursor omits it.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonFilter" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePerson" } } }, "description": "OK", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token, present when another page exists; send it as cursor to read that page. The body's number, first, and totalPages describe offset paging only; they do not advance while you follow cursors. With semanticQuery it continues the semantic window from page 0; otherwise it is a keyset over the default sort.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Search People", "tags": [ "People" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/texts/types": { "get": { "description": "Returns text type values accepted by person text rows.", "operationId": "listPersonTextTypes", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TextTypeOption" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the Accepted Person Text Types", "tags": [ "Texts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}": { "get": { "description": "Returns person detail by exact UUID. Use lookup for a slug, URL, or candidate signals. A signed-in user's read charges one view per distinct returned record against the monthly entity or person view allowance; a repeat read of the same record in the month is free, and an exhausted cap answers 429 with Retry-After.", "operationId": "getPerson", "parameters": [ { "description": "Exact person UUID.", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Projection qualifier — include URL link values in response (default: true). Set false to omit urlLink array.", "in": "query", "name": "includeUrl", "required": false, "schema": { "type": "boolean", "description": "Projection qualifier — include URL link values in response (default: true). Set false to omit urlLink array." } }, { "description": "Projection qualifier — include association values (default: true). Set false to omit association array.", "in": "query", "name": "includeAssociation", "required": false, "schema": { "type": "boolean", "description": "Projection qualifier — include association values (default: true). Set false to omit association array." } }, { "description": "Projection qualifier — include address values (default: true). Set false to omit address array.", "in": "query", "name": "includeAddress", "required": false, "schema": { "type": "boolean", "description": "Projection qualifier — include address values (default: true). Set false to omit address array." } }, { "description": "Projection qualifier — max association values to return; bounded internally to the association limit. Default: 40.", "in": "query", "name": "maxAssociations", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Projection qualifier — max association values to return; bounded internally to the association limit. Default: 40." } }, { "description": "Permit generated monogram photo fallback (default: true). Set false to exclude monogram photos in response.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean", "description": "Permit generated monogram photo fallback (default: true). Set false to exclude monogram photos in response." } }, { "in": "query", "name": "include", "required": false, "schema": { "type": "array", "description": "Projection qualifier — profile panels to embed in this one read (repeat or comma-separate). Each named panel answers the same rows as its own endpoint's first page; omitted panels stay absent.", "items": { "$ref": "#/components/schemas/PersonDetailInclude" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDetail" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Person detail as canonical JSON or compact text.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Person by ID", "tags": [ "People" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/addresses": { "get": { "description": "Returns physical addresses with all role-period associations for one person.", "operationId": "listPersonAddresses", "parameters": [ { "description": "Canonical person UUID", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Person's Addresses", "tags": [ "Person Addresses" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/addresses/{addressJoinId}": { "get": { "description": "Returns the physical address group containing the selected person association.", "operationId": "getPersonAddress", "parameters": [ { "description": "Canonical person UUID", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Integer person-address association id", "in": "path", "name": "addressJoinId", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get One Person's Address", "tags": [ "Person Addresses" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/blog-posts": { "get": { "description": "Returns active external blog post links.", "operationId": "listPersonBlogPosts", "parameters": [ { "description": "Person UUID owning the blog post rows", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "default": [ "publishedAt,desc" ], "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageBlogPost" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Person's Blog Posts", "tags": [ "Research Blog Posts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/blog-posts/{blogPostId}": { "get": { "description": "Returns one person-owned external link by id. Any signed-in user may call this.", "operationId": "getPersonBlogPost", "parameters": [ { "description": "Person UUID owning the blog post row", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Blog post UUID", "in": "path", "name": "blogPostId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPost" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Person Blog Post", "tags": [ "Research Blog Posts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/content": { "get": { "description": "Returns news articles, blog posts, repositories, websites, and pages related to a person. Any signed-in user may call this.", "operationId": "listPersonContent", "parameters": [ { "description": "Person UUID whose publications are listed.", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Topic key or source category.", "in": "query", "name": "topic", "required": false, "schema": { "type": "string", "description": "Topic key or source category." } }, { "description": "Public content type filter.", "in": "query", "name": "contentType", "required": false, "schema": { "$ref": "#/components/schemas/PublicationType" } }, { "description": "Owner relation filter.", "in": "query", "name": "relation", "required": false, "schema": { "$ref": "#/components/schemas/PublicationRelation" } }, { "description": "Best-effort content year filter.", "in": "query", "name": "year", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Best-effort content year filter." } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "Set true for first-page content-existence probes that do not need exact totals or stable ordering.", "in": "query", "name": "existenceProbe", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublication" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List a Person's Publications", "tags": [ "Publications" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/content/facets": { "get": { "description": "Counts one person's content cards by topic and content type across the whole index, so filters show exact totals before every page loads. Any signed-in user may call this.", "operationId": "listPersonContentFacets", "parameters": [ { "description": "Person UUID whose publications are counted.", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicationFacet" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Count a Person's Publications", "tags": [ "Publications" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/content/search": { "post": { "description": "Translates plain-English constraints for one person's content index. Any signed-in user may call this.", "operationId": "searchPersonContent", "parameters": [ { "description": "Person UUID whose publications are searched.", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NaturalSearch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublication" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Search a Person's Publications", "tags": [ "Publications" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/enrichments": { "post": { "description": "Queues a run that researches the addressed person and updates their aVenture profile, owned by the authenticated caller. Take personId from match.owner when POST /v1/lookup or POST /v1/people/lookup returns MATCHED (CLI: lookup, people lookup). To request an update from an indexed news article or web source, pass userPrompt in the body naming the observed detail and source URL (newsUrlOriginal or web URL). When a run for this person is already queued or running, returns that run instead of queuing and charging another; a new run reserves one `person` research unit from the plan's research allowance, spent only once the run saves a research write and returned when it ends without one. After the run completes, read the updated profile with GET /v1/people/{personId} (CLI: people get). Check the run's progress with GET /v1/research-runs/{runId} (CLI: research-runs get).", "operationId": "enrichPerson", "parameters": [ { "description": "Canonical person UUID.", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "COMPREHENSIVE (the default) researches the whole profile; INDIVIDUAL runs only the tasks named in taskPresetKey.", "in": "query", "name": "mode", "required": false, "schema": { "$ref": "#/components/schemas/EnrichmentMode" } }, { "description": "Model id for the run's lead agent; omit to use aVenture's default model.", "in": "query", "name": "model", "required": false, "schema": { "type": "string" } }, { "deprecated": true, "description": "Deprecated: send userPrompt in the JSON body. Used only when the body carries no userPrompt; longer than 2000 characters is refused with 400.", "in": "query", "name": "userPrompt", "required": false, "schema": { "type": "string" } }, { "description": "Research presets that focus the run, listed by GET /v1/research-runs/presets; at least one is required when mode is INDIVIDUAL, and an unknown key is a 400.", "in": "query", "name": "taskPresetKey", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonEnrichmentPrompt" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessRun" } } }, "description": "The queued enrichment run for the addressed person.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Needs a plan that includes research runs; a caller without one gets 402 with code subscription_required (subscription_canceled, subscription_past_due, or subscription_paused when a plan lapsed)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Enrich One Person", "tags": [ "Research Runs" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/entities": { "get": { "description": "Returns entity associations for one person.", "operationId": "listPersonEntityAssociations", "parameters": [ { "description": "Zero-based page index for offset paging; omit it for the first page. Ignored when cursor is sent: to continue a cursor traversal, send the X-Next-Cursor value as cursor and leave page out.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "Person UUID", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Return count metadata without full content", "in": "query", "name": "countOnly", "required": false, "schema": { "type": "boolean" } }, { "description": "Include entity URL records", "in": "query", "name": "includeUrl", "required": false, "schema": { "type": "boolean" } }, { "description": "Include entity address records (pass false to omit)", "in": "query", "name": "includeAddress", "required": false, "schema": { "type": "boolean" } }, { "description": "Permit generated monogram logo fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Opaque URL-safe cursor token from X-Next-Cursor", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityPersonAssociation" } } }, "description": "OK", "headers": { "X-Next-Cursor": { "description": "Opaque continuation token, present when another page exists; send it as cursor to read that page. The body's number, first, and totalPages describe offset paging only; they do not advance while you follow cursors.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Person's Roles at Companies", "tags": [ "Entity Person Associations" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/entities/{associationId}": { "get": { "description": "Returns one person-scoped association join row.", "operationId": "getPersonEntityAssociation", "parameters": [ { "description": "Person UUID", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Association id", "in": "path", "name": "associationId", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "description": "Include entity URL records", "in": "query", "name": "includeUrl", "required": false, "schema": { "type": "boolean" } }, { "description": "Include entity address records (pass false to omit)", "in": "query", "name": "includeAddress", "required": false, "schema": { "type": "boolean" } }, { "description": "Permit generated monogram logo fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityPersonAssociation" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get One of a Person's Roles at a Company", "tags": [ "Entity Person Associations" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/graph": { "get": { "description": "Returns the precomputed person-graph document: career context per associated entity (entity facts, recent news, colleagues, similar entities with key people) and co-investors. Lists are capped and pre-ranked; the response is the display order. Hidden people and entities are excluded at materialization. When no document has been materialized yet, returns empty lists with computedAt=null and schedules an asynchronous recompute.", "operationId": "getPersonGraph", "parameters": [ { "description": "Canonical person UUID", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonGraph" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get Person Graph", "tags": [ "People" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/investments": { "get": { "description": "Returns a paginated investment portfolio for a person with investorAttribution. amountInvested appears only inside investorAttribution, is a plain decimal number in the fundraise transaction currency, and is not added to amount. Valid sort syntax is sort=amountInvested,desc; do not use investorAttribution.amountInvested, amount_invested, currency signs, currency codes, comma grouping, or abbreviated values. joinId (the investor join id) is always the final tiebreak sort key, so rows tied on every requested key keep one order across pages.", "operationId": "listPersonInvestments", "parameters": [ { "description": "Person unique identifier (UUID)", "example": "01993139-fc26-768a-bdf3-c8396c184be7", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Permit monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePersonInvestment" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List a Person's Investments", "tags": [ "Person Investments" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/investor-activity": { "get": { "description": "Gets the investor-perspective activity aggregate (total investments, distinct portfolio companies, current portfolio count, exits, USD-attributed money totals, and top investment stages) for a person investor by personId. personId identifies the individual who supplied the capital — an angel or individual investor, not the company that raised the round.", "operationId": "getPersonInvestorActivity", "parameters": [ { "description": "Person unique identifier (UUID)", "example": "01993139-fc26-768a-bdf3-c8396c184be7", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFundraiseInvestorActivity" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get Person Investor Activity", "tags": [ "Person Investments" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/photo": { "get": { "description": "Returns the person's attached photo with its stored provenance; an empty slot returns 404, so read presence from `core.image.picture` and `core.image.isMonogram` on `people get`.", "operationId": "getPersonPhoto", "parameters": [ { "description": "Canonical person UUID", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUpload" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get Person Photo", "tags": [ "Person Photo" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/repositories": { "get": { "description": "Returns the person's synced GitHub repositories, paged. Default sort is stargazerCount desc, then name.", "operationId": "listPersonRepositories", "parameters": [ { "description": "Person UUID owning the repositories", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageGithubRepo" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List a Person's GitHub Repositories", "tags": [ "Repositories" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/similar": { "get": { "description": "Returns people similar to the person at this address. Rows carry the person shape and per-row similarity provenance; load full detail through the person read endpoint. Results are ordered by similarity score (highest first). This endpoint does not support custom sorting. Any signed-in user may call this on every plan. The list is free: it never counts against the monthly record-view allowance, which charges only a separate full-detail view of one record.", "operationId": "listPersonSimilarPeople", "parameters": [ { "description": "Person unique identifier (UUID)", "example": "04e2bf9c-a100-72ad-83ff-ba69c647b30b", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Permit monogram fallback", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Attribution token identifying the requesting surface; metrics-only", "in": "header", "name": "X-Request-Origin", "required": false, "schema": { "type": "string" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 10, "minimum": 1 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePersonSimilarityResult" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List People Similar to One Person", "tags": [ "Semantic Similarity" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/texts": { "get": { "description": "Returns paginated text rows owned by the person. Inactive rows require read auth.", "operationId": "listPersonTexts", "parameters": [ { "description": "Person UUID owning the text rows", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityText" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Text About a Person", "tags": [ "Texts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/texts/{textId}": { "get": { "description": "Returns one person-owned text row by id. Requires read auth.", "operationId": "getPersonText", "parameters": [ { "description": "Person UUID owning the text row", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Text row id", "in": "path", "name": "textId", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityText" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Piece of Text About a Person", "tags": [ "Texts" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/unique-ids": { "get": { "description": "Returns paginated external identifier mappings for one owner. Sort by id, idType, identifier, createdAt, or updatedAt; default is updatedAt descending.", "operationId": "listPersonUniqueIds", "parameters": [ { "description": "Canonical person UUID.", "example": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageUniqueId" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List a Person's Identifiers", "tags": [ "Identifiers" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/unique-ids/{uniqueIdId}": { "get": { "description": "Returns one external identifier mapping after verifying it belongs to the path owner.", "operationId": "getPersonUniqueId", "parameters": [ { "description": "Canonical person UUID.", "example": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Unique-id row id.", "example": 42, "in": "path", "name": "uniqueIdId", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniqueId" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Person Identifier", "tags": [ "Identifiers" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/urls": { "get": { "description": "Returns paged primary current URL rows owned by a person. Set includeInactive=true as a signed-in user or with read credentials to include secondary active and inactive/historical rows.", "operationId": "listPersonUrls", "parameters": [ { "description": "Person UUID owning the URL rows", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "Include secondary active and inactive/historical URL rows", "in": "query", "name": "includeInactive", "required": false, "schema": { "type": "boolean", "default": false } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityUrlLink" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Person URLs", "tags": [ "URL Links" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/people/{personId}/urls/{urlId}": { "get": { "description": "Returns one person-owned URL row by id. Requires read auth.", "operationId": "getPersonUrl", "parameters": [ { "description": "Person UUID owning the URL row", "in": "path", "name": "personId", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, { "description": "URL link id", "in": "path", "name": "urlId", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityUrlLink" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Person URL", "tags": [ "URL Links" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/research-runs": { "post": { "description": "Files a research request for the company, Product, Service, or person at url and returns the run, owned by you. Send name when known. A url an existing profile owns refreshes that profile; any other url researches a new one, so this is how to add a subject that POST /v1/lookup answers NO_MATCH. To update an existing entity with facts read verbatim from an external source page, pass finding (taskPresetKey defaults to apply-cited-findings); when an observed update comes from an indexed news article (newsArticle or GET /v1/news) or a page not read verbatim, pass userPrompt naming the observed detail and source URL (newsUrlOriginal or web URL). A new run reserves one `company` or `person` research unit, named by the run's researchAllowanceType and spent only once the run saves research and returned when it ends without any. Sending the same url again, with the same mode and presets, while your run for it is queued or running returns that run, uncharged. A record is researched at most once per rolling 24 hours across all callers: a different spelling of a subject already being researched, or of one whose research completed inside that window, files and charges nothing and answers 429 whose detail says when to retry. A url that matches more than one record answers 409, and a spent allowance answers 429. A url that names someone other than the subject (a platform or publisher page, a parked or for-sale host, or an article) answers 422 before anything is filed or charged. You may set only url, name, model, mode, userPrompt, taskPresetKey, and finding; any other field is refused with 403, and a userPrompt longer than 2000 characters is refused with 400. Follow progress with GET /v1/research-runs/{runId}; you are notified when the run completes.", "operationId": "createResearchRun", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessRunCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessRun" } } }, "description": "The filed or reused run.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Needs a plan that includes research runs; a caller without one gets 402 with code subscription_required (subscription_canceled, subscription_past_due, or subscription_paused when a plan lapsed)." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The url is a platform, publisher, parking-host, or article page rather than the subject's own site or LinkedIn profile; nothing is filed or charged, and the problem detail names what to send instead." }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Research a Company or Person by URL", "tags": [ "Research Runs" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/research-runs/presets": { "get": { "description": "Lists the presets you may send as taskPresetKey when you request research. Each preset's key is the value to send, and its name says what the run does. Every listed preset applies the facts you send in finding: the run checks each quote against its page and writes only the facts it confirms.", "operationId": "listResearchRunPresets", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTaskPresetCatalog" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "List Research Presets", "tags": [ "Research Runs" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/research-runs/{runId}": { "get": { "description": "Returns one of your research runs with its status, latest progress, and, once available, the resulting profile and its public URL.", "operationId": "getResearchRun", "parameters": [ { "description": "Research run id", "in": "path", "name": "runId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessRunDetail" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get One Research Run", "tags": [ "Research Runs" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/resolve/{token}": { "get": { "deprecated": true, "description": "Deprecated: use POST /v1/lookup?legacy=true with body {\"name\":\"\"}. Resolve any identifier token to its canonical entity or person. Tries UUID, then the stable public handle, then external registry ids, then the slug (with redirects). Returns 404 when nothing matches and 409 when an external id maps to multiple owners. A name or website URL is not a token; resolve it with the entity or person lookup.", "operationId": "getResolvedHandle", "parameters": [ { "description": "Any identifier: a stable public handle (e.g. eV1StGXR8Z5a), a UUID, an external registry id (ticker, LEI, EIN, ...), or a slug.", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedHandle" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Deprecated: Resolve an Entity or Person by Identifier Token", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/search": { "post": { "description": "Search companies, people, and news. auto blends exact names, full-text, planning, and similarity; keyword forces full-text. Other modes are rejected. Entity results supply ranked people; without entities, people are empty. provenance.modeUsed and scope interpretation report execution; unsearchable scopes carry provenance.rejection. entityFilter constrains entities; single-scope hard filters use /v1/search/natural/entities or /v1/search/natural/people. Page/size apply across scopes except personSize/newsSize; sort is unsupported. layer=synthesis adds a cited answer and relatedQuery. SSE opens with admitted after metering. settled contains all scopes; revised adds pendingWebQuery results and synthesis without moving settled rows; complete is terminal. Snapshot and admitted SSE ids use revision:request-uuid, starting at 0. For ten minutes, identical Last-Event-ID requests from the same caller replay durable state without new quota or records. Failed synthesis retries only its paid answer; disconnects never cancel admitted work. Incomplete snapshots replay as settled, then error. Terminal failures carry ProblemDetail.disposition=TERMINAL; resume ids never restart paid search. JSON with the web layer and a signed-in user waits within the search deadline for discovery, files newly found companies, and returns their queued enrichment runs.", "operationId": "searchFederated", "parameters": [ { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "description": "Repeat to add layers. Synthesis cites this response's public entity records, passages, and news; other layers enrich entities while people and news run alongside.", "in": "query", "name": "layer", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SearchLayer" }, "uniqueItems": true } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedNaturalSearch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedSearch" } } }, "description": "Ranked matches across every federated record type.", "headers": { "X-Aventure-Search-Cache-Mode": { "description": "Cache policy this search ran under: use, bypass, or refresh. A caller without private-data access always runs use, whatever cacheMode it sent.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "This search needs a paid aVenture plan; a caller without one gets 402 with code subscription_required." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Search Companies, People, and News Together", "tags": [ "Search" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/search/link": { "get": { "description": "Fetches the page at the supplied URL, identifies the single company, product, or person the page is primarily about, and returns the federated entity, person, and news results for that name together with the synthesized query itself. A page whose content cannot be read returns 404; a fetch or inference failure returns a problem (503 only when a retry can succeed), never an empty result. For direct URL-to-record identity resolution use the entities lookup operation with the url instead. Send `Prefer: respond-async` to skip the live wait: the search is committed as a link search job and the read answers 202 with a Location status URL and Retry-After; poll it. A repeat of a search that completed in the last few minutes answers 200 from its stored result. A failed job commit answers 503; a caller already holding the maximum active link searches gets 429.", "operationId": "searchLink", "parameters": [ { "description": "Public article or page URL to search from", "example": "https://example.com/article", "in": "query", "name": "url", "required": true, "schema": { "type": "string" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "description": "Send respond-async to request a pollable link search job.", "in": "header", "name": "Prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkSearch" } } }, "description": "Records reachable from the submitted link.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnqueue" } } }, "description": "Only with `Prefer: respond-async`; poll Location after Retry-After.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "This search needs a paid aVenture plan; a caller without one gets 402 with code subscription_required." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Search From a Page URL", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/search/link/jobs/{jobId}": { "get": { "description": "Returns the result of a link search accepted with `Prefer: respond-async`. Answers 202 with Location and Retry-After while the job is pending or running, 200 with the search once it completes, the synchronous read's 404 or 422 when the page or URL was refused, and 503 when the job failed transiently; resubmit the search to retry. Runs and their stored results do not expire; an unknown job id returns 404.", "operationId": "getLinkSearchJob", "parameters": [ { "description": "Link search job UUID", "in": "path", "name": "jobId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkSearch" } } }, "description": "Records reachable from the submitted link.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnqueue" } } }, "description": "Job still running; poll Location after Retry-After.", "headers": { "Cache-Control": { "description": "Always no-store: the state changes under the same URL", "schema": { "type": "string" }, "style": "simple" }, "Location": { "description": "This status URL; poll it again", "schema": { "type": "string", "format": "uri-reference" }, "style": "simple" }, "Retry-After": { "description": "Seconds to wait before polling again", "schema": { "type": "integer" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "This search needs a paid aVenture plan; a caller without one gets 402 with code subscription_required." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a Link Search Job", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/search/natural/entities": { "post": { "description": "Translate a plain-English company, startup, investor, investment firm, or investment manager search into the canonical EntityFilter contract, execute the existing entity list engine, and return both the interpretation and ranked entity list page. Unsupported constraints are named in the interpretation instead of being silently ignored. A description or company discovery question belongs here; explicit filter fields are hard constraints: they override planner values, while the planner fills fields left unset. Example: search.query 'AI infrastructure companies founded since 2020' with size=3. The query accepts plain English; size limits the page, page starts at 0, and filter.yearFoundedRange [{\"min\":2020}] imposes a hard founding-year constraint.", "operationId": "searchNaturalEntities", "parameters": [ { "description": "When false, generated monogram logos are stripped from entity rows.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Optional answer layers to add beside the entity records; repeat to add more. `passage` ranks public research snippets and linked news that answer the question; `synthesis` adds a cited written answer and implies `passage`; `judgment` ranks a competitor, market, or provider question's answer by judged probability; `web` adds web evidence and the companies it names, and implies `judgment`.", "in": "query", "name": "layer", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SearchLayer" }, "uniqueItems": true } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNaturalSearch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NaturalSearchResult" } } }, "description": "Ranked entity matches for the interpreted query.", "headers": { "X-Aventure-Search-Cache-Mode": { "description": "Cache policy this search ran under: use, bypass, or refresh. A caller without private-data access always runs use, whatever cacheMode it sent.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "This search needs a paid aVenture plan; a caller without one gets 402 with code subscription_required." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Find Companies, Startups, and Investors in Natural Language", "tags": [ "Natural Search" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/search/natural/people": { "post": { "description": "Translate a plain-English people search into the canonical PersonFilter contract, execute the existing people list engine, and return both the interpretation and ranked people page. Broad role, employer, work-history, and profile requests use person semantic search. Explicit filter fields are hard constraints: they override planner values, while the planner fills fields left unset.", "operationId": "searchNaturalPeople", "parameters": [ { "description": "When false, generated monogram pictures are stripped from person rows.", "in": "query", "name": "permitMonogram", "required": false, "schema": { "type": "boolean" } }, { "description": "Zero-based page index (0..N)", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonNaturalSearch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonNaturalSearchResult" } } }, "description": "Ranked person matches for the interpreted query.", "headers": { "X-Aventure-Search-Cache-Mode": { "description": "Cache policy this search ran under: use, bypass, or refresh. A caller without private-data access always runs use, whatever cacheMode it sent.", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "This search needs a paid aVenture plan; a caller without one gets 402 with code subscription_required." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Find People With Natural Language", "tags": [ "Natural Search" ], "x-aventure-tool": { "auth": "read" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/search/shared": { "get": { "description": "Returns publication metadata in UUID order with a bounded keyset cursor. Answer bodies and a total count are omitted to keep sitemap traversal independent of the total number or size of saved answers. Page must be zero; follow nextCursor.", "operationId": "listSharedSearch", "parameters": [ { "description": "Offset paging is not supported; omit page. Any value other than 0 returns 400. Send the previous response's nextCursor as cursor to read the next page.", "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "description": "The size of the page to be returned", "in": "query", "name": "size", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 1 } }, { "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "in": "query", "name": "sort", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "The previous page's nextCursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorSliceSharedSearchList" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List Shared Search Publications", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } }, "post": { "description": "Runs the query against public records and saves its answer under the supplied UUID. Reusing the UUID with the same query returns the original answer; a different query is rejected. The saved answer survives query-cache expiry and is readable without authentication. No result supplied by a caller is accepted.", "operationId": "createSharedSearch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedSearchMutation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedSearch" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Share a Search Answer", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/search/shared/slug/{slug}": { "get": { "description": "Resolves the saved query slug used by the public search page.", "operationId": "getSharedSearchBySlug", "parameters": [ { "description": "Shared search slug.", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedSearch" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Read a Shared Search by Slug", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/search/shared/{id}": { "get": { "description": "Returns the persisted public answer without running the query again.", "operationId": "getSharedSearch", "parameters": [ { "description": "Shared search UUID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedSearch" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Read a Shared Search Answer", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/status": { "get": { "description": "Confirms the API is reachable; needs no credential.", "operationId": "getSystemStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemStatus" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "Get System Status", "tags": [ "System" ], "x-aventure-tool": { "auth": "none" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/unique-ids/lookup": { "get": { "description": "Resolves an external identifier to its owner(s). idType accepts a canonical token or alias; the value is normalized per type before matching. Returns every owner that carries the identifier (a value can recur across owners, e.g. a reused ticker), each row carrying its entityId or personId.", "operationId": "lookupUniqueId", "parameters": [ { "description": "Identifier type token or alias, for example ein.", "example": "ein", "in": "query", "name": "idType", "required": true, "schema": { "type": "string" } }, { "description": "Identifier value to resolve.", "example": "12-3456789", "in": "query", "name": "identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UniqueId" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Look Up an Identifier Owner", "tags": [ "Identifiers" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/unique-ids/types": { "get": { "description": "Lists the recognized external identifier types (ein, secCik, ticker, lei, duns, isin, cusip, crd, orcid) with each type's label, accepted aliases, owner scope (entity and/or person), and the format pattern a value must match on write.", "operationId": "listUniqueIdTypes", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UniqueIdTypeAlias" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List the Accepted Unique Identifier Types", "tags": [ "Identifiers" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/url-types": { "get": { "description": "Read-only inventory: returns the canonical URL types and aliases accepted by entity and person URL rows. One catalog serves both owners; it writes nothing.", "operationId": "listUrlTypes", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UrlTypeAlias" } } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "summary": "List URL Types", "tags": [ "URL Links" ], "x-aventure-tool": { "auth": "none" }, "x-aventure-visibility": { "scope": "public" } } }, "/v1/web/search": { "post": { "description": "Runs a live web search and returns its results, or a stored result when the same query was searched recently. Use it for external facts a stored record lacks, such as a publication or release date, press coverage, or an app-store listing. Each successful search uses one web search from the signed-in account's monthly allowance. Past it, a subscriber with additional usage on pays 2.5 cents per search; otherwise the call answers 429 with a usage-limit message and upgrade links. A query naming too few distinct words (a bare brand, or a brand plus a number) is refused with 422 before any charge; name what you are looking for and a disambiguator such as the domain. Set `provider` to EXA for Exa's instant search or EXA_DEEP for its slower, broader deep search; both answer synchronously. When the default search is still running after aVenture's live wait, the call answers 503 with Retry-After; send `Prefer: respond-async` to receive 202 with a Location status URL instead, and poll it after Retry-After. Neither charges an allowance search.", "operationId": "searchWeb", "parameters": [ { "description": "Replay key for this account's exact search request, up to 255 characters", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "(?U)(?!\\s*$)[^\\p{Cc}]+" } }, { "description": "Send respond-async to receive a pollable job when a live web search is still running; an Exa provider answers live.", "in": "header", "name": "Prefer", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Search" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearch" } } }, "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Conflict", "x-aventure-standard-response": true }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unsupported Media Type", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Search the Live Web", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } }, "/v1/web/searches/jobs/{jobId}": { "get": { "description": "Reads the web-search job a `Prefer: respond-async` search accepted. Answers 200 with the finished search (charged like a search), 202 with Retry-After while the search is queued or running, 503 search_provider_error when the job ended without a result (run the search again), and 404 for an unknown job. Never starts or resubmits a provider search.", "operationId": "getWebSearchJob", "parameters": [ { "description": "Web-search job UUID from the 202 response", "in": "path", "name": "jobId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearch" } } }, "description": "Finished web search; never cached by intermediaries", "headers": { "Cache-Control": { "description": "Always no-store: a metered per-caller read", "schema": { "type": "string" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnqueue" } } }, "description": "The search is queued or running; poll again after Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait before polling again", "schema": { "type": "integer" }, "style": "simple" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Bad Request", "x-aventure-standard-response": true }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unauthorized", "x-aventure-standard-response": true }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Forbidden", "x-aventure-standard-response": true }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Found", "x-aventure-standard-response": true }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Not Acceptable", "x-aventure-standard-response": true }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content", "x-aventure-standard-response": true }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "x-aventure-standard-response": true }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Internal Server Error", "x-aventure-standard-response": true }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-aventure-standard-response": true } }, "security": [ { "bearerAuth": [] } ], "summary": "Get an Async Web Search Job", "tags": [ "Search" ], "x-aventure-visibility": { "scope": "public" } } } }, "components": { "schemas": { "SystemBuild": { "type": "object", "description": "Build metadata exposed by the public info alias", "properties": { "build": { "$ref": "#/components/schemas/SystemBuildDetail", "description": "Application build metadata" } }, "required": [ "build" ] }, "ProblemDetail": { "type": "object", "description": "RFC 9457 problem response with aVenture extensions.", "properties": { "allowanceType": { "description": "Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.", "oneOf": [ { "$ref": "#/components/schemas/ResearchAllowanceType" }, { "type": "null" } ] }, "circuitBreaker": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.", "maxLength": 128, "x-enum-descriptions": [ "Caller is authenticated but lacks the required role for this operation. Agent action: surface the requiredRole field on the ProblemDetail and stop; do not retry without role escalation.", "Request was throttled. Agent action: wait at least retryAfterSeconds (also in the Retry-After header), then increase the delay exponentially on repeated 429s. When resetAt is present, wait until that time instead of retrying the exhausted monthly allowance.", "Request was throttled. Agent action: wait at least retryAfterSeconds (also in the Retry-After header), then increase the delay exponentially on repeated 429s. When resetAt is present, wait until that time instead of retrying the exhausted monthly allowance.", "Caller is authenticated but the subscription on their account does not include this operation. Agent action: surface ProblemDetail.detail explaining the subscription requirement and stop. The identical request cannot succeed until the account changes plan, so never retry it.", "Caller's subscription was canceled or its first payment expired unpaid, so it no longer includes this operation. Agent action: surface ProblemDetail.detail and stop; the account must subscribe again through the resolution's Checkout endpoint before the identical request can succeed.", "Caller's subscription has a failed or unfinished payment, so it does not include this operation until the payment succeeds. Agent action: surface ProblemDetail.detail and stop; the account must update its payment method through the resolution's Billing Portal endpoint.", "Caller's subscription is paused, so it does not include this operation. Agent action: surface ProblemDetail.detail and stop; the account must add a payment method through the resolution's Billing Portal endpoint, then resume with PATCH /v1/billing/subscription and paused false.", "The caller's metered allowance for this operation is spent for the current period. Agent action: stop and report ProblemDetail.allowanceType, limit, used, remaining, and resetAt; resetAt is when the meter refills and is typically weeks away. Do not retry inside the period even though the status is 429.", "The caller's monthly allowance is spent and the next additional-usage unit would pass the monthly spend cap or the prepaid credit left. Agent action: stop and report ProblemDetail.allowanceType, limit, used, remaining, and resetAt; raise the cap or buy credit through /v1/billing/additional-usage, or wait for resetAt.", "The prepaid credit Checkout is paid, expired, or closed. Retire this purchase intent before explicitly starting another Checkout; ambiguous transport failures and in-progress conflicts must keep the original key.", "A signed-out purchase named an email that already belongs to an account. Agent action: sign that account in with its email code, then subscribe signed in; never retry the signed-out purchase for that email.", "Detail-origin cold-miss coalescing is saturated. Agent action: treat as backend capacity impairment, back off, and inspect backend pool/bulkhead metrics; this is not a caller throttle.", "Detail-origin cold-miss scheduler rejected work because this instance is shutting down for a redeploy. Agent action: retry shortly; the platform routes the retry to a healthy instance. This is deploy-window noise, not a capacity defect — do not treat it as backend saturation.", "A read overran its database query budget and was shed before it could answer, so nothing was read and the identical request can be replayed. Agent action: retry after a short backoff; this service records the shed WARN-only without an incident, so a consumer that reports it files the only incident for an expected condition.", "Request prose looks shell-mangled around a money phrase: either shell expansion stripped a leading dollar sign ('50 million' where '$50 million' was meant) or an escape character survived into the text ('\\$50 million', standalone '/$50 million'). Agent action: write '$' literally and re-send the JSON body from a file or stdin, or quote it so the shell does not expand '$'; use allowSuspectedShellStrip only when the value is intentional.", "Request prose looks shell-mangled around a money phrase: either shell expansion stripped a leading dollar sign ('50 million' where '$50 million' was meant) or an escape character survived into the text ('\\$50 million', standalone '/$50 million'). Agent action: write '$' literally and re-send the JSON body from a file or stdin, or quote it so the shell does not expand '$'; use allowSuspectedShellStrip only when the value is intentional.", "Entity text or a research snippet was rejected by its prose judge or text contract. Agent action: rewrite every passage in ProblemDetail.proseViolation at once and resend the whole text; ProblemDetail.hint names the override only when every violation is overridable.", "Every source-grounding slot is held by other text writes, so this write was refused before it judged or wrote anything. Agent action: replay the identical request after retryAfterSeconds (also in the Retry-After header).", "A URL was submitted to the wrong write surface. Agent action: move the URL to the specific surface named by ProblemDetail.hint/resolution, for example EntityUrl.urlType=ycombinator via entities urls create instead of News.newsUrlOriginal.", "JobRunr background worker is disabled in this environment. Agent action: stop (this is an admin/ops configuration condition, not a retriable user error).", "JobRunr background worker is disabled in this environment. Agent action: stop (this is an admin/ops configuration condition, not a retriable user error).", "A catalog task step runs an operation this API instance does not serve, so its plan cannot be projected: rollout skew, or an instance whose configuration disables that operation. Agent action: retry after the rollout; on a deployed instance that persists, report it as rollout skew.", "JobRunr backing storage (Postgres) is unavailable. Agent action: stop; retrying will not help until DB connectivity is restored.", "JobRunr backing storage (Postgres) is unavailable. Agent action: stop; retrying will not help until DB connectivity is restored.", "RBAC role lookup failed (app_user read did not return). Agent action: retry once; persistent failure indicates a database outage.", "Geocoding provider (Google Maps Platform) call failed. Agent action: surface the error; address fields can be submitted without normalization as a fallback.", "Geocoding provider (Google Maps Platform) call failed. Agent action: surface the error; address fields can be submitted without normalization as a fallback.", "Image upload matched a blocklist entry (visually similar to a known bad asset). Agent action: do not retry the same image; supply a different image or stop.", "Image upload was blank or a flat monochrome canvas. Agent action: supply a source image with visible logo or photo detail; retrying the same bytes will not pass.", "Image upload failed minimum dimension/file-size check. Agent action: supply a higher-resolution source image; retrying the same one will not pass.", "Image upload's visible content is a wide banner/wordmark when a square logo or photo was required. Agent action: supply a square (or near-square) source image — a favicon, app icon, square logo, or cropped headshot — not a horizontal wordmark or og:image banner; retrying the same bytes will not pass.", "Image upload was classified as a monogram (single letter / generated initial) when a real photograph or logo was required. Agent action: supply a non-monogram image or set permitMonogram=true on the read endpoint if a monogram is acceptable for the use case.", "Image upload could not be decoded (corrupt file, unsupported format). Agent action: supply a valid PNG/JPEG/WebP; retrying the same bytes will not pass.", "Image processing pipeline (resize/encode/hash) threw an unexpected error. Agent action: retry once; persistent failure indicates an infra issue.", "Logo/photo upload was rejected because the server-side brand-match vision check found it does not depict the target's own brand (a generic favicon, a parent/provider/acquirer mark, an OpenGraph/banner/social card, or an unrelated image). Agent action: supply the target entity's OWN brand mark and re-run; retrying the same image, or any generic/og/banner/parent asset, will not pass.", "Image upload was a photograph or scene image rather than a standalone logo/mark graphic (a homepage hero, product photo, ad, or screenshot carrying an embedded wordmark). Agent action: supply the entity's standalone mark — a favicon, app icon, wordmark, or lockup — not page imagery; retrying the same bytes will not pass.", "An outbound fetch from an external target site (robots.txt, sitemap, page, or logo or thumbnail image) failed after retries or with the breaker open. Agent action: the failure belongs to the target; crawl jobs may fall back to rendered extraction; do not retry immediately.", "A request that must not wait found another request already fetching its source document. Agent action: retry after retryAfterSeconds (also in the Retry-After header); the existing fetch keeps running and this request did not start another.", "A crawl-run request named an entity or person that has no current primary website URL. Agent action: add or activate the owner's website URL, then resubmit; retrying the unchanged request cannot succeed.", "RSS news-ingest feed fetch failed after retries or with the breaker open. Agent action: inspect the configured feed URL and upstream status; do not retry the enqueue immediately.", "RSS news-ingest article page fetch failed after retries or with the breaker open. Agent action: inspect the source article URL and upstream status; the ingest job may skip that article.", "News subscription webhook verification could not connect to delivery.url. Agent action: confirm the endpoint is publicly reachable over https, then subscribe again.", "News subscription webhook verification timed out. Agent action: make the endpoint answer the challenge within the delivery read timeout, then subscribe again.", "News subscription webhook verification failed the TLS handshake. Agent action: serve a publicly trusted certificate for the delivery.url host, then subscribe again.", "News subscription webhook verification got a 4xx answer. Agent action: make the endpoint accept the signed verification POST, then subscribe again.", "News subscription webhook verification got a 5xx answer. Agent action: fix or wait for the endpoint, then subscribe again.", "News subscription webhook verification got a 2xx answer whose body was not {\"challenge\":\"\"} with the sent nonce. Agent action: echo the challenge exactly, then subscribe again.", "Caller already holds the maximum number of news subscriptions. Agent action: unsubscribe one before subscribing again.", "Cloudflare R2 object fetch failed during a read operation. Agent action: retry once with backoff; persistent failure indicates R2 outage or asset deletion.", "Cloudflare R2 object delete failed during a cleanup operation. Agent action: surface; retrying may produce duplicate-delete errors.", "Cloudflare R2 object upload failed during a write operation. Agent action: retry once with the same payload; persistent failure indicates R2 outage.", "Stored source-document raw bytes could not be served: the row's inline-or-R2 raw authority is incomplete or failed digest verification. Agent action: surface; the stored authority needs operator reconciliation before this body can be read.", "A source-document capture stopped before retaining a provider response over this service's configured byte limit. Agent action: this is a designed containment boundary, not a provider outage or a service defect; do not retry the same request expecting a different outcome.", "News similarity cannot run because the target embedding is unavailable or live similarity capacity is full. Agent action: surface the 503 and retry later; this endpoint does not fall back to lexical ranking.", "The web search provider is not configured for this environment. Agent action: stop; admin/ops must configure the provider key before this endpoint will succeed.", "Search provider call failed. Agent action: inspect detail and source. Provider credential or credit refusals (401, 402, or 407) are terminal: restore the provider credential or credits before retrying. Other transient provider outages may be retried according to Retry-After.", "aVenture stopped waiting for a web search the provider is still running; the search keeps running and its finished result is stored. Agent action: retry the same request, after retryAfterSeconds when present (also in the Retry-After header); this is not a provider failure.", "A lookup sent with Prefer: respond-async was accepted as a lookup job instead of answered in the request. Agent action: poll the Location status URL after Retry-After.", "SEC EDGAR lookup failed (ticker catalog or company submissions). Agent action: surface; SEC outages or rate limiting affect the public-company preview endpoint only.", "GitHub repository fetch failed (account, listing, or single repo). Agent action: surface; GitHub outages or rate limiting affect github-repo sync endpoints only.", "LLM inference provider call failed. Agent action: retry once with backoff; persistent failure indicates provider outage or invalid profile config.", "LLM inference provider call failed. Agent action: retry once with backoff; persistent failure indicates provider outage or invalid profile config.", "LLM inference provider returned an empty response body. Agent action: retry once; persistent empty responses indicate prompt or provider misconfiguration.", "LLM inference provider returned an empty response body. Agent action: retry once; persistent empty responses indicate prompt or provider misconfiguration.", "LLM inference provider returned a response that failed JSON parsing. Agent action: surface; the prompt or response schema may need adjustment.", "LLM inference provider returned a response that failed JSON parsing. Agent action: surface; the prompt or response schema may need adjustment.", "Inference profile catalog is missing or empty. Agent action: stop; admin/ops must configure inference profiles before this endpoint will succeed.", "Inference profile catalog is missing or empty. Agent action: stop; admin/ops must configure inference profiles before this endpoint will succeed.", "Inference profile is configured but its API key is missing from secret storage. Agent action: stop; admin/ops must populate the API key in secret storage.", "Inference profile is configured but its API key is missing from secret storage. Agent action: stop; admin/ops must populate the API key in secret storage." ], "x-extensible-enum": [ "not_authorized", "rateLimited", "rate_limited", "subscription_required", "subscription_canceled", "subscription_past_due", "subscription_paused", "billing_allowance_exhausted", "billing_additional_usage_cap_reached", "billing_credit_checkout_closed", "account_exists", "origin_detail_capacity", "origin_detail_shutdown", "query_deadline_shed", "suspectedShellStrip", "suspected_shell_strip", "prose_rejected", "source_grounding_at_capacity", "url_surface_misclassification", "JOBRUNR_DISABLED", "jobrunr_disabled", "task_plan_operation_unserved", "JOBRUNR_STORAGE_UNAVAILABLE", "jobrunr_storage_unavailable", "rbac_lookup_unavailable", "GEOCODE_PROVIDER_ERROR", "geocode_provider_error", "image_blocklist_match", "image_monochrome", "image_too_small", "image_wrong_aspect", "image_monogram", "image_unreadable", "image_processing_error", "image_brand_mismatch", "image_photographic", "web_crawl_fetch_failed", "source_document_fetch_busy", "primary_website_missing", "news_rss_feed_fetch_failed", "news_rss_article_fetch_failed", "callback_connection_refused", "callback_timeout", "callback_tls_error", "callback_http_4xx", "callback_http_5xx", "callback_challenge_failed", "news_subscription_limit", "r2_fetch_failed", "r2_delete_failed", "r2_upload_failed", "source_document_body_unavailable", "source_document_capture_limit_exceeded", "news_similarity_embedding_unavailable", "search_provider_not_configured", "search_provider_error", "search_still_running", "lookup_still_running", "sec_edgar_fetch_failed", "github_fetch_failed", "INFERENCE_PROVIDER_ERROR", "inference_provider_error", "INFERENCE_PROVIDER_RESPONSE_EMPTY", "inference_provider_response_empty", "INFERENCE_PROVIDER_INVALID_JSON", "inference_provider_invalid_json", "INFERENCE_PROFILES_MISSING", "inference_profiles_missing", "INFERENCE_PROFILE_API_KEY_MISSING", "inference_profile_api_key_missing" ] }, "conflictingRecord": { "oneOf": [ { "$ref": "#/components/schemas/CurrentSlugOwner" }, { "type": "null" } ] }, "detail": { "type": "string" }, "details": { "description": "Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.", "oneOf": [ { "$ref": "#/components/schemas/DomainConflictDetails" }, { "type": "null" } ] }, "disposition": { "type": [ "string", "null" ], "description": "Whether a service-unavailable failure can be retried.", "enum": [ "TRANSIENT", "TERMINAL" ] }, "error": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "existingRecordId": { "type": [ "string", "null" ], "description": "On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record." }, "existingRedirect": { "oneOf": [ { "$ref": "#/components/schemas/RedirectSlugPath" }, { "type": "null" } ] }, "feId": { "type": [ "string", "null" ] }, "field": { "type": [ "string", "null" ] }, "filedRunId": { "type": [ "array", "null" ], "description": "Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.", "items": { "type": "string", "format": "uuid" } }, "hammingDistance": { "type": [ "integer", "null" ], "format": "int64" }, "hint": { "type": [ "string", "null" ] }, "instance": { "type": "string", "format": "uri" }, "limit": { "type": [ "integer", "null" ], "format": "int64", "description": "Cap the limitType meter allows for its current period." }, "limitType": { "type": [ "string", "null" ], "description": "Which meter refused the request; names what limit/used/remaining count.", "x-enum-descriptions": [ "Too many form submissions from this client; retry after retryAfterSeconds.", "The service-wide request rate is exhausted; retry after retryAfterSeconds.", "Too many requests from this client's network; retry after retryAfterSeconds.", "Too many requests from this client's address; retry after retryAfterSeconds.", "A request-rate limit refused the request; retry after retryAfterSeconds.", "Too many live web searches; retry after retryAfterSeconds.", "Too many help questions; retry after retryAfterSeconds.", "Too many natural-language searches; retry after retryAfterSeconds.", "The plan's monthly research allowance is used up. It refills at resetAt, often weeks away: stop rather than retry.", "The additional-usage spend cap or prepaid credit is used up, counted in cents: stop rather than retry until the cap is raised or credit is added." ], "x-extensible-enum": [ "FORM", "GLOBAL", "SUBNET", "IP", "UNKNOWN", "WEB_SEARCH", "AGENT_HELP", "NATURAL_SEARCH", "BILLING_ALLOWANCE", "BILLING_ADDITIONAL_USAGE" ] }, "matchedBlocklistKey": { "type": [ "string", "null" ] }, "mediaType": { "type": [ "string", "null" ] }, "moderationReason": { "type": [ "string", "null" ] }, "parseError": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] }, "properties": { "type": "object", "additionalProperties": {} }, "proseViolation": { "type": [ "array", "null" ], "description": "Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.", "items": { "$ref": "#/components/schemas/ProseViolation" } }, "remaining": { "type": [ "integer", "null" ], "format": "int64", "description": "Cap minus used for the limitType meter, never negative." }, "requiredRole": { "type": [ "string", "null" ] }, "resetAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the limitType meter refills and the request can succeed again." }, "resolution": { "oneOf": [ { "$ref": "#/components/schemas/ProblemResolution" }, { "type": "null" } ] }, "retryAfterSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff." }, "spanId": { "type": [ "string", "null" ] }, "status": { "type": "integer", "format": "int32" }, "suggestion": { "type": [ "string", "null" ] }, "suggestions": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "suspectedFragment": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "traceId": { "type": [ "string", "null" ] }, "type": { "type": "string", "format": "uri", "anyOf": [ { "type": "string", "format": "uri" }, { "$ref": "#/components/schemas/ProblemType" } ] }, "unknownParameters": { "type": [ "array", "null" ], "items": { "type": "string" } }, "used": { "type": [ "integer", "null" ], "format": "int64", "description": "Requests already charged against the limitType meter this period." }, "validParameters": { "type": [ "array", "null" ], "items": { "type": "string" } }, "value": { "type": [ "string", "null" ] }, "windowSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Length of a rolling throttle window; absent for period meters." } } }, "CursorSliceAddressLink": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/AddressLink" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "content" ] }, "AgentHelpQuestion": { "type": "object", "description": "A plain-English question about how to use aVenture, answered with references to the operations that do it.", "properties": { "model": { "type": [ "string", "null" ], "description": "Optional supported model for the answer. Omit it to use the default; an unsupported model answers 422." }, "question": { "type": "string", "description": "The question to answer, in natural language.", "example": "how do I attach a product URL?", "minLength": 1 }, "resolve": { "type": "boolean", "description": "True recommends the operation or workflow that does what the question asks, or asks a clarifying question, instead of writing an answer. It ignores model and has its own per-account limit." }, "scope": { "description": "Optional scope restricting which operations the answer may recommend; null means all.", "oneOf": [ { "$ref": "#/components/schemas/HelpScope" }, { "type": "null" } ] } }, "required": [ "question" ] }, "AgentHelp": { "type": "object", "description": "Help answer with citations to the operations it draws on. Unsupported questions abstain (LOW confidence) rather than guess.", "properties": { "answer": { "type": "string", "description": "Answer drawn only from the cited corpus; abstains when unsupported." }, "citation": { "type": "array", "description": "Corpus evidence backing the answer; empty when the model abstains.", "items": { "$ref": "#/components/schemas/HelpCitation" } }, "confidence": { "$ref": "#/components/schemas/Confidence", "description": "Confidence the answer is fully supported by the cited corpus. LOW signals an abstention." }, "resolution": { "description": "The task or operation resolution when the question asked to resolve; absent for a generated answer.", "oneOf": [ { "$ref": "#/components/schemas/HelpResolution" }, { "type": "null" } ] } }, "required": [ "answer", "citation", "confidence" ], "x-aventure-noun": { "one": "help answer", "other": "help answers" } }, "ApiKey": { "type": "object", "description": "API key metadata; never contains the key secret", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "Provider creation timestamp" }, "description": { "type": [ "string", "null" ], "description": "Optional user-visible key description" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Provider expiry timestamp" }, "id": { "type": "string", "description": "API key identifier", "pattern": "^ak_[0-9A-Fa-f]{32}$" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Most recent provider-recorded use timestamp" }, "name": { "type": "string", "description": "User-visible key name" }, "revocationReason": { "type": [ "string", "null" ], "description": "Provider revocation explanation" }, "scopes": { "type": "array", "description": "Scopes assigned to this key", "items": { "type": "string" } }, "status": { "type": "string", "description": "Provider-derived current lifecycle state", "enum": [ "ACTIVE", "REVOKED", "EXPIRED" ] }, "subject": { "type": "string", "description": "Account that owns the key" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Provider metadata update timestamp" } }, "required": [ "createdAt", "id", "name", "scopes", "status", "subject", "updatedAt" ] }, "CliAuthorizationMutation": { "type": "object", "description": "Creates a short-lived CLI authorization request bound to an ephemeral key", "properties": { "clientLabel": { "type": [ "string", "null" ], "description": "Label for this CLI installation", "example": "William's MacBook", "maxLength": 120, "minLength": 1, "pattern": ".*\\S.*" }, "clientPlatform": { "description": "Coarse operating-system family", "oneOf": [ { "$ref": "#/components/schemas/CliAuthorizationClientPlatform" }, { "type": "null" } ] }, "encryptionAlgorithm": { "description": "Requested hybrid encryption suite", "oneOf": [ { "$ref": "#/components/schemas/CliAuthorizationEncryptionAlgorithm" }, { "type": "null" } ] }, "encryptionPublicKey": { "type": [ "string", "null" ], "description": "Base64-encoded DER SubjectPublicKeyInfo for an ephemeral RSA public key", "maxLength": 12000, "minLength": 344 } } }, "CliAuthorizationStart": { "type": "object", "description": "New CLI authorization handle and one-time poll credential", "properties": { "comparisonCode": { "type": "string", "description": "Human comparison code shown by both the CLI and browser" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Authorization request expiry timestamp" }, "id": { "type": "string", "format": "uuid", "description": "Public authorization request identifier" }, "intervalSeconds": { "type": "integer", "format": "int64", "description": "Minimum poll interval in seconds", "minimum": 1 }, "pollSecret": { "type": "string", "description": "One-time high-entropy credential required to poll and acknowledge delivery", "readOnly": true }, "verificationUrl": { "type": "string", "format": "uri", "description": "Browser verification URL" } }, "required": [ "comparisonCode", "expiresAt", "id", "intervalSeconds", "pollSecret", "verificationUrl" ] }, "CliAuthorization": { "type": "object", "description": "Browser-approved CLI authorization metadata. Secret poll and encrypted-delivery material are exposed only by their dedicated one-time response contracts.", "properties": { "approvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the authenticated user approved this request" }, "clientLabel": { "type": "string", "description": "User-supplied label for the requesting CLI installation" }, "clientPlatform": { "$ref": "#/components/schemas/CliAuthorizationClientPlatform", "description": "Coarse client operating-system family" }, "comparisonCode": { "type": "string", "description": "Human comparison code shown by both the CLI and browser" }, "consumedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the CLI acknowledged durable local storage" }, "createdAt": { "type": "string", "format": "date-time", "description": "Authorization request creation timestamp" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Time after which an unfinished request cannot be approved" }, "id": { "type": "string", "format": "uuid", "description": "Public authorization request identifier" }, "intervalSeconds": { "type": "integer", "format": "int64", "description": "Minimum server-directed poll interval in seconds", "minimum": 1 }, "keyReadyAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time encrypted key delivery became available" }, "status": { "$ref": "#/components/schemas/CliAuthorizationStatus", "description": "Current broker lifecycle state" }, "terminalAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time this request entered its terminal state" }, "terminalReason": { "description": "Non-secret terminal-state explanation", "oneOf": [ { "$ref": "#/components/schemas/CliAuthorizationTerminalReason" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "Most recent lifecycle update timestamp" } }, "required": [ "clientLabel", "clientPlatform", "comparisonCode", "createdAt", "expiresAt", "id", "intervalSeconds", "status", "updatedAt" ] }, "CliAuthorizationPoll": { "type": "object", "description": "Current broker state and encrypted delivery when the key is ready", "properties": { "delivery": { "description": "Encrypted one-time delivery, present only for KEY_READY", "oneOf": [ { "$ref": "#/components/schemas/CliAuthorizationDelivery" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "Authorization request expiry timestamp" }, "status": { "$ref": "#/components/schemas/CliAuthorizationStatus", "description": "Current broker lifecycle state" }, "terminalReason": { "description": "Non-secret terminal-state explanation", "oneOf": [ { "$ref": "#/components/schemas/CliAuthorizationTerminalReason" }, { "type": "null" } ] } }, "required": [ "expiresAt", "status" ] }, "AuthPermissionGrant": { "type": "object", "description": "Auth permission grant", "properties": { "permission": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "role": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } }, "required": [ "permission", "role" ] }, "AuthOperationFilter": { "type": "object", "description": "Bounded generated API operations to authorize for the current session.", "properties": { "operation": { "type": "array", "description": "Generated API operation candidates to authorize.", "items": { "$ref": "#/components/schemas/AuthOperation" }, "maxItems": 1000, "minItems": 0 } }, "required": [ "operation" ] }, "AuthOperationAuthorization": { "type": "object", "description": "Current permission grant, access class, and supplied API operations admitted by the live request authorization policy.", "properties": { "operation": { "type": "array", "description": "Supplied operations admitted by the current session.", "items": { "$ref": "#/components/schemas/AuthOperation" } }, "operationAccess": { "$ref": "#/components/schemas/AuthOperationAccess", "description": "Highest access class represented by the current session." }, "permissionGrant": { "$ref": "#/components/schemas/AuthPermissionGrant", "description": "Existing role and permission grant for the current session." } }, "required": [ "operation", "operationAccess", "permissionGrant" ] }, "AuthProviderCatalog": { "type": "object", "properties": { "clerkPublishableKey": { "type": [ "string", "null" ], "description": "Publishable key for browser sign-in; absent when browser sign-in is unavailable", "example": "pk_test_cmVmaW5lZC13aWxkY2F0LTMuY2xlcmsuYWNjb3VudHMuZGV2JA" }, "oauthClient": { "description": "OAuth PKCE client configuration for the CLI; absent until its client configuration is complete", "oneOf": [ { "$ref": "#/components/schemas/AuthClient" }, { "type": "null" } ] } } }, "BillingAdditionalUsageMutation": { "type": "object", "description": "Merge patch of the additional-usage settings. Enabling requires funding; USAGE_INVOICE also requires spendCapCents and invoiceIncrementCents.", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Turn recording of usage past the monthly caps on or off." }, "funding": { "oneOf": [ { "$ref": "#/components/schemas/BillingAdditionalUsageFundingType" }, { "type": "null" } ] }, "invoiceIncrementCents": { "type": [ "integer", "null" ], "format": "int64", "description": "Unbilled cents that trigger a USAGE_INVOICE invoice; one of the plan catalog's invoiceIncrementCents." }, "spendCapCents": { "type": [ "integer", "null" ], "format": "int64", "description": "Monthly spend cap in cents; required for USAGE_INVOICE." } } }, "BillingAdditionalUsage": { "type": "object", "description": "Opt-in metered usage past the monthly allowance: settings, spend this UTC month, prepaid credit, and unbilled usage.", "properties": { "availableCreditCents": { "type": "number", "description": "Spendable prepaid credit after pending usage and invoice-line rounding reserves, in cents." }, "blocked": { "type": "boolean", "description": "True while a failed threshold invoice blocks additional usage; paying it in Billing Portal clears the block." }, "enabled": { "type": "boolean", "description": "Whether usage past the monthly caps is recorded and billed." }, "funding": { "oneOf": [ { "$ref": "#/components/schemas/BillingAdditionalUsageFundingType" }, { "type": "null" } ] }, "invoiceIncrementCents": { "type": [ "integer", "null" ], "format": "int64", "description": "USAGE_INVOICE bills an invoice once unbilled usage reaches this many cents; the invoice can exceed it by the usage recorded while it was being created." }, "meter": { "type": "array", "items": { "$ref": "#/components/schemas/BillingAdditionalUsageMeter" } }, "resetAt": { "type": "string", "format": "date-time", "description": "When spentCents returns to zero: the next UTC month." }, "spendCapCents": { "type": [ "integer", "null" ], "format": "int64", "description": "Monthly spend cap in cents. Required for USAGE_INVOICE; absent for PREPAID_CREDIT means only the prepaid credit bounds usage." }, "spentCents": { "type": "number", "description": "Additional usage priced this UTC month, in cents." }, "unbilledCents": { "type": "number", "description": "Priced usage not yet paid by credit or placed on an invoice, in cents; the next threshold or period invoice bills it." } }, "required": [ "availableCreditCents", "blocked", "enabled", "meter", "resetAt", "spentCents", "unbilledCents" ] }, "ResearchAllowance": { "type": "object", "description": "Usage allowance for one meter in one billing period, the UTC month by default", "properties": { "access": { "description": "What filing one more research run on this meter does now, decided exactly as filing decides it; present only on the company and person research meters", "oneOf": [ { "$ref": "#/components/schemas/ResearchAccessType" }, { "type": "null" } ] }, "limit": { "type": [ "integer", "null" ], "format": "int32", "description": "Cap for the period; absent when the tier meters without a cap" }, "remaining": { "type": [ "integer", "null" ], "format": "int32", "description": "Cap minus used, never negative; absent when there is no cap" }, "resetAt": { "type": "string", "format": "date-time", "description": "When used returns to zero and the next period starts" }, "used": { "type": "integer", "format": "int32", "description": "Amount used so far in the period" } }, "required": [ "resetAt", "used" ], "x-aventure-noun": { "one": "usage allowance", "other": "usage allowances" } }, "BillingCheckoutMutation": { "type": "object", "description": "Caller-selected plan and Checkout presentation for server-owned Checkout creation.", "properties": { "plan": { "$ref": "#/components/schemas/BillingPlanType", "description": "AI Plus or AI Pro plan to start through Checkout" }, "uiMode": { "$ref": "#/components/schemas/BillingCheckoutUiMode", "description": "How the caller presents Checkout; HOSTED_PAGE when omitted" } }, "required": [ "plan" ] }, "BillingCheckout": { "type": "object", "description": "Checkout Session destination or client secret and expiry without provider identifiers.", "properties": { "clientSecret": { "type": [ "string", "null" ], "description": "Checkout Session client secret for Stripe.js initCheckout; set for ELEMENTS" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the Checkout Session stops accepting payment" }, "plan": { "$ref": "#/components/schemas/BillingPlanType" }, "publishableKey": { "type": [ "string", "null" ], "description": "Stripe publishable key that loads Stripe.js; set for ELEMENTS" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Hosted Checkout page to open in a browser; set for HOSTED_PAGE" } }, "required": [ "expiresAt", "plan" ] }, "BillingCreditPurchaseMutation": { "type": "object", "description": "Prepaid credit pack to buy through hosted Checkout.", "properties": { "pack": { "$ref": "#/components/schemas/BillingCreditPackType", "description": "Credit pack to buy; its amount becomes prepaid credit." } }, "required": [ "pack" ] }, "BillingCreditPurchase": { "type": "object", "description": "Hosted Checkout destination and expiry for a prepaid credit pack.", "properties": { "expiresAt": { "type": "string", "format": "date-time" }, "id": { "type": [ "string", "null" ], "format": "uuid" }, "pack": { "$ref": "#/components/schemas/BillingCreditPackType" }, "url": { "type": "string", "format": "uri" } }, "required": [ "expiresAt", "pack", "url" ] }, "BillingCreditPurchaseConfirmation": { "type": "object", "description": "One account-owned purchase's confirmed credit grant or checkout closure.", "properties": { "amountCents": { "type": "integer", "format": "int64" }, "closedAt": { "type": [ "string", "null" ], "format": "date-time" }, "grantedAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "amountCents", "id" ] }, "BillingPlanChangeMutation": { "type": "object", "description": "Caller-selected plan for changing a continuing AI Plus or AI Pro subscription.", "properties": { "plan": { "$ref": "#/components/schemas/BillingPlanType", "description": "AI Plus or AI Pro plan to move to; the current plan cancels a scheduled change" }, "prorationDate": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix epoch-second timestamp from an upgrade preview that pins its prorated amount on confirmation; omit it when no upgrade preview applies" } }, "required": [ "plan" ] }, "BillingPlanChangePreview": { "type": "object", "description": "Preview of POST /v1/billing/plan-changes for the same plan: the amount charged on confirmation, when the plan takes effect, the renewal price after it, and the card that pays.", "properties": { "amountDue": { "type": "integer", "format": "int64", "description": "Amount charged on confirmation in the currency's minor unit, after credit for unused time; 0 when the change waits for the period end" }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" }, "effectiveAt": { "type": "string", "format": "date-time", "description": "When the plan would take effect: now, or the current period end" }, "paymentMethod": { "description": "Card Stripe charges; absent when no card is on file", "oneOf": [ { "$ref": "#/components/schemas/BillingPaymentMethod" }, { "type": "null" } ] }, "prorationDate": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix epoch-second timestamp to send on upgrade confirmation so Stripe charges this previewed proration; absent when the change does not prorate now" }, "recurringPrice": { "$ref": "#/components/schemas/BillingRecurringPrice", "description": "Recurring charge after the change" } }, "required": [ "amountDue", "currency", "effectiveAt", "recurringPrice" ] }, "BillingPlanChange": { "type": "object", "description": "Plan change outcome: an upgrade applies now with a prorated invoice, a downgrade waits for the current period end.", "properties": { "effectiveAt": { "type": "string", "format": "date-time", "description": "When the plan takes effect: now, or the current period end" }, "paymentClientSecret": { "type": [ "string", "null" ], "description": "PaymentIntent client secret of the same pending invoice, for Stripe.js to complete authentication or payment in the page; set exactly when paymentUrl is." }, "paymentUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Hosted invoice to pay when the upgrade's prorated charge needs the customer; the upgrade applies only after it is paid. Absent when no payment is pending." }, "plan": { "$ref": "#/components/schemas/BillingPlanType", "description": "Plan the subscription moves to" }, "publishableKey": { "type": [ "string", "null" ], "description": "Stripe publishable key for Stripe.js; set with paymentClientSecret" } }, "required": [ "effectiveAt", "plan" ] }, "BillingCatalog": { "type": "object", "description": "Every self-serve subscription tier with its monthly allowance caps, every plan Checkout sells, and the prices of usage past those caps. The Unlimited tier is not sold through Checkout and is omitted.", "properties": { "additionalUsage": { "type": "array", "items": { "$ref": "#/components/schemas/BillingCatalogAdditionalUsage" } }, "creditPack": { "type": "array", "items": { "$ref": "#/components/schemas/BillingCatalogCreditPack" } }, "invoiceIncrementCents": { "type": "array", "description": "Invoice increments a USAGE_INVOICE subscriber may choose, in cents.", "items": { "type": "integer", "format": "int64" } }, "plan": { "type": "array", "items": { "$ref": "#/components/schemas/BillingCatalogPlan" } }, "tier": { "type": "array", "items": { "$ref": "#/components/schemas/BillingCatalogTier" } } }, "required": [ "additionalUsage", "creditPack", "invoiceIncrementCents", "plan", "tier" ] }, "BillingPortalMutation": { "type": "object", "description": "Where the hosted Billing Portal session opens.", "properties": { "flow": { "type": [ "string", "null" ], "description": "PAYMENT_METHOD_UPDATE opens straight to adding or replacing the card and returns to subscription settings when done. Omit to open the portal home. Plan changes use POST /v1/billing/plan-changes and cancellation uses PATCH /v1/billing/subscription.", "enum": [ "PAYMENT_METHOD_UPDATE" ] } } }, "BillingPortal": { "type": "object", "description": "Hosted Billing Portal destination without provider identifiers.", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] }, "BillingSubscription": { "type": "object", "description": "Current plan (Essential, AI Plus, AI Pro, or Unlimited), subscription status, and monthly usage.", "properties": { "additionalUsage": { "$ref": "#/components/schemas/BillingAdditionalUsage" }, "allowance": { "$ref": "#/components/schemas/ResearchAllowanceUsage", "description": "Used, cap, and reset time of each monthly allowance" }, "cancelAtPeriodEnd": { "type": "boolean", "description": "True when the plan is cancelled and ends at periodEnd" }, "creditPurchasable": { "type": "boolean", "description": "True when POST /v1/billing/credit-purchases sells this account a prepaid credit pack; false for an operator, a plan the App Store bills, an Unlimited plan, or a continuing paid plan that is not entitled (INCOMPLETE, PAST_DUE, UNPAID, or PAUSED)" }, "entitled": { "type": "boolean", "description": "True while the subscription grants its paid tier" }, "originalStart": { "type": [ "string", "null" ], "format": "date-time", "description": "Original start of the continuing paid subscription; absent when the provider did not supply it" }, "pendingPlan": { "description": "Plan a scheduled change moves the subscription to at pendingPlanAt; absent when nothing is scheduled", "oneOf": [ { "$ref": "#/components/schemas/BillingPlanType" }, { "type": "null" } ] }, "pendingPlanAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When pendingPlan takes effect; absent when nothing is scheduled" }, "periodEnd": { "type": [ "string", "null" ], "format": "date-time", "description": "When the plan renews, or when access ends if cancelAtPeriodEnd" }, "periodStart": { "type": [ "string", "null" ], "format": "date-time", "description": "Start of the current billing period" }, "plan": { "description": "Paid plan and billing cycle; absent without a paid subscription", "oneOf": [ { "$ref": "#/components/schemas/BillingPlanType" }, { "type": "null" } ] }, "provider": { "type": [ "string", "null" ], "description": "Who bills the continuing paid subscription, including one past due or paused: STRIPE (managed on the web) or APP_STORE; absent without one", "enum": [ "STRIPE", "APP_STORE" ] }, "recurringPrice": { "description": "Subscribed renewal price before discounts; absent without a known paid Price", "oneOf": [ { "$ref": "#/components/schemas/BillingRecurringPrice" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "NONE", "INCOMPLETE", "INCOMPLETE_EXPIRED", "TRIALING", "ACTIVE", "PAST_DUE", "CANCELED", "UNPAID", "PAUSED" ] }, "tier": { "type": "string", "description": "Tier whose monthly allowances apply now", "enum": [ "ESSENTIAL", "PLUS", "PRO", "UNLIMITED" ] } }, "required": [ "additionalUsage", "allowance", "cancelAtPeriodEnd", "creditPurchasable", "entitled", "status", "tier" ], "x-aventure-noun": { "one": "subscription", "other": "subscriptions" } }, "BillingSubscriptionMutation": { "type": "object", "description": "Merge patch of a continuing AI Plus or AI Pro subscription: cancel it at the period end or resume it, including one Stripe paused.", "properties": { "cancelAtPeriodEnd": { "type": [ "boolean", "null" ], "description": "true ends the subscription at the current period end and drops a scheduled plan change; false resumes it and restores the plan change scheduled before the cancellation. Omit to change nothing." }, "paused": { "type": [ "boolean", "null" ], "description": "false resumes a subscription Stripe paused because its trial ended without a payment method; add one with POST /v1/billing/portal-sessions first. The resumption starts a new billing period now and charges the plan to that card; a declined or authentication-held charge answers 409. true, or cancelAtPeriodEnd in the same request, is refused. Omit to change nothing." } } }, "BillingNextCharge": { "type": "object", "description": "Next invoice of the caller's renewing Stripe subscription as Stripe previews it, after discounts and credits.", "properties": { "amountDue": { "type": "integer", "format": "int64", "description": "Amount the next invoice will charge in the currency's minor unit, after discounts, credits, and usage so far; 0 when a discount covers it" }, "chargeAt": { "type": "string", "format": "date-time", "description": "When the next invoice is raised and charged" }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" }, "discount": { "type": "array", "description": "Discounts applied to the next invoice; empty when none apply", "items": { "$ref": "#/components/schemas/BillingDiscount" } }, "totalExcludingTax": { "type": "integer", "format": "int64", "description": "Next invoice total in the currency's minor unit after discounts, before tax and account credit; compare it, not amountDue, with the plan's price" } }, "required": [ "amountDue", "chargeAt", "currency", "discount", "totalExcludingTax" ] }, "BillingPaymentProfile": { "type": "object", "description": "The caller's card on file and whether Checkout would charge each plan's introductoryAmount on the first payment, read live from Stripe.", "properties": { "introductoryOfferEligible": { "type": "boolean", "description": "True when the catalog offers introductoryAmount, the App Store does not bill the account, and it has no earlier subscription, payment, or unvoided invoice; false otherwise" }, "paymentMethod": { "description": "Card that pays the continuing Stripe subscription; absent without one or when it is paid by something other than a card", "oneOf": [ { "$ref": "#/components/schemas/BillingPaymentMethod" }, { "type": "null" } ] } }, "required": [ "introductoryOfferEligible" ] }, "CursorSliceSharedDirectoryList": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/SharedDirectoryList" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "content" ] }, "SharedDirectoryMutation": { "type": "object", "description": "Publish a directory view under a stable client UUID; retries and identical views return the same publication.", "properties": { "directory": { "description": "Directory page the view filters.", "oneOf": [ { "$ref": "#/components/schemas/SharedDirectoryType" }, { "type": "null" } ] }, "entityFilter": { "description": "Body the companies or investors page sends to entity search.", "oneOf": [ { "$ref": "#/components/schemas/EntityListFilter" }, { "type": "null" } ] }, "id": { "type": [ "string", "null" ], "format": "uuid", "description": "Stable sharing UUID generated once and reused across retries." }, "personFilter": { "description": "Body the people page sends to person search.", "oneOf": [ { "$ref": "#/components/schemas/PersonFilter" }, { "type": "null" } ] }, "sort": { "type": [ "string", "null" ], "description": "Sort the page sends, as property,asc or property,desc.", "maxLength": 100, "minLength": 0 } } }, "SharedDirectory": { "type": "object", "description": "A saved public directory view and its page copy.", "properties": { "description": { "type": "string", "description": "Search-result description, at most 155 characters." }, "entityFilter": { "description": "Entity filter of a companies or investors view.", "oneOf": [ { "$ref": "#/components/schemas/EntityListFilter" }, { "type": "null" } ] }, "personFilter": { "description": "Person filter of a people view.", "oneOf": [ { "$ref": "#/components/schemas/PersonFilter" }, { "type": "null" } ] }, "publication": { "$ref": "#/components/schemas/SharedDirectoryList" }, "sort": { "type": [ "string", "null" ], "description": "Sort as property,direction; absent uses the directory default." }, "title": { "type": "string", "description": "Search-result title, at most 60 characters." } }, "required": [ "description", "publication", "title" ], "x-aventure-noun": { "one": "shared directory view", "other": "shared directory views" } }, "EnrichmentBatch": { "type": "object", "description": "Existing records to enrich in one call, with the run options every run shares", "properties": { "entityId": { "type": "array", "description": "Canonical entity UUIDs to enrich, filed in order before any person", "items": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, "mode": { "$ref": "#/components/schemas/EnrichmentMode", "description": "COMPREHENSIVE (the default) researches each whole profile; INDIVIDUAL runs only the tasks named in taskPresetKey" }, "model": { "type": [ "string", "null" ], "description": "Model id for each run's lead agent; omit to use aVenture's default model" }, "personId": { "type": "array", "description": "Canonical person UUIDs to enrich, filed in order after every entity", "items": { "type": "string", "format": "uuid", "description": "Canonical person UUID" } }, "taskPresetKey": { "type": [ "array", "null" ], "description": "Task preset keys that scope or emphasize every run; at least one is required when mode is INDIVIDUAL, and an unknown key is a 400", "items": { "type": "string" } }, "userPrompt": { "type": [ "string", "null" ], "description": "Plain-language instruction for every run, such as which facts or sources to check first", "maxLength": 2000, "minLength": 0 } } }, "Enrichment": { "type": "object", "description": "One requested record's batch enrichment outcome: the filed run or the refusal", "properties": { "record": { "$ref": "#/components/schemas/EntityPersonOwner", "description": "The requested entity or person" }, "refusal": { "description": "Why no run was filed; absent when run is set", "oneOf": [ { "$ref": "#/components/schemas/EnrichmentRefusalType" }, { "type": "null" } ] }, "run": { "description": "The queued or reused run; absent when refusal is set", "oneOf": [ { "$ref": "#/components/schemas/HarnessRun" }, { "type": "null" } ] } }, "required": [ "record" ] }, "EntityType": { "type": "string", "description": "Canonical entity classification for the organization, product, and service records stored in the entity domain.", "enum": [ "Company", "Investment Firm", "Fund", "Nonprofit", "Government", "Organization", "Business Line", "Product", "Service" ], "x-aventure-noun": { "one": "entity type", "other": "entity types" }, "x-aventure-parsed-enum": true }, "IntRange": { "type": "object", "description": "Integer range for count-based filter criteria", "properties": { "max": { "type": [ "integer", "null" ], "format": "int32", "description": "Inclusive maximum integer." }, "min": { "type": [ "integer", "null" ], "format": "int32", "description": "Inclusive minimum integer." } } }, "EntityOperatingStatus": { "type": "string", "description": "Operating state accepted by entity filters and mutation endpoints. Acquired Subsidiary means the entity was acquired and still operates; Closed (Acquihire) means the entity was acquired for its team and is terminal, rendering like Closed everywhere; Acquired means the entity is terminal, folded into the buyer, or closed.", "enum": [ "Operating", "Acquired", "Acquired Subsidiary", "Closed", "Closed (Acquihire)", "Inactive" ], "x-aventure-parsed-enum": true }, "EntityListQualityGate": { "type": "string", "description": "Named quality gates for entity list endpoints.", "enum": [ "NONE", "COMPANY_LISTING_READY" ], "x-aventure-parsed-enum": true }, "EntityUrlType": { "type": "string", "description": "Canonical URL platform type such as website, linkedin, twitter, or github. Lifecycle facts belong on link flags such as isCurrent and isPrimary." }, "UrlMatchMode": { "type": "string", "description": "URL matching mode for URL-backed filters and duplicate checks.", "enum": [ "hostPath", "domain" ], "x-aventure-parsed-enum": true }, "DecimalRange": { "type": "object", "description": "Decimal range for monetary and numeric filter criteria", "properties": { "max": { "type": [ "number", "null" ], "description": "Inclusive maximum decimal number, such as 220000 or 123456.78." }, "min": { "type": [ "number", "null" ], "description": "Inclusive minimum decimal number, such as 220000 or 123456.78." } } }, "PageEntityList": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/EntityList" } }, "empty": { "type": "boolean" }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "number": { "type": "integer", "format": "int32" }, "numberOfElements": { "type": "integer", "format": "int32" }, "pageable": { "$ref": "#/components/schemas/PageableObject" }, "size": { "type": "integer", "format": "int32" }, "sort": { "$ref": "#/components/schemas/SortObject" }, "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer", "format": "int32" } } }, "EntityBrand": { "type": "object", "description": "Thin company brand read: names and logos under core, current website and social URLs, and current classification tags.", "properties": { "classification": { "$ref": "#/components/schemas/EntityClassification", "description": "Current classification tags, industries, and standardized classifications." }, "core": { "$ref": "#/components/schemas/Entity", "description": "Core identity: id, slug, nameBrand, nameLegal, nameAlias, type, status, and image (logo, logoSquare, isMonogram)." }, "publicUrl": { "type": [ "string", "null" ], "description": "Absolute canonical aVenture page URL, when the entity has one." }, "urlLink": { "type": "array", "description": "Current URL links: websites first, the primary one leading, then social and other profiles.", "items": { "$ref": "#/components/schemas/EntityUrlLink" } } }, "required": [ "classification", "core", "urlLink" ], "x-aventure-noun": { "one": "brand profile", "other": "brand profiles" } }, "ClassificationCatalog": { "type": "object", "description": "Full active entity classification taxonomy in one payload. Inactive tags are omitted.", "properties": { "bucket": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationCatalogBucket" } }, "category": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationCatalogCategory" } }, "generatedAt": { "type": "string", "format": "date-time" }, "totalBucket": { "type": "integer", "format": "int32" }, "totalCategory": { "type": "integer", "format": "int32" }, "totalStandardizedClassification": { "type": "integer", "format": "int32" }, "totalTag": { "type": "integer", "format": "int32" } }, "required": [ "bucket", "category", "generatedAt", "totalBucket", "totalCategory", "totalStandardizedClassification", "totalTag" ], "x-aventure-noun": { "one": "classification catalog", "other": "classification catalogs" } }, "PageClassification": { "type": "object", "properties": { "content": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/EntityTag" }, { "$ref": "#/components/schemas/StandardizedClassification" } ] } }, "empty": { "type": "boolean" }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "number": { "type": "integer", "format": "int32" }, "numberOfElements": { "type": "integer", "format": "int32" }, "pageable": { "$ref": "#/components/schemas/PageableObject" }, "size": { "type": "integer", "format": "int32" }, "sort": { "$ref": "#/components/schemas/SortObject" }, "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer", "format": "int32" } } }, "EntityTypeGroup": { "type": "string", "description": "Canonical entity type groups for boundary-level scope selection.", "enum": [ "Organization", "Investor" ] }, "EntityFilterOptionSet": { "type": "object", "description": "Available filter options for list endpoints", "properties": { "arrayFilterEntry": { "type": "array", "description": "Array filter entries", "items": { "$ref": "#/components/schemas/EntityFilterEntry" } }, "filtersMeta": { "description": "Metadata for the generated filter option set", "oneOf": [ { "$ref": "#/components/schemas/EntityFilterOptionSetMeta" }, { "type": "null" } ] }, "rangeFilterEntry": { "type": "array", "description": "Range filter entries", "items": { "$ref": "#/components/schemas/EntityFilterEntry" } } }, "required": [ "arrayFilterEntry", "rangeFilterEntry" ], "x-aventure-noun": { "one": "filter set", "other": "filter sets" } }, "EntityFilter": { "type": "object", "additionalProperties": false, "description": "Entity list and search filters. GET flattens these fields as query parameters; POST accepts the same shape as JSON.", "properties": { "acceleratorBrand": { "type": "array", "description": "Accelerator brand or operator name.", "items": { "type": "string" } }, "acceleratorCohort": { "type": "array", "description": "Accelerator batch or cohort label.", "items": { "type": "string" } }, "acceleratorName": { "type": "array", "description": "Specific accelerator program name.", "items": { "type": "string" } }, "acceleratorStatus": { "type": "array", "description": "Accelerator participation status.", "items": { "type": "string" } }, "affinity": { "type": "array", "description": "Affinity provider organization names accepted by the companies list filter. Affinity rows are member -> provider; use provider names here, not member names.", "items": { "type": "string" } }, "closedLast": { "type": "boolean", "description": "Rank closed entities (Closed, Closed (Acquihire), Inactive) after every other textSearch or semanticQuery match, ahead of relevance and sort; omitted means true. false ranks them by relevance alone. Filter them out with operatingStatus or suppressNonOperating." }, "employeeCountRange": { "type": "array", "description": "Inclusive reported employee-count ranges, in employees.", "items": { "$ref": "#/components/schemas/IntRange" } }, "entityId": { "type": "array", "description": "Restrict results to specific entity IDs.", "items": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, "entityName": { "type": "array", "description": "Exact normalized match against entity brand, legal, or alias names.", "items": { "type": "string" } }, "featured": { "type": [ "boolean", "null" ], "description": "Filter by featured status." }, "fundraiseActivity": { "$ref": "#/components/schemas/EntityFundraiseFilterCriteria", "description": "Fundraise activity" }, "hasFundraising": { "type": [ "boolean", "null" ], "description": "Filter to entities with fundraise activity." }, "headquartersCity": { "type": "array", "description": "Headquarters city values.", "items": { "type": "string" } }, "headquartersCountry": { "type": "array", "description": "Headquarters country values.", "items": { "type": "string" } }, "headquartersState": { "type": "array", "description": "Headquarters state or region values.", "items": { "type": "string" } }, "industry": { "type": "array", "description": "Industry classification values.", "items": { "type": "string" } }, "letter": { "type": [ "string", "null" ], "description": "First letter of the display name." }, "location": { "type": "array", "description": "Geographic classification values.", "items": { "type": "string" } }, "logoOption": { "$ref": "#/components/schemas/EntityFilterLogoOption", "description": "Logo sort priority." }, "mainProduct": { "type": "array", "description": "Main product classification values.", "items": { "type": "string" } }, "operatingStatus": { "type": "array", "description": "Operating states to include; omit to include every state.", "items": { "$ref": "#/components/schemas/EntityOperatingStatus" } }, "originCountry": { "type": "array", "description": "Countries an entity is from: its headquarters country or the country of its current origin (founding) address, never a legal seat alone. What a nationality adjective (Colombian startups) means; headquartersCountry is only where it is based now.", "items": { "type": "string" } }, "person": { "type": "array", "description": "Associated person, matched by name.", "items": { "type": "string" } }, "portfolioHeadquartersCity": { "type": "array", "description": "Portfolio-company headquarters city values.", "items": { "type": "string" } }, "portfolioHeadquartersCountry": { "type": "array", "description": "Portfolio-company headquarters country values.", "items": { "type": "string" } }, "portfolioHeadquartersState": { "type": "array", "description": "Portfolio-company headquarters state or region values.", "items": { "type": "string" } }, "qualityGate": { "$ref": "#/components/schemas/EntityListQualityGate", "description": "Server-owned list quality gate." }, "rankByProminence": { "type": [ "boolean", "null" ], "description": "Rank most prominent first (funding, stage, headcount, momentum, recent news, investor breadth), ahead of sort: what best, top, or most promising mean." }, "slug": { "type": "array", "description": "Restrict results to entity slugs.", "items": { "type": "string", "description": "Canonical lowercase URL slug for the resource", "example": "aventure-vc", "maxLength": 255, "pattern": "^[a-z0-9_-]+$" } }, "stage": { "type": "array", "description": "Investment stage classification values.", "items": { "type": "string" } }, "suppressLateStage": { "type": [ "boolean", "null" ], "description": "Exclude public and acquired companies (including acquired subsidiaries); what startup means. Private companies at any round stay, as do companies without a recorded stage or operating status." }, "suppressNonOperating": { "type": [ "boolean", "null" ], "description": "Suppress entities with terminal operating status." }, "suppressZeroTotalRaised": { "type": [ "boolean", "null" ], "description": "Suppress entities with zero or unknown USD total raised." }, "tag": { "type": "array", "description": "General classification tag values.", "items": { "type": "string" } }, "textSearch": { "type": [ "string", "null" ], "description": "Non-blank keyword/full-text search term. Use natural-search for plain-English or multi-constraint company requests." }, "typeCustomer": { "type": "array", "description": "Customer-type classification values.", "items": { "type": "string" } }, "typeModel": { "type": "array", "description": "Business-model classification values.", "items": { "type": "string" } }, "typeOwnership": { "type": "array", "description": "Ownership-model classification values.", "items": { "type": "string" } }, "typeRecord": { "type": "array", "description": "Entity type filter. Organization expands to Company, Investment Firm, Nonprofit, Government, and Business Line; omit to include every entity type.", "items": { "$ref": "#/components/schemas/EntityType" } }, "typeRevenue": { "type": "array", "description": "Revenue-model classification values.", "items": { "type": "string" } }, "typeTechnologyUsed": { "type": "array", "description": "Technology-used classification values.", "items": { "type": "string" } }, "url": { "type": [ "string", "null" ], "description": "Current URL to match by normalized host and path." }, "urlDomain": { "type": [ "string", "null" ], "description": "Current root domain to match when urlMatchMode=domain.", "example": "example.com" }, "urlMatchMode": { "description": "URL matching mode: hostPath uses host and path; domain uses the root domain. Omitted, it is domain when urlDomain is set, else hostPath.", "example": "domain", "oneOf": [ { "$ref": "#/components/schemas/UrlMatchMode" }, { "type": "null" } ] }, "urlType": { "description": "Restrict URL matching to one URL type.", "example": "website", "oneOf": [ { "$ref": "#/components/schemas/EntityUrlType" }, { "type": "null" } ] }, "yearFoundedRange": { "type": "array", "description": "Inclusive founding-year ranges, in calendar years.", "items": { "$ref": "#/components/schemas/IntRange" } } } }, "EntityFilterRefinedFilters": { "type": "object", "description": "Refined filters", "properties": { "filter": { "type": "array", "description": "Canonical filter entries for the active entity scope.", "items": { "$ref": "#/components/schemas/EntityFilterEntry" } }, "meta": { "$ref": "#/components/schemas/RefinementMeta", "description": "Pagination and degradation state for this refinement." } }, "required": [ "filter", "meta" ], "x-aventure-noun": { "one": "refined filter set", "other": "refined filter sets" } }, "EntityFilterSearch": { "type": "object", "additionalProperties": false, "description": "Record representing a filter search request", "properties": { "filterKey": { "type": "string", "description": "Filter key", "minLength": 1 }, "limit": { "type": "integer", "format": "int32", "default": 20, "description": "Maximum number of search results; omit for 20, or the filter's own limit when that is smaller. A larger value returns the filter's limit.", "minimum": 1 }, "query": { "type": "string", "description": "Query", "minLength": 1 }, "scopeFilter": { "$ref": "#/components/schemas/EntityFilter", "description": "Entity filter scope applied to the option search. Omit to search every eligible entity." } }, "required": [ "filterKey", "query" ] }, "EntityFilterSearchResult": { "type": "object", "description": "Typeahead search result pairing a filter key with matching option values", "properties": { "filterKey": { "type": "string", "description": "Canonical filter key searched" }, "result": { "type": "array", "description": "Matching option values", "items": { "type": "string" } } }, "required": [ "filterKey", "result" ], "x-aventure-noun": { "one": "filter search", "other": "filter searches" } }, "IdentificationSubject": { "type": "object", "description": "The company, Product, Service, or person to identify. Send the name, a URL it owns, or both, plus every location and source you have; a website or profile URL usually settles the answer without any model call.", "properties": { "context": { "type": [ "string", "null" ], "description": "Specific facts in plain words: product, industry, employer and title, or founder names. Generic words like startup add nothing.", "example": "Online payments company", "maxLength": 2000, "minLength": 0 }, "kind": { "type": [ "string", "null" ], "description": "Kind of record to identify when you know it: ENTITY for companies, funds, and firms (and their products or services); PERSON for people. Only that kind is looked up; typeRecord or providerId implies ENTITY.", "enum": [ "ENTITY", "PERSON" ] }, "location": { "type": [ "string", "null" ], "description": "City, region, or country, such as Austin, TX. Tells namesakes apart; not proof on its own.", "example": "San Francisco, CA", "maxLength": 2000, "minLength": 0 }, "name": { "type": [ "string", "null" ], "description": "Name exactly as the source writes it, such as Acme AI or Jane Doe. Send name, url, or both; a name that is an absolute http(s) URL is read as url.", "example": "Stripe", "maxLength": 200, "minLength": 0 }, "providerId": { "type": [ "string", "null" ], "format": "uuid", "description": "Provider entity id for a Product or Service lookup. Omit it when the provider is unknown. With no typeRecord, searches both Product and Service. Invalid for a company type or a person lookup." }, "sourceIdentifier": { "description": "Internal permanent Folk source identity. Requires private visibility and resolves before names or URLs.", "oneOf": [ { "$ref": "#/components/schemas/UniqueIdMutation" }, { "type": "null" } ], "writeOnly": true }, "sourceNewsId": { "type": [ "integer", "null" ], "format": "int32", "description": "aVenture news id of the article that mentions the subject; an unknown id is a 400.", "example": 123456 }, "sourceUrl": { "type": [ "string", "null" ], "description": "URL of the article that mentions the subject; read from aVenture news when stored there, otherwise fetched.", "example": "https://techcrunch.com/2024/01/01/example", "maxLength": 2000, "minLength": 0 }, "typeRecord": { "description": "Entity type to identify. A Product or Service never matches its provider organization, but a record stored under a neighboring type of the same family (Product or Service; Fund, Investment Firm, or Company) still matches, and a Business Line lookup sees both families. Invalid for a person lookup.", "oneOf": [ { "$ref": "#/components/schemas/EntityType" }, { "type": "null" } ] }, "url": { "type": "array", "description": "URLs the subject owns: its website, its LinkedIn company or person profile, an aVenture page, or a registry page. At most 10. Required when name is omitted. Put articles in sourceUrl.", "example": [ "https://stripe.com" ], "items": { "type": "string" }, "maxItems": 10, "minItems": 0 } } }, "Identification": { "type": "object", "description": "Which existing entity or person satisfies the requested identity, type, and provider scope, how that was settled, and the candidates considered, most probable first.", "properties": { "candidate": { "type": "array", "description": "Records considered, most probable first.", "items": { "$ref": "#/components/schemas/IdentificationCandidate" } }, "created": { "description": "The new unpublished record a NO_MATCH subject with a proven own site was added as, or the existing one that already held its website. Absent otherwise.", "oneOf": [ { "$ref": "#/components/schemas/IdentificationCandidate" }, { "type": "null" } ] }, "detail": { "type": "string", "description": "One sentence naming what settled the answer or what the user must decide." }, "duplicate": { "type": "array", "description": "Other records that appear to describe the same subject as match. Empty when none were found.", "items": { "$ref": "#/components/schemas/IdentificationCandidate" } }, "enrichmentRunId": { "type": [ "string", "null" ], "format": "uuid", "description": "Research request filed for the created record; absent without created, when the lookup did not request research on it, and when the record is already public." }, "languageModelSettled": { "type": [ "boolean", "null" ], "description": "true when the match was settled on a second, slower review; confirm it before relying on it. Absent otherwise." }, "match": { "description": "The matched record when status is MATCHED.", "oneOf": [ { "$ref": "#/components/schemas/IdentificationCandidate" }, { "type": "null" } ] }, "officialUrl": { "type": [ "string", "null" ], "description": "The subject's own website or profile page found in web search; it may be a profile page on another site rather than the subject's own domain." }, "status": { "type": "string", "description": "Use the scoped match, record scoped absence, or refine an ambiguous identity with evidence.", "enum": [ "MATCHED", "NO_MATCH", "NEEDS_REVIEW" ] }, "urlHostForm": { "type": "array", "description": "Fresh backend URL evidence gathered when verifyUrl=true; empty otherwise.", "items": { "$ref": "#/components/schemas/UrlHostFormResolution" } } }, "required": [ "candidate", "detail", "duplicate", "status", "urlHostForm" ], "x-aventure-noun": { "one": "identity lookup", "other": "identity lookups" } }, "JobEnqueue": { "type": "object", "description": "Accepted asynchronous app job enqueue response.", "properties": { "jobId": { "type": "string", "format": "uuid" }, "mode": { "type": "string" }, "statusUrl": { "type": "string", "description": "Endpoint to poll for asynchronous job state and result.", "example": "/v1/jobs/runs/550e8400-e29b-41d4-a716-446655440000" } }, "required": [ "jobId", "mode", "statusUrl" ] }, "EntityDetailBatch": { "type": "object", "additionalProperties": false, "description": "Batch request for entity detail retrieval by id, slug, or current joined URL. Each identifier array accepts at most 200 values, and at most 200 identifiers may be submitted across entityId, slug, and url.", "properties": { "entityId": { "type": "array", "description": "Entity UUID values", "items": { "type": "string", "format": "uuid" }, "maxItems": 200, "minItems": 0 }, "permitMonogram": { "type": [ "boolean", "null" ], "default": true, "description": "Permit monogram fallbacks" }, "slug": { "type": "array", "description": "Entity slug values", "items": { "type": "string" }, "maxItems": 200, "minItems": 0 }, "url": { "type": "array", "description": "Current joined entity URL values", "items": { "type": "string" }, "maxItems": 200, "minItems": 0 } }, "x-aventure-max-total-array-items": 200 }, "PageEntityDetail": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/EntityDetail" } }, "empty": { "type": "boolean" }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "number": { "type": "integer", "format": "int32" }, "numberOfElements": { "type": "integer", "format": "int32" }, "pageable": { "$ref": "#/components/schemas/PageableObject" }, "size": { "type": "integer", "format": "int32" }, "sort": { "$ref": "#/components/schemas/SortObject" }, "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer", "format": "int32" } } }, "EntityDetail": { "type": "object", "description": "\n Full entity detail response: core entity, enrichment, governed research,\n relationships, external identifiers, fundraising, news, people, and sitemap eligibility.\n Core identity and naming fields live under core.\n ", "properties": { "core": { "$ref": "#/components/schemas/Entity", "description": "Core entity identity, naming, status, image, and source metadata." }, "enrichment": { "$ref": "#/components/schemas/EntityEnrichment", "description": "Entity enrichment: addresses, classification, funding summary, text, and URL links." }, "fundraiseRound": { "type": "array", "description": "Fundraise rounds associated with this entity. When newsArticle or an external source reports a newer round not yet listed here, report both and ask the user whether to request a record update via POST /v1/entities/{entityId}/enrichments (CLI: entities enrichments enrich; MCP: aventure_job enrichEntity).", "items": { "$ref": "#/components/schemas/EntityFundraiseTransaction" } }, "newsArticle": { "type": "array", "description": "News articles associated with this entity; full-detail search carries the first few, and GET /v1/news?owner.entityId={entityId} lists them all. When an indexed article reports a newer funding round, role, or milestone not yet reflected in structured fields, report both and offer to request an update on the record.", "items": { "$ref": "#/components/schemas/News" } }, "person": { "type": "array", "description": "People associated with this entity; full-detail search carries the first few, and GET /v1/entities/{entityId}/people lists them all.", "items": { "$ref": "#/components/schemas/PersonDetail" } }, "provider": { "description": "Fund manager firm or product/service provider; null otherwise.", "oneOf": [ { "$ref": "#/components/schemas/EntityProvider" }, { "type": "null" } ] }, "publicUrl": { "type": [ "string", "null" ], "description": "Absolute canonical public URL when this detail has a renderable public route." }, "relationship": { "type": "array", "description": "Entity relationships.", "items": { "$ref": "#/components/schemas/EntityRelationship" } }, "research": { "$ref": "#/components/schemas/EntityResearch", "description": "Combined research disclosure: governed detail rows, snippets, and accelerator participation." }, "sitemap": { "$ref": "#/components/schemas/EntitySitemap", "description": "Sub-route eligibility computed once at the persistence boundary." }, "uniqueId": { "type": "array", "description": "External registry identifiers associated with this entity.", "items": { "$ref": "#/components/schemas/UniqueId" } } }, "required": [ "core", "enrichment", "fundraiseRound", "newsArticle", "person", "relationship", "research", "sitemap", "uniqueId" ], "x-aventure-noun": { "one": "company", "other": "companies" } }, "EntityResolution": { "type": "object", "description": "Resolution of one queried identifier (id, slug, or current joined URL) to its current entity. Echoes the raw input; matched rows carry the full detail, ambiguous rows carry the conflicting candidate ids, missing rows carry neither.", "properties": { "candidateEntityId": { "type": "array", "description": "Entity ids that all currently own the queried URL when status is AMBIGUOUS; empty otherwise. Re-query a single id to disambiguate.", "items": { "type": "string", "format": "uuid", "description": "Canonical entity UUID" } }, "detail": { "description": "Full entity detail when status is MATCHED; absent otherwise.", "oneOf": [ { "$ref": "#/components/schemas/EntityDetail" }, { "type": "null" } ] }, "input": { "type": "string", "description": "Raw identifier exactly as queried (UUID string, slug, or URL)." }, "inputType": { "type": "string", "description": "Which identifier kind this row was queried by.", "enum": [ "ID", "SLUG", "URL" ] }, "status": { "type": "string", "description": "Resolution outcome for this input.", "enum": [ "MATCHED", "AMBIGUOUS", "MISSING" ] } }, "required": [ "candidateEntityId", "input", "inputType", "status" ], "x-aventure-noun": { "one": "identifier resolution", "other": "identifier resolutions" } }, "EntityRelationshipTypeOption": { "type": "object", "description": "Published relationship catalog row. Directional values use sourceRole and targetRole to name sourceEntityId and targetEntityId.", "properties": { "acquisitionManaged": { "type": "boolean", "description": "Whether this type must be written through acquisition endpoints." }, "alias": { "type": "array", "description": "Accepted aliases that normalize to canonical.", "items": { "type": "string" } }, "canonical": { "type": "string", "description": "Canonical relationship type token used in reads and writes." }, "description": { "type": "string", "description": "Human-readable catalog meaning and placement guidance." }, "direction": { "$ref": "#/components/schemas/RelationshipDirection", "description": "How to interpret sourceEntityId and targetEntityId. DIRECTIONAL means sourceRole and targetRole are authoritative." }, "exclusiveRelationshipType": { "type": "array", "description": "Relationship types that cannot coexist for one unordered pair.", "items": { "type": "string" } }, "joinable": { "type": "boolean", "description": "Whether generic relationship join/write endpoints accept this type." }, "pairRule": { "type": "string", "description": "Entity type pairing rule enforced before persistence." }, "readOnly": { "type": "boolean", "description": "Whether this type is emitted by reads only and rejected on writes." }, "sourceRole": { "type": [ "string", "null" ], "description": "Role of sourceEntityId for directional/type-oriented rows. For affinity this is member." }, "targetRole": { "type": [ "string", "null" ], "description": "Role of targetEntityId for directional/type-oriented rows. For affinity this is provider." } }, "required": [ "acquisitionManaged", "alias", "canonical", "description", "direction", "exclusiveRelationshipType", "joinable", "pairRule", "readOnly" ], "x-aventure-noun": { "one": "relationship type", "other": "relationship types" } }, "EntityRelationship": { "type": "object", "description": "Domain record for entity relationships - oriented from the requested entity to the joined entity", "properties": { "asOf": { "type": [ "string", "null" ], "description": "Source-stated effective date, preserving stored precision", "pattern": "^(?!0000)[0-9]{4}(?:-(?:0[1-9]|1[0-2])(?:-(?:0[1-9]|[12][0-9]|3[01])(?:T(?:[01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:\\.[0-9]{1,9})?)?(?:Z|[+-](?:(?:0[0-9]|1[0-7]):[0-5][0-9]|18:00)))?)?)?$" }, "comparisonSignals": { "description": "Competitive comparison signals for the joined entity when it is a product/service provider — sells-to, pricing model, ownership, funding, and website. Null for every other joined entity. Lets comparison surfaces render provider columns without a second per-provider fetch.", "oneOf": [ { "$ref": "#/components/schemas/EntityComparisonSignals" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "detail": { "type": [ "string", "null" ], "description": "Relationship-specific detail. acceleratorParticipant rows use `batch=