~~~ metaphorically speaking ~~~

openapi.yaml

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."
              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."