> ## Documentation Index > Fetch the complete documentation index at: https://docs.istari.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search ## OpenAPI ````yaml /api-reference/openapi.json post /search openapi: 3.1.0 info: title: GOI API description: >- Programmatic access to the ISTARI Global Organization Index (GOI) — search, bulk lookup, aggregations, and location resolution over ~20M verified organizations. Authenticate with the `x-api-key` header. version: v2 servers: - url: https://api.istari.ai/v2 description: GOI API (production) security: - ApiKeyAuth: [] paths: /search: post: summary: Search operationId: search_v1_search_post requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - ApiKeyAuth: [] components: schemas: SearchRequest: properties: similar_to: anyOf: - items: type: string type: array - items: $ref: '#/components/schemas/SimilarToInput' type: array title: Similar To describe: anyOf: - type: string - type: 'null' title: Describe keywords: anyOf: - $ref: '#/components/schemas/KeywordsInput' - type: 'null' filters: anyOf: - $ref: '#/components/schemas/FiltersInput' - type: 'null' excludes: items: type: string type: array title: Excludes columns: items: type: string type: array title: Columns size: type: integer maximum: 500 minimum: 1 title: Size default: 100 min_score: type: number maximum: 1 minimum: 0 title: Min Score default: 0.35 search_balance: type: number maximum: 1 minimum: 0 title: Search Balance default: 0.5 search_after: anyOf: - items: {} type: array - type: 'null' title: Search After explain: type: boolean title: Explain default: false dedup: type: boolean title: Dedup default: false type: object title: SearchRequest SearchResponse: properties: data: items: additionalProperties: true type: object type: array title: Data metadata: $ref: '#/components/schemas/SearchMetadata' type: object required: - data - metadata title: SearchResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SimilarToInput: properties: domain: type: string title: Domain description: >- Domain of the reference company (e.g. 'stripe.com'). The company's embedding becomes the search anchor. boost: items: type: string type: array maxItems: 5 title: Boost description: >- Concept terms whose embeddings are ADDED to the reference. Pushes results toward these concepts. Example: ['B2B', 'enterprise']. penalize: items: type: string type: array maxItems: 5 title: Penalize description: >- Concept terms whose embeddings are SUBTRACTED from the reference. Pushes results away from these concepts. Example: ['consumer', 'B2C']. repel_domains: items: type: string type: array maxItems: 5 title: Repel Domains description: >- Other company domains whose embeddings are subtracted from the reference. Use to exclude a 'flavor' of company by example. weight: type: number title: Weight description: >- Relative weight when multiple similar_to entries are provided. Accepts a number 0.0–2.0 or one of 'weak' (0.5), 'normal' (1.0), 'strong' (2.0). default: 1 type: object required: - domain title: SimilarToInput description: |- Reference company for vector-similarity ('find similar to X') search. Accepts a domain plus optional embedding arithmetic: terms in `boost` are added to the reference embedding, `penalize` are subtracted, and `repel_domains` push results away from those other companies. Used by /v1/search when `similar_to` is provided. KeywordsInput: properties: must_all: items: type: string type: array title: Must All description: >- Terms that must ALL appear in the company description (AND logic). Example: ['open banking', 'API']. must_any: items: type: string type: array title: Must Any description: >- Terms where ANY ONE must appear (OR logic). Example: ['fintech', 'payments', 'banking']. must_not: items: type: string type: array title: Must Not description: >- Terms that must NOT appear in the company description. Requires must_all or must_any to also be set. type: object title: KeywordsInput description: |- BM25 / fulltext keyword filter applied to the company description. Combines three lists with AND / OR / NOT logic. At least one positive list (must_all or must_any) is required when must_not is set — BM25 cannot match on pure negation. FiltersInput: properties: country: anyOf: - items: type: string type: array - type: 'null' title: Country description: >- Country name(s), OR-combined. Examples: ['Germany'], ['Germany', 'Austria', 'Switzerland']. state: anyOf: - items: type: string type: array - type: 'null' title: State description: >- State / Bundesland name(s). Native spelling (e.g. 'Bayern'). Use /v1/locations/search to look up exact spellings. region: anyOf: - items: type: string type: array - type: 'null' title: Region description: Region (admin level between state and district). Native spelling. district: anyOf: - items: type: string type: array - type: 'null' title: District description: District / Landkreis. Native spelling. municipality: anyOf: - items: type: string type: array - type: 'null' title: Municipality description: Municipality / Stadt / Gemeinde. Native spelling. organization_type: anyOf: - items: type: string type: array - type: 'null' title: Organization Type description: >- Filter by organization type. Valid values: "Company", "Startup", "Public", "Academic", "Other" organization_size: anyOf: - items: type: string type: array - type: 'null' title: Organization Size description: >- Filter by organization size. Valid values: "Micro (0-9)", "Small (10-49)", "Medium-sized (50-249)", "Large enterprise (250+)" nace_code: anyOf: - items: type: string type: array - type: 'null' title: Nace Code description: >- Filter by NACE section code. Valid values: "NACE A: Agriculture, forestry and fishing", "NACE B: Mining and quarrying", "NACE C: Manufacturing", "NACE D: Electricity, gas, steam and air conditioning supply", "NACE E: Water supply; sewerage, waste management and remediation activities", "NACE F: Construction", "NACE G: Wholesale and retail trade", "NACE H: Transportation and storage", "NACE I: Accommodation and food service activities", "NACE J: Publishing, broadcasting, and content production and distribution activities", "NACE K: Telecommunication, computer programming, consulting, computing infrastructure and other information service activities", "NACE L: Financial and insurance activities", "NACE M: Real estate activities", "NACE N: Professional, scientific and technical activities", "NACE O: Administrative and support service activities", "NACE P: Public administration and defence; compulsory social security", "NACE Q: Education", "NACE R: Human health and social work activities", "NACE S: Arts, sports and recreation", "NACE T: Other service activities", "NACE U: Activities of households as employers and undifferentiated goods- and service-producing activities of households for own use", "NACE V: Activities of extraterritorial organisations and bodies" source: anyOf: - items: type: string type: array - type: 'null' title: Source description: >- Filter by data source. Valid values: "register", "cache", "request", "goi_02_2026" company_register_court: anyOf: - items: type: string type: array - type: 'null' title: Company Register Court description: >- Filter by court of registration. Matches a company if any of its registrations is at one of the given courts (not just the primary). register_date_from: anyOf: - type: string format: date - type: 'null' title: Register Date From description: >- Filter by registration date >= this date. Matches if any of the company's registrations is on/after this date. ISO format: YYYY-MM-DD. register_date_to: anyOf: - type: string format: date - type: 'null' title: Register Date To description: >- Filter by registration date <= this date. Matches if any of the company's registrations is on/before this date. When combined with company_register_court, both predicates must apply to the same registration. ISO format: YYYY-MM-DD. summary_keywords: anyOf: - items: type: string type: array - type: 'null' title: Summary Keywords description: >- Exact-match filter on each company's auto-extracted keyword tags (array containment — a company matches only if its summary_keywords contain ALL the values you pass). Discover valid values via /v1/stats with group_by='summary_keywords' on a narrower slice. text_keywords: anyOf: - $ref: '#/components/schemas/KeywordsInput' - type: 'null' description: >- Strict BM25 WHERE filter on company description — combines AND / OR / NOT the same way as a search keywords argument. Not supported in /v1/stats. type: object title: FiltersInput description: |- Column-level filters applied to org rows. Geographic fields use GADM-native names (e.g. 'Bayern' not 'Bavaria'). All list-valued filters are OR-combined within the field. Values across different fields are AND-combined. SearchMetadata: properties: total_hits: anyOf: - type: integer - type: 'null' title: Total Hits description: >- Total matches found before pagination/dedup. May be null if the search engine couldn't compute a cheap total (e.g. some vector modes). returned: type: integer title: Returned description: Number of rows in this response after limits and dedup. mode: type: string title: Mode description: >- Auto-detected search mode: 'vector_similarity', 'semantic', 'fulltext', 'hybrid', or 'filter'. elapsed_ms: type: integer title: Elapsed Ms description: Search execution time in milliseconds. search_after: anyOf: - items: {} type: array - type: 'null' title: Search After description: >- Opaque pagination cursor. Pass back verbatim in the next request's `search_after` to fetch the next page. Null if no more results. filters_applied: anyOf: - additionalProperties: true type: object - type: 'null' title: Filters Applied description: >- Echo of the column filters that were applied (after scope/normalization). explain_plan: anyOf: - items: type: string type: array - type: 'null' title: Explain Plan description: >- EXPLAIN ANALYZE output lines when `explain=true` was requested, else null. type: object required: - total_hits - returned - mode - elapsed_ms title: SearchMetadata description: Diagnostics returned alongside /v1/search results. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Your GOI API key. Create one on the GOI dashboard under API keys. ````