> ## 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. # Start discovery for existing market > Add more companies to an existing market using AI-powered discovery process. ## OpenAPI ````yaml post /v2/discovery/{marketId}/start 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/{marketId}/start: post: tags: - Discovery summary: Start discovery for existing market description: >- Add more companies to an existing market using AI-powered discovery process. parameters: - schema: type: number nullable: true description: Unique identifier for the market study. required: false description: Unique identifier for the market study. name: marketId in: path - schema: type: number nullable: true description: Unique identifier for the team to use for this discovery. required: false description: Unique identifier for the team to use for this discovery. name: teamId in: query - schema: type: number nullable: true description: Unique identifier for the collection that the market belongs to. required: false description: Unique identifier for the collection that the market belongs to. name: collectionId in: query requestBody: content: application/json: schema: type: object properties: searchCriteria: 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. count: type: number default: 50 description: Number of results returned for the search criteria. performSearch: type: boolean default: true description: >- Indicates whether the search criteria should be used to perform a search. required: - userPrompt - marketName - marketType - marketRole - keywords - locations pipelineChoices: type: object properties: skipDiscoveryReview: type: boolean default: false description: Skip the discovery review step. runReverseGeocoding: type: boolean default: true description: Run reverse geocoding step. runDunsMapper: type: boolean default: true description: Run DUNS mapper step. runPeople: type: boolean default: true description: Run people step. runNews: type: boolean default: true description: Run news step. runEsg: type: boolean default: true description: Run ESG step. runMomentumScore: type: boolean default: true description: Run momentum score step. runMarketRadar: type: boolean default: false description: Run market radar step. runTopicAnalysis: type: boolean default: true description: Run topic analysis step. runPhraseExplorer: type: boolean default: true description: Run phrase explorer step. runGenerateFeatureMap: type: boolean default: true description: Run generate feature map step. sendPublishEmail: type: boolean default: true description: Run send publish email step. description: Choices for the publish pipeline. required: - searchCriteria examples: ai-transcription-discovery: summary: AI Transcription Discovery description: Example for starting AI transcription services discovery value: searchCriteria: marketName: AI Healthcare Transcription Services userPrompt: >- Find AI-powered transcription services that serve enterprise healthcare customers 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 assertions: null constraints: null projectKind: second_pass performSearch: true locations: - country: GB address: null coordinates: null responses: '200': description: Discovery started successfully, returns the job id and status content: application/json: schema: type: object properties: metadata: type: object properties: marketId: type: number description: Unique identifier for the market study. required: - marketId data: type: array items: type: object properties: jobId: type: number description: >- Unique identifier for the job associated with the market study. workflowId: type: number description: Unique identifier of the workflow. workflowName: type: string description: Name of the workflow associated with the job. startTime: type: string description: Timestamp indicating when the job started. required: - jobId - workflowId - workflowName - startTime required: - metadata - data examples: discovery-started: summary: Discovery Started Response description: Example response when discovery is successfully started value: metadata: marketId: 12345 data: - jobId: 67890 workflowId: 1 workflowName: second_pass startTime: '2024-01-15T10:30:00Z' '400': description: Invalid input provided 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: Invalid input provided '402': description: Payment Required - Team quota exceeded 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: QUOTA_EXCEEDED: value: success: false errorCode: QUOTA_EXCEEDED message: Payment Required - Team quota exceeded '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 '404': description: Not Found 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: NOT_FOUND: value: success: false errorCode: NOT_FOUND message: Not Found '409': description: Conflict 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: CONFLICT: value: success: false errorCode: CONFLICT message: Conflict '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`. ````