Below is our OpenAPI specification, which provides a complete definition of the Metaphor API.
openapi: 3.0.0
info:
version: 1.0.0
title: Metaphor Search API
description: A comprehensive API for neural internet-scale search, allowing users to perform queries and retrieve results from a wide variety of sources.
servers:
- url: https://api.metaphor.systems
paths:
/search:
post:
operationId: search
summary: Search
description: Perform a search with a Metaphor prompt-engineered query and retrieve a list of relevant results.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
example: 'Here is an article about the state of search:'
description: "The query string. On the web, people often recommend content - it's vital that the query takes the form of a declarative suggestion, where a high quality search result link would follow."
numResults:
type: integer
example: 10
description: 'Number of search results to return. Default 10. Max 10 for basic plans. Up to thousands for custom plans.'
includeDomains:
type: array
items:
type: string
description: 'List of domains to include in the search. If specified, results will only come from these domains. Only one of includeDomains and excludeDomains should be specified.'
example: ['example.com', 'sample.net']
excludeDomains:
type: array
items:
type: string
description: 'List of domains to exclude in the search. If specified, results will only come from these domains. Only one of includeDomains and excludeDomains should be specified.'
example: ['excludedomain.com', 'excludeme.net']
startCrawlDate:
type: string
format: date-time
description: '"Crawl date" refers to the date that Metaphor discovered a link, which is more granular and can be more useful than published date. If startCrawlDate is specified, results will only include links that were crawled after startCrawlDate. Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)'
example: '2023-01-01'
endCrawlDate:
type: string
format: date-time
description: '"Crawl date" refers to the date that Metaphor discovered a link, which is more granular and can be more useful than published date. If endCrawlDate is specified, results will only include links that were crawled before endCrawlDate. Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)'
example: '2023-12-31'
startPublishedDate:
type: string
format: date-time
description: 'If specified, only links with a published date after startPublishedDate will be returned. Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Note that for some links, we have no published date, and these links will be excluded from the results if startPublishedDate is specified.'
example: '2023-01-01'
endPublishedDate:
type: string
format: date-time
description: 'If specified, only links with a published date before endPublishedDate will be returned. Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Note that for some links, we have no published date, and these links will be excluded from the results if endPublishedDate is specified.'
example: '2023-12-31'
useAutoprompt:
type: boolean
description: 'If true, your query will be converted to a Metaphor query. Latency will be much higher. Default: false'
type:
type: string
description: "The Type of search, 'keyword' or 'neural'. Default: neural"
required:
- query
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
description: 'A list of search results containing title, URL, published date, author, and score.'
items:
$ref: '#/components/schemas/Result'
autopromptString:
type: string
description: 'The Metaphor query created by the autoprompt functionality.'
example:
results:
- title: 'Google Search is Dying'
url: https://dkb.blog/p/google-search-is-dying
publishedDate: '2022-02-14'
author: 'Dmitri Brereton'
id: 'dYQFhHy3tPwMTaBvDFuugg'
score: 0.4
autopromptString: 'Some Metaphor optimized query (this is fake)'
security:
- apikey: []
/findSimilar:
post:
operationId: findSimilar
summary: Find similar links
description: Find similar links to the link provided.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
url:
type: string
example: 'https://slatestarcodex.com/2014/07/30/meditations-on-moloch/'
description: 'The url for which you would like to find similar links'
numResults:
type: integer
example: 10
description: 'Number of search results to return. Default 10. Max 10 for basic plans. Up to thousands for custom plans.'
includeDomains:
type: array
items:
type: string
description: 'An optional list of domain names to include in the search. If specified, results will only come from these domains.'
example: ['example.com', 'sample.net']
excludeDomains:
type: array
items:
type: string
description: 'An optional list of domain names to exclude from the search. If specified, results will not include any from these domains.'
example: ['excludedomain.com', 'excludeme.net']
startCrawlDate:
type: string
format: date-time
description: 'The optional start date (inclusive) for the crawled data. Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). The search will only include results crawled on or after this date.'
example: '2023-01-01'
endCrawlDate:
type: string
format: date-time
description: 'The optional end date (inclusive) for the crawled data. Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). The search will only include results crawled on or before this date.'
example: '2023-12-31'
startPublishedDate:
type: string
format: date-time
description: 'The optional start date (inclusive) for the published data. Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). The search will only include results published on or after this date.'
example: '2023-01-01'
endPublishedDate:
type: string
format: date-time
description: 'The optional end date (inclusive) for the published data. Must be specified in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). The search will only include results published on or before this date.'
example: '2023-12-31'
excludeSourceDomain:
type: boolean
description: 'If true, links from the base domain of the input will be automatically excluded from the results. Default: true'
required:
- url
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
description: 'A list of search results containing title, URL, published date, author, and score.'
items:
$ref: '#/components/schemas/Result'
example:
results:
- title: 'Misperceptions on Moloch'
url: 'https://slatestarcodex.com/2014/08/01/misperceptions-on-moloch/'
publishedDate: '2014-08-01'
author: 'Scott Alexander'
id: 'dYQFhHy3tPwMTaBvDFuugg'
score: 0.3
security:
- apikey: []
/contents:
get:
operationId: getContents
summary: Get contents of documents
description: Retrieve contents of documents based on a list of document IDs.
parameters:
- in: query
name: ids
schema:
type: array
items:
type: string
required: true
description: 'An array of document IDs obtained from either /search or /findSimilar endpoints.'
example: ['31gfpFb2i3Hbsm8nDE33YA', '1aI5kUIO8VuLxT3db47cnM']
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
contents:
type: array
description: 'A list of document contents containing id, URL, title, and extract. In the future, we will support more content types.'
items:
type: object
properties:
id:
type: string
description: 'The ID of the document.'
url:
type: string
format: uri
description: 'The URL of the document, which directs to the web page containing the content.'
title:
type: string
description: 'The title of the document, typically representing the main heading of the content.'
extract:
type: string
description: 'The first 1000 tokens of content in the document. This is designed for current language models to process.'
author:
type: string
description: 'If available, the author of the content. Nullable'
example:
results:
- id: '31gfpFb2i3Hbsm8nDE33YA'
url: https://dkb.blog/p/google-search-is-dying
title: 'Google Search is Dying'
extract: 'Google Search, once the crown jewel of the internet...'
security:
- apikey: []
components:
securitySchemes:
apikey:
type: apiKey
name: x-api-key
in: header
schemas:
Result:
type: object
properties:
title:
type: string
description: 'The title of the search result, typically representing the main heading of the content. If empty, there was likely no HTMl <title> tag in the webpage.'
url:
type: string
format: uri
description: 'The URL of the search result, which directs to the web page containing the relevant content.'
publishedDate:
type: string
nullable: true
description: 'An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD. Nullable'
author:
type: string
nullable: true
description: 'If available, the author of the content. Nullable'
score:
type: number
description: 'A number from 0 to 1 representing similarity between the query/url and the result'
nullable: true
id:
type: string
description: 'The temporary ID for the document. Useful for /contents endpoint.'