> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forestreet.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate search criteria
> Convert natural language queries into structured search criteria for AI-powered company discovery.
## Overview
This endpoint converts your natural language business question into structured search criteria that our AI algorithms
can use to discover relevant companies.
**Workflow Step**: This is Step 1 of the [Market Research
Workflow](/api-reference/guides/platform-discovery#phase-1-search-criteria-generation).
## Usage
The endpoint accepts a simple search input and returns comprehensive search criteria including:
* **Market Classification**: Type, role, and geographic scope
* **Keyword Groups**: Features, users, synonyms, and irrelevant terms
* **Search Parameters**: Count limits, project type, and constraints
## Best Practices
**Pro Tip**: Be specific in your search input. Instead of "AI companies", try "AI-powered transcription services for
enterprise healthcare customers."
**Important**: The generated search criteria will be used in subsequent discovery steps. Take time to review and
potentially refine the criteria before proceeding to company discovery.
## OpenAPI
````yaml post /v2/discovery/search-criteria
openapi: 3.0.0
info:
title: Forestreet API
version: 1.0.0
description: API documentation for Forestreet API
servers:
- url: https://rest.forestreet.com
description: Forestreet API V2 server
security:
- apiKeyAuth: []
- bearerAuth: []
- sessionIdQuery: []
tags: []
paths:
/v2/discovery/search-criteria:
post:
tags:
- Discovery
summary: Generate search criteria
description: >-
Convert natural language queries into structured search criteria for
AI-powered company discovery.
requestBody:
content:
application/json:
schema:
type: object
properties:
searchType:
type: string
enum:
- keywordSearch
- domainSearch
default: keywordSearch
description: Type of search to perform.
searchInput:
type: string
description: Input for the search.
required:
- searchInput
examples:
ai-transcription:
summary: AI Transcription Services
description: Example for finding AI transcription services
value:
searchType: keywordSearch
searchInput: >-
Find AI-powered transcription services that serve enterprise
healthcare customers
responses:
'200':
description: Search criteria generated
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
properties: {}
data:
type: object
properties:
userPrompt:
type: string
description: Prompt used to generate the search criteria.
marketName:
type: string
description: Name of the market associated with the study.
marketType:
type: string
enum:
- service
- product
description: >-
Type classification of the market, such as region or
category.
marketRole:
type: string
enum:
- manufacturer
- distributor
- serviceProvider
- service provider
- consultant
- provider
description: >
Try to limit the companies to ones that fit a specific
role in the market. Possible values are:
- `"manufacturer"` – physical product manufacturing,
e.g. a car manufacturer
- `"distributor"` – physical product distribution,
e.g. a car dealership
- `"service provider"` – contractor or provider of
pre-defined services, e.g. a car repair shop
- `"consultant"` – consultants or advisers not
themselves participating in the market, but offer
advice to those who do, e.g. a motor regulatory
consultant
This is a hint to the discovery process and does not
guarantee that all returned companies will fit this
role. If insufficient companies are found, the search
will be broadened to include other roles.
If not provided, the AI will attempt to infer the role
based on the market name, and assumes `"manufacturer"`
if the market is too broad.
> 💡 It is recommended to write your intended role in
the market name, which the AI will be able to infer
from. Supplying a `marketRole` incompatible with the
market name might degrade the output.
keywords:
type: object
properties:
features:
type: array
items:
type: string
description: Keywords related to the market's features.
user:
type: array
items:
type: string
description: Keywords related to user preferences or behavior.
synonyms:
type: array
items:
type: string
description: Alternative terms related to the market search.
irrelevant:
type: array
items:
type: string
description: >-
Terms identified as irrelevant for the search
criteria.
required:
- features
- user
- synonyms
- irrelevant
description: Grouped keywords associated with the search criteria.
seedDomains:
type: array
items:
type: string
description: List of company domains you already know (if any).
assertions:
nullable: true
description: >-
Assumptions made during the search criteria generation
process.
constraints:
nullable: true
description: >-
Constraints applied to the search criteria generation
process.
locations:
type: array
items:
type: object
properties:
country:
type: string
nullable: true
address:
type: array
nullable: true
items:
type: string
coordinates:
type: array
nullable: true
items:
type: number
minItems: 2
maxItems: 2
required:
- country
description: List of country relevant to the study.
required:
- userPrompt
- marketName
- marketType
- marketRole
- keywords
- locations
required:
- metadata
- data
examples:
ai-transcription-response:
summary: AI Transcription Services Response
description: Example response for AI transcription services search
value:
metadata: {}
data:
userPrompt: >-
Find AI-powered transcription services that serve
enterprise healthcare customers
marketName: AI Healthcare Transcription Services
marketType: service
marketRole: serviceProvider
keywords:
features:
- AI transcription
- speech-to-text
- healthcare
user:
- healthcare
- enterprise
- hospitals
synonyms:
- transcription
- dictation
- voice-to-text
irrelevant:
- manual transcription
- human transcription
seedDomains: []
count: 50
locations:
- country: GB
address:
- 123 Healthcare St
- Suite 100
coordinates:
- 51.5074
- -0.1278
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
INVALID_INPUT:
value:
success: false
errorCode: INVALID_INPUT
message: Bad Request
'401':
description: Unauthorized - User not authenticated
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
UNAUTHORISED:
value:
success: false
errorCode: UNAUTHORISED
message: Unauthorized - User not authenticated
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
FORBIDDEN:
value:
success: false
errorCode: FORBIDDEN
message: Forbidden
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
INTERNAL_SERVER_ERROR:
value:
success: false
errorCode: INTERNAL_SERVER_ERROR
message: Internal Server Error
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Pass a static API key for every request, provided by your customer
support.
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer token authentication, using a sessionId generated by `GET
/v2/auth/session`.
sessionIdQuery:
type: apiKey
in: query
name: sessionId
description: >-
Session ID passed as a query parameter for authentication, provided by
`GET /v2/auth/session`.
````