--- updatedAt: 2026-06-02T07:06:18.000Z agentTools: projectIndex: https://docs.bavest.co/llms.txt --- # Security Search Aggregated Returns aggregated search results grouped by security type. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Bavest API", "description": "Enterprise-grade REST API for financial market data, analytics, and quantitative portfolio management.\n\n## Categories\n\n| Category | Description |\n|----------|-------------|\n| **Account** | API status and usage quota |\n| **Bulk** | Batch any endpoint across up to 100 symbols/ISINs |\n| **Calendar** | IPO event calendar |\n| **Corporate Actions** | Stock splits, earnings events, transcripts |\n| **Crypto** | Cryptocurrency profiles |\n| **Dividends** | Dividend history, annual summaries, calendar |\n| **Economic Indicators** | Macroeconomic indicators (CPI, GDP, inflation, rates, unemployment) |\n| **Equities** | Company profiles, peers, financial statements, metrics, market cap |\n| **Estimates** | Analyst consensus estimates, recommendations, upgrades/downgrades |\n| **ETFs** | ETF profiles, holdings, sectors, countries, risk, fees, KID |\n| **Forex** | Currency pair quotes and candles |\n| **Funds** | Mutual fund profiles, holdings, sectors, countries, and metrics (NAV, AUM, performance returns) |\n| **News** | Stock-specific and market-wide news |\n| **Bavest QuantOS** | Quantitative portfolio analytics (allocation, stats) |\n| **Reference** | Security search, screener, market indices |\n| **Timeseries Data** | Real-time quotes, end-of-day prices, historical prices, OHLCV candles, NAV |\n| **AI** | MCP server to connect AI agents to all Bavest API endpoints |\n\n## Response Envelope\nAll responses wrap the result in a **data** field.\n\n## Examples\nRequest examples use one security identifier. Clear it before supplying an alternative identifier.\nOptional filters are left blank so that the API's defaults apply; supported values are described beside each parameter.\nResponse examples are snapshots with abbreviated lists, not live quotes. Check each observation's own date for freshness.\n\n## Authentication\nAll requests require an **x-api-key** header. Include it in every request.\n\nKeep your API key secret. Do not expose it in client-side code.\n\n## Rate Limits\nRate limits vary by plan tier. When exceeded, you will receive a 429 Too Many Requests response.\n\n## Versioning\nMajor version in URL path (/v2/). Minor and patch versions are backward-compatible.\n\n## SDKs\nOfficial SDKs are available for Python, TypeScript, and Go.", "version": "2.2.0", "termsOfService": "https://www.bavest.co/en/legal/terms-of-service", "contact": { "name": "Bavest API Support", "url": "https://bavest.co", "email": "support@bavest.co" }, "license": { "name": "Proprietary", "url": "https://bavest.co/terms" }, "x-logo": { "url": "https://bavest.co/logo.png", "altText": "Bavest" } }, "servers": [ { "url": "https://api.bavest.co", "description": "Production API" }, { "url": "https://sandbox.api.bavest.co", "description": "Sandbox (test data)" } ], "security": [ { "apiKey": [] } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-languages": [ "shell", "python", "javascript", "go" ], "parameter-ordering": [ "path", "query", "body", "cookie", "form", "header" ], "metrics-enabled": true }, "tags": [ { "name": "Reference", "description": "Security search and stock screener.\n\nSearch across all asset classes by name, ticker, or ISIN." } ], "paths": { "/v2/reference/search/aggregated": { "get": { "operationId": "reference.searchAggregated", "summary": "Security Search Aggregated", "description": "Returns aggregated search results grouped by security type.", "tags": [ "Reference" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Security name" }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "root_ticker": { "type": "string", "description": "Primary ticker symbol" } } } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "example": { "data": { "results": [ { "name": "Tesla, Inc.", "listings": [ { "symbol": "TL0.DE", "isin": "US88160R1014", "exchange": "XETRA", "type": "ADR", "isEtf": false, "isAdr": true, "isFund": false }, { "symbol": "TSLA", "isin": "US88160R1014", "exchange": "NASDAQ", "type": "EQUITY", "isEtf": false, "isAdr": false, "isFund": false } ], "root_ticker": "TSLA" }, { "name": "Tesla Exploration Ltd.", "listings": [ { "symbol": "TXLZF", "isin": "CA8816011081", "exchange": "PNK", "type": "EQUITY", "isEtf": false, "isAdr": false, "isFund": false } ], "root_ticker": "TXLZF" } ] }, "meta": { "page": 1, "pageSize": 100, "totalPages": 1, "totalCount": 45, "parameters": { "limit": "100", "q": "Tesla" }, "time": 198 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "504": { "$ref": "#/components/responses/GatewayTimeout" }, "default": { "$ref": "#/components/responses/InternalServerError" } }, "parameters": [ { "$ref": "#/components/parameters/acceptJson" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "example": "Tesla" }, "description": "Search query (name, ticker, or ISIN)" }, { "$ref": "#/components/parameters/limitQuery" }, { "$ref": "#/components/parameters/offsetQuery" }, { "$ref": "#/components/parameters/cursorQuery" } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for authentication. Obtain from [bavest.co/dashboard](https://bavest.co/dashboard).", "x-default": "demo_api_key" } }, "parameters": { "limitQuery": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "description": "Maximum number of results to return (default 100, max 1000)" }, "offsetQuery": { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 }, "description": "Number of results to skip for pagination (default 0)" }, "cursorQuery": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor for cursor-based pagination. When provided, returns results after the cursor position. Takes precedence over offset." }, "acceptJson": { "name": "Accept", "in": "header", "required": false, "schema": { "type": "string", "default": "application/json" }, "description": "Response content type. Defaults to `application/json`." } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Missing Authentication Token", "status": "ERROR" } } } }, "NotFound": { "description": "Resource not found.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "The requested security is not found.", "status": "ERROR" } } } }, "RateLimited": { "description": "Rate limit exceeded. Retry after the `Retry-After` header interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Rate limit exceeded. Please retry after cooldown.", "status": "ERROR" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until rate limit resets" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests allowed in current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the rate limit window resets" } } }, "BadRequest": { "description": "Invalid request parameters. Returned when required query parameters are missing, have invalid types, or violate constraints (e.g., providing both symbol and isin when they are mutually exclusive).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Either 'symbol', 'isin', or 'cusip' must be provided.", "status": "ERROR" } } } }, "BadGateway": { "description": "Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Upstream data provider is temporarily unavailable. Please retry after a short delay.", "status": "ERROR" } } } }, "GatewayTimeout": { "description": "The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Request timed out waiting for upstream data provider. Consider narrowing your date range or simplifying the query.", "status": "ERROR" } } } }, "InternalServerError": { "description": "An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Bavest server error.", "status": "ERROR" } } } } }, "headers": { "RequestId": { "schema": { "type": "string", "format": "uuid" }, "description": "Unique request identifier for tracing and debugging. Present on every response.", "example": "550e8400-e29b-41d4-a716-446655440000" } }, "schemas": { "Error": { "type": "object", "description": "Standard error response.\n\nTwo 404 messages exist and they mean different things. \"The requested\nsecurity is not found.\" means the identifier did not resolve. \"No data\navailable for the requested security.\" means it resolved but has no data\nfor this request.\n", "properties": { "message": { "type": "string", "description": "Human-readable error description", "example": "No data available for the requested security." }, "status": { "type": "string", "description": "Error status indicator", "example": "ERROR" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "message", "status" ] }, "ResponseMeta": { "type": "object", "description": "Response envelope metadata. Always present on a 200: `time` is set by\n`core/response.py` on every successful response. Errors carry the same\nblock, built by the same code, so a client parses one meta shape whether\nthe call succeeded or failed.", "properties": { "time": { "type": "integer", "description": "Server-side processing time in milliseconds", "example": 17 }, "parameters": { "type": "object", "additionalProperties": true, "description": "Echo of the request parameters the endpoint resolved", "example": { "symbol": "AAPL" } } } }, "PaginationMeta": { "type": "object", "description": "Response metadata for paginated endpoints. Offset pagination returns\n`page`/`pageSize`/`totalPages`/`totalCount`; cursor pagination returns\n`pageSize`/`hasMore`/`nextCursor` and `totalCount` only when known.", "allOf": [ { "$ref": "#/components/schemas/ResponseMeta" }, { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number (offset pagination)", "example": 1 }, "pageSize": { "type": "integer", "description": "Number of results per page", "example": 50 }, "totalPages": { "type": "integer", "description": "Total number of pages (offset pagination)", "example": 2 }, "totalCount": { "type": "integer", "description": "Total number of results across all pages", "example": 100 }, "hasMore": { "type": "boolean", "description": "Whether more results follow (cursor pagination)" }, "nextCursor": { "type": "string", "nullable": true, "description": "Cursor for the next page (cursor pagination), null on the last page" } } } ] }, "SearchResult": { "type": "object", "description": "Security search result matching the query.\n\n`companyName` and `isActivelyTrading` are returned by `/v2/reference/search`\nonly; the listings under `/v2/reference/search/aggregated` carry the\nidentity fields and the company name sits on the enclosing group.", "required": [ "symbol", "type" ], "properties": { "symbol": { "type": "string", "description": "Ticker symbol", "example": "AAPL" }, "type": { "type": "string", "description": "Asset class of the security (e.g. EQUITY, ETF, ETP, MUTUAL_FUND,\nCLOSED_END_FUND, BOND, ADR, INDEX, CRYPTO_CURRENCY, CURRENCY,\nCOMMODITY, CERTIFICATE).\n\n`EQUITY` und `STOCK` sind im Bestand beide vergeben und meinen\ndasselbe; die Suche vereinheitlicht sie zu `EQUITY` und stellt das\nurspruengliche `STOCK` in `subtype`.", "example": "EQUITY" }, "subtype": { "type": [ "string", "null" ], "description": "Feinere Klassifizierung, sofern vorhanden. Traegt unter anderem das\nurspruengliche `STOCK`, wenn `type` zu `EQUITY` vereinheitlicht wurde.\n`null`, wenn keine feinere Angabe vorliegt.", "example": "STOCK" }, "exchange": { "type": [ "string", "null" ], "description": "Primary listing exchange. `null`, wenn zu dem Papier keine Boerse\ngefuehrt wird, etwa bei OTC-Anleihen ohne Handelsplatz.", "example": "NASDAQ" }, "isin": { "type": [ "string", "null" ], "description": "ISIN code (if available)", "example": "US0378331005" }, "companyName": { "type": "string", "description": "Full company name", "example": "Leverage Shares 3x Apple ETC" }, "isActivelyTrading": { "type": [ "boolean", "null" ], "description": "Whether the security is actively trading. `null`, wenn die Quelle dazu\nnichts sagt; das betrifft vor allem Publikumsfonds, fuer die kein\nHandelsstatus gefuehrt wird (z. B. LU0327386487).", "example": true }, "isAdr": { "type": "boolean", "description": "Whether the security is an American Depositary Receipt", "example": false }, "isEtf": { "type": "boolean", "description": "Whether the security is an ETF", "example": true }, "isFund": { "type": "boolean", "description": "Whether the security is a fund", "example": false }, "isReit": { "type": [ "boolean", "null" ], "description": "Whether the company is a REIT (real estate investment trust): its\nindustry starts with \"REIT\", e.g. Realty Income \"REIT - Retail\".\nNever true for ETFs or funds. `null` when no industry is known.", "example": false } } } } } } ```