> ## Documentation Index > Fetch the complete documentation index at: https://docs.metal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search deals > Returns deals ranked by relevance to a query. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/deals/search openapi: 3.1.0 info: title: Metal API version: 1.0.0 description: >- REST API for Metal, the AI context layer for financial firms. Manage companies, deals, people, documents, activities, enrichments, scores, screenings, lists, workflows, and more. All endpoints are versioned under /v1, return JSON, and are scoped to the organization that owns your API key. contact: name: Metal Support email: support@metal.ai url: https://www.metal.ai servers: - url: https://api.metal.ai description: Production security: - MetalClientId: [] MetalApiKey: [] tags: - name: API keys description: Create, list, and revoke API keys. - name: Companies description: Manage and enrich companies. - name: Deals description: Track opportunities through your pipeline. - name: People description: Manage contacts and relationships. - name: Documents description: Search and retrieve ingested documents. - name: Activities description: Log and search meetings, calls, and other interactions. - name: Enrichments description: Read and write enriched property values on resources. - name: Scores description: Score companies and deals against scoring frameworks. - name: Screenings description: Run and manage AI-powered company screenings. - name: Lists description: Organize and enrich resources in bulk. - name: Tags description: Label companies, deals, and lists. - name: Industries description: Manage your organization's industry taxonomy. - name: Sectors description: Manage sectors within an industry. - name: Subsectors description: Manage subsectors within a sector. - name: Workflows description: Run and monitor AI workflows. - name: Data description: Query time-series metrics and observations. - name: Teams description: Manage deal teams and their members. - name: Workspaces description: Organize documents and data by workspace. paths: /v1/deals/search: post: tags: - Deals summary: Search deals description: Returns deals ranked by relevance to a query. operationId: searchDeals parameters: - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit400Clamped' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' responses: '200': description: Ranked deal results. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Deal' metadata: $ref: '#/components/schemas/PaginationMetadata' '401': $ref: '#/components/responses/Unauthorized' components: parameters: SearchPage: name: page in: query description: >- Page number, starting at 1. The deep offset `(page - 1) * limit` cannot exceed 10,000. required: false schema: type: integer default: 1 minimum: 1 SearchLimit400Clamped: name: limit in: query description: Results per page. Requests above 400 are clamped to 400. required: false schema: type: integer default: 100 minimum: 1 maximum: 400 schemas: SearchRequest: type: object description: >- Search text, structured filters, and ranking options. Pass pagination through the `page` and `limit` query parameters. properties: text: type: string description: Free-text query ranked against the resource's searchable fields. example: industrial automation suppliers filters: $ref: '#/components/schemas/SearchFilters' sort: type: array description: Ordered sort fields. items: $ref: '#/components/schemas/SearchSortField' hybrid: type: boolean description: >- Enables hybrid semantic and keyword ranking on endpoints that support it. default: false fuzzy: type: boolean description: >- Enables approximate text matching on supported keyword-search paths. Document search and company hybrid search ignore this flag; activity search uses it only when `fullText` is false. default: false fullText: type: boolean description: Enables word-level matching on endpoints that support it. default: false Deal: type: object properties: id: type: string example: 665f1c2a9b1e4a0012a3b4c5 name: type: string example: Project Atlas companyId: type: string description: The target company's id. status: type: string enum: - ACTIVE - CLOSED - PASSED_DEAD description: Internal lifecycle status. example: ACTIVE stage: type: string enum: - SOURCED - SCREENED - IOI_TERM_SHEET - DUE_DILIGENCE - IC_MEETING - DEAL_CLOSING - PORTFOLIO_COMPANY - REALIZED - PASSED - DEAD description: Pipeline stage. example: DUE_DILIGENCE externalStatus: type: string description: Your firm's custom status label, when configured. externalStage: type: string description: Your firm's custom stage label, when configured. acquisitionType: type: string enum: - add_on - platform readOnly: true description: >- Derived, read-only classification of the deal. `add_on` if the deal has a platform company (an add-on acquisition under an existing portfolio company), otherwise `platform`. Computed on read from the deal's platform company; cannot be set via create, update, or any other write endpoint. example: platform owners: type: array items: $ref: '#/components/schemas/Reference' sector: type: string industry: type: string size: type: number notes: type: string externalReference: $ref: '#/components/schemas/ExternalReference' PaginationMetadata: type: object description: Pagination details returned by search endpoints. properties: page: type: integer example: 1 limit: type: integer example: 20 totalCount: type: integer example: 134 totalPages: type: integer example: 7 SearchFilters: type: object description: Structured predicates grouped with `and` and `or`. properties: and: type: array items: $ref: '#/components/schemas/SearchFilterClause' or: type: array items: $ref: '#/components/schemas/SearchFilterClause' SearchSortField: type: object required: - field - order properties: field: type: string order: type: string enum: - asc - desc Reference: type: object description: A reference to another resource, such as a user or team. properties: id: type: string type: type: string description: The referenced resource type, e.g. "user" or "team". ExternalReference: type: object description: A structured reference to a record in an external source system. properties: source: type: string description: The external system, e.g. a CRM provider. id: type: string description: The record id in the external system. Error: type: object properties: error: type: string description: A human-readable error message. SearchFilterClause: type: object description: A field predicate or nested boolean group. properties: field: type: string description: Indexed field to filter. Available fields vary by resource. operator: type: string description: >- Filter operator, such as `eq`, `neq`, `match`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `exists`, or `missing`. value: description: Comparison value. Omit it for `exists` and `missing`. and: type: array items: $ref: '#/components/schemas/SearchFilterClause' or: type: array items: $ref: '#/components/schemas/SearchFilterClause' responses: Unauthorized: description: Missing or invalid API key credentials. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid api key or clientId securitySchemes: MetalClientId: type: apiKey in: header name: x-metal-client-id description: The Client ID of your API key. x-default: MetalApiKey: type: apiKey in: header name: x-metal-api-key description: The secret value of your API key. x-default: ```` ## Related topics - [MCP tools reference](/mcp/tools-reference.md) - [Search companies, deals, people, documents, and activities](/guides/search.md) - [Metal MCP server](/mcp/overview.md) - [Search documents](/api-reference/documents/search-documents.md) - [Search activities](/api-reference/activities/search-activities.md)